Get Completed Timecards

Applies to: Labor API | Team API | Locations API

Learn how to get all closed timecards (shifts) for the workweek 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 at least one CLOSED timecard (shift) to receive any SearchTimecards results. 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 completed timecards, the status field is set to CLOSED and an end_at timestamp is defined. To learn how to start and end a timecard, see Start and End Timecards.

The following SearchTimecards example uses supported filter and sort criteria to search for all completed timecards for a specified location and pay period:

• The targeted pay period is May 12, 2025, through May 19, 2025.
• The results are sorted using the shift creation timestamp in ascending order.
• The results are limited to 20 shifts per response (page size).

The limit in the previous SearchTimecards request defines a page size of 20 (default 200, maximum 200). If more results are available, the response includes a cursor that you use to get the next page of results. 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.