Applies to: Labor API
Learn how to get details for the shift you want to update, get available break types, and add a break to the shift using the Labor API.
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 require the TIMECARDS_WRITE, TIMECARDS_READ, and TIMECARDS_SETTINGS_READ permissions to perform these steps. When calling Square APIs in the production environment, change the base URL to https://connect.squareup.com.
You need an open shift to update - To learn how to create a shift, see Start the shift.
Important
A shift is complete when it has a start time and end time. If a team member takes breaks during a shift, the shift must be updated with each break including start and end times for the breaks taken. The steps in this topic show how to update a shift when a break starts and ends.
1. Get the shift you want to update
To get details about the target shift, call GetShift and specify the shift ID.
Note
If you don't have the shift ID, you can call SearchShifts using supported filters to get details about the target shift instead of calling GetShift.
The response returns the Shift object that matches the specified shift ID. For example:
{
"shift": {
"id": "3DBHNF9E8CG27",
"team_member_id": "aq8XS-F0-VA0UrgH6h3w",
"employee_id": "aq8XS-F0-VA0UrgH6h3w",
"location_id": "89EKRBA8A0BET",
"timezone": "America/Los_Angeles",
"start_at": "2018-10-05T04:00:00-08:00",
"wage": {
"title": "Bartender",
"hourly_rate": {
"amount": 1050,
"currency": "USD"
},
"job_id": "J4e3B7nyVA3QfMdnU1BkEfjP",
"tip_eligible": true
},
"declared_cash_tip_money": {
"amount": 0,
"currency": "USD"
},
"status": "OPEN",
"version": 1,
"created_at": "2019-02-20T01:28:49-08:00",
"updated_at": "2019-02-20T01:28:49-08:00"
}
}
You'll use these shift details when you update the shift in a later step.
2. Get available break types
To get details about available break types, call ListBreakTypes.
The response returns an array of BreakType objects.
{
"break_types": [
{
"id": "3X212GX9NDJA9",
"location_id": "89EKRBA8A0BET",
"break_name": "Breakfast",
"expected_duration": "PT20M",
"is_paid": true,
"version": 1,
"created_at": "2019-02-20T17:57:41Z",
"updated_at": "2019-02-20T17:57:41Z"
},
{
"id": "Y32XW5N9JHHW3",
"location_id": "89EKRBA8A0BET",
"break_name": "2nd Breakfast",
"expected_duration": "PT15M",
"is_paid": true,
"version": 1,
"created_at": "2019-02-20T18:06:07Z",
"updated_at": "2019-02-20T18:06:07Z"
}
]
}
For businesses that have more than one location, you can filter the ListBreakTypes request by a particular location.
3. Add the break to the shift
When the break starts, call UpdateShift to add a new break to the breaks field in the shift. Specify the start_at time of the break and the name, break_type_id, expected_duration, and is_paid fields that corresponding to the break type.
Important
If the optional version field is included in the request but the specified value doesn't equal the current version of the Shift object you're updating, the update fails and you receive an error. This typically happens because a different client endpoint updated the same shift after your application retrieved the shift. To resolve the error, get the updated shift by restarting the workflow from step 1.
The response returns the updated Shift object with the break you added and an incremented version number. For example:
{
"shift": {
"id": "3DBHNF9E8CG27",
...
"breaks": [
{
"id": "42AWYR29PYV52",
"start_at": "2018-10-16T04:00:00-08:00",
"break_type_id": "Y32XW5N9JHHW3",
"name": "2nd Breakfast",
"expected_duration": "PT15M",
"is_paid": true
}
],
"status": "OPEN",
"version": 2,
...
}
}
When the shift ends, call UpdateShift again and update the break with the end_at time. Make sure to specify the latest version number of the shift.
The response returns the updated Shift object with the updated break and incremented version number. For example:
{
"shift": {
"id": "3DBHNF9E8CG27",
...
"breaks": [
{
"id": "42AWYR29PYV52",
"start_at": "2018-10-16T04:00:00-08:00",
"end_at": "2018-10-16T04:14:20-08:00",
"break_type_id": "Y32XW5N9JHHW3",
"name": "2nd Breakfast",
"expected_duration": "PT15M",
"is_paid": true
}
],
"status": "OPEN",
"version": 3,
...
}
}