Add Breaks to a Shift

Learn how to get details for the shift you want to update, get available break types, and add a break to the shift.

Applies to: Labor API

Link to section

Before you start

  • 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

  • You need an open shift to update - To learn how to create a shift, see Start the shift.


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.

Link to section

Step 1: Get details for the shift you want to update

To get details about the target shift, call GetShift and specify the shift ID.

Get shift


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:

You'll use these shift details when you update the shift in a later step.

Link to section

Step 2: Get available break types

To get details about available break types, call ListBreakTypes.

List break types

The response returns an array of BreakType objects.

For businesses that have more than one location, you can filter the ListBreakTypes request by a particular location.

Link to section

Step 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.

Update shift


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:

Link to section

Step 4: End the shift break

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.

Update shift

The response returns the updated Shift object with the updated break and incremented version number. For example: