Applies to: Labor API | Team API | Locations API
Learn how to integrate the Labor API into your application to record team member work hours.
Use the Labor API to record shifts worked by team members, including the shift's start and end times, job title, pay rate, and breaks. Shift records can be used for payroll, labor cost reporting, and overtime management and to inform scheduling decisions.
The basic steps for recording shifts include starting a shift for a team member (with a job title and pay rate) and ending the shift.
Requirements and limitations
You need a valid access token - The steps in this topic call Square APIs in the Square Sandbox, so you can use your Sandbox access token in the requests. Square recommends testing with Sandbox credentials when possible.
Applications that use OAuth access tokens in the production environment require the MERCHANT_PROFILE_READ, EMPLOYEES_READ, TIMECARDS_READ, and TIMECARDS_WRITE permissions to perform these steps. When calling Square APIs in the production environment, change the base URL to https://connect.squareup.com.
You need a team member with an assigned wage setting - To create a shift, you must provide the ID of a team member who's active at the shift location. If needed, you can create and set up a team member using the Square Dashboard or Team API.
To start a shift, first get the location ID, team member ID, and wage information and verify that the team member doesn't have an OPEN shift. Then, create a shift by providing the start time and the information you collected.
1. Get the shift location
If needed, call ListLocations to get the ID of the shift location.
Call SearchTeamMembers to get active team members for a location using the location_ids and status query filters.
The limit in the example request defines a page size of 3. The default is 100 and the maximum is 200. If the response includes a cursor field, append the cursor to your previous request and resend it to retrieve the next page of results. Repeat this process until the response no longer contains a cursor. For more information, see Pagination.
3. Get wage information for the team member
Call ListTeamMemberWages using the team_member_id query parameter to get jobs and pay rates for the team member. A team member might have multiple jobs, so you need to find the job title and pay rate for the job to be done on the shift.
4. Check for an open shift record
Call SearchShifts to search for an OPEN shift for the team member using the status, team_member_ids, and location_ids query filters. A team member can have only one open shift at a time.
Call CreateShift to create a shift using information you copied in previous steps. Provide the location ID and team member ID, and for the wage field, provide the job title, pay rate, and tip eligibility. The start_at field can be set to local time or GMT. If you use GMT, Square calculates the local time based on the shift location.
If the shift is successfully created, Square invokes the labor.shift.created webhook event.
Important
To record labor cost, you must include the wage.hourly_rate field. Otherwise, the shift record has no associated pay amount. The job title and pay rate from the team member's primary job aren't used by default.
To end a shift, first get the shift ID and verify that all breaks are ended. Then, update the shift with the end time.
1. Get the shift to close
Call SearchShifts to get the open shift for the team member using the status, team_member_ids, and location_ids query filters.
2. Verify that any breaks are ended
Inspect the shift for a breaks field, which is added to a shift if the team member took any breaks. If you're following the steps in this topic, you shouldn't see this field because no breaks were recorded.
If the shift does include the breaks field, confirm that each break contains an end_at field with a valid timestamp. If the shift has an open break, you need to end the break before you can end the shift.
To close a shift, call UpdateShift and add an end_at field to the shift.
If the shift is successfully updated, Square invokes the labor.shift.updated webhook event.
Note that you can update the wage or declared_cash_tip_money field for a shift at any time.