Use the Labor API to manage time tracking and scheduling for team members. Time-tracking features let you manage timecards to record hours worked (including breaks, wages, and declared cash tips) for labor cost reporting, payroll, and overtime management. Scheduling features let you manage team schedules using draft and published scheduled shifts.
In addition to calling the Labor API using REST calls or Square SDKs, developers can send GraphQL queries to get labor data in fewer, more compact data transfers. Developers can also subscribe to be notified about labor webhook events.
Note
The Labor API defines two types of shifts; be careful not to confuse them:
A ScheduledShift is used to manage team schedules.
A Shift is used for payroll time tracking. Shift is deprecated and replaced by Timecard.
Link to section
Time tracking
Use the Labor API to track actual hours worked by team members:
The Labor API integrates directly with the following Square APIs:
Team API for team member, job, and wage management.
Locations API for location management, such as setting the location's time zone.
Applications can also integrate with these and other Square APIs for custom use cases, such as advanced operational analytics and reporting.
Link to section
Migration notes
The following migration notes apply to the Labor API.
Link to section
Deprecated Shift endpoints, data types, and webhooks
Deprecated in version: 2025-05-21 Retired in version: 2026-05-21
The Shift object is renamed to Timecard in Square API version 2025-05-21.
As part of this process, all Shift endpoints (/v2/labor/shifts/...) are replaced by Timecard endpoints (/v2/labor/timecards/...) that provide the same functionality. In addition, all Shift-related data types and webhook events are deprecated and replaced by new Timecard equivalents. For a complete list, see Deprecated Shift items.
Shift and Timecard endpoints operate on the same resources. For example, both SearchShifts and SearchTimecards return the same set of resources in the results. However, they're returned as Shift objects in the SearchShifts response and Timecard objects in the SearchTimecards response.
At retirement, Shift endpoints become unavailable to all applications and return 410 GONE errors regardless of the Square-Version header in the request. Applications must migrate before the retirement date to avoid disruption.
The following examples show the request and response format changes for each endpoint pair.
Changes:
shift is renamed to timecard in the request and response.
employee_id (deprecated) isn't supported in the request or returned in the response.
Create shift
Create timecard
Changes:
shift is renamed to timecard in the response.
employee_id (deprecated) isn't returned in the response.
Get shift
Retrieve timecard
Changes:
match_shifts_by in the workday filter is renamed to match_timecards_by.
employee_ids (deprecated) isn't a supported filter in the request.
shifts is renamed to timecards in the response.
employee_id (deprecated) isn't returned in the response.
Search shifts
Search timecards
Changes:
shift is renamed to timecard in the request and response.
employee_id (deprecated) isn't supported in the request or returned in the response.
Update shift
Update timecard
Delete shift
Delete timecard
The following tables map deprecated Shift endpoints, data types, and webhook events to their Timecard replacements. Timecard replacements are available in Square API version 2025-05-21 and later.
Until Shift endpoints are retired, operations on a Shift or Timecard object triggers events for both resource types. For example, a successful CreateShift or CreateTimecard request triggers both labor.shift.created and labor.timecard.created events. Note that the new shift and new timecard have the same ID.
To avoid receiving duplicate notifications (with different event IDs) for the same operation, subscribe to only one event type.