Add Breaks to Timecards

Applies to: Labor API | Webhooks

Learn how to get details for the timecard (shift) you want to update, get available break types, and add a break to the timecard using the Labor API.

• Square API version - Square API version 2025-05-21 or later is required to call Timecard endpoints. The Shift object and related endpoints, data types, and webhook events are deprecated and replaced by Timecard equivalents. For more information, see Migration notes.

• Valid access token - Square API requests require an Authorization header with a bearer access token. The examples in this topic use the Square Sandbox, so you can test using your Sandbox access token.

  Link to section

  More details

  Applications using OAuth access tokens to authorize requests typically require the following permissions for timecard management:

  • MERCHANT_PROFILE_READ to retrieve location information.
  • EMPLOYEES_READ to retrieve team member, job, and wage information.
  • TIMECARDS_READ and TIMECARDS_WRITE to retrieve and manage timecards (shifts).
  • TIMECARDS_SETTINGS_READ and TIMECARDS_SETTINGS_WRITE to retrieve and manage break types and workweek settings.

  To call Square APIs in the production environment, change the base URL to https://connect.squareup.com and use your production (personal) access token.

• A timecard for testing - For this exercise, you need an OPEN timecard (shift) to add a break to. In addition, you must create a break type that defines the break.

  A timecard is a record of the hours worked by a team member for a single shift on a specific day, including breaks, declared cash tips, and wage information. For open timecards, the status field is set to OPEN and there's no end_at timestamp. To learn how to create a timecard, see Start and End Timecards.

To get details about the target timecard, call RetrieveTimecard and specify the timecard ID. If you don't have the timecard ID, call SearchTimecards using supported filters to get the timecard.

The timecard is updated each time the team member takes a break during the shift.

To get details about available break types, call ListBreakTypes. For businesses with more than one location, you can filter by location_id.

When the break starts, call UpdateTimecard to add the break to the Timecard.breaks field. Specify the start_at time of the break, as well as the name, break_type_id, expected_duration, and is_paid fields that correspond to the break type.

Updating a timecard triggers a labor.timecard.updated webhook event.

When the break ends, call UpdateTimecard again and update the break with the end_at time. Make sure to specify the latest version number of the timecard.

Updating a timecard triggers a labor.timecard.updated webhook event.