Applies to: Labor API | Team API | Locations API | Webhooks | GraphQL
Learn how to manage team schedules using the Labor API.
The Labor API provides scheduling capabilities that let third-party scheduling applications integrate with Square. You can manage team member schedules, synchronize schedule data between external systems and Square, and access data for labor forecasting, labor cost reporting, and optimizing staffing levels. The API supports:
- Creating draft and published schedules.
- Managing shift assignments and changes.
- Searching scheduled hours by status, team member, and other parameters.
- Notifying team members about schedule updates.
Whether you're creating a standalone scheduling application or integrating with the Square Dashboard and Square Team application, you can use the Labor API to manage scheduled shifts.
Note
The Labor API defines two types of shifts; be careful not to confuse them:
- A
ScheduledShiftis used to manage team schedules. - A
Shiftis used for payroll time tracking.Shiftis deprecated and replaced byTimecard.
The following requirements and limitations apply when managing scheduled shifts using the Labor API.
- Square API version 2025-05-21 or later is required to access or manage scheduled shifts.
- The ability to schedule repeated shifts using templates isn't supported.
- Scheduled shifts created by the API are visible in the Staff section of the Square Dashboard under Scheduling and in the Square Team application. Note the following:
Sellers must use team permissions in the Shifts category to allow other team members to access draft shifts. Published shifts are accessible by all team members.
Some scheduling features require that the seller has an active Shifts Plus subscription. For example, shifts that are scheduled more than 10 days in advance using the Labor API are visible in the Square Dashboard to sellers without a subscription but these shifts cannot be updated.
Note
The Labor API provides unrestricted access to schedule management, so these requirements don't apply to third-party scheduling applications.
The color scheme for a scheduled shift cannot be changed. This property isn't exposed on the
ScheduledShiftobject.
See additional requirements and limitations for managing scheduled shifts.
Team schedules are made up of individual scheduled shifts spanning a given time period. To create a scheduled shift, first provide draft shift details such as the job ID, location ID, team member assignment, and start and end times. You can update draft shift details as needed and then publish the shift to make your changes public.
The following diagram shows the API call flow for managing a scheduled shift and the webhook events triggered by each request:
The simplest flow is from create to publish, but you can iteratively update and publish or republish. For more information about these flows, see Manage Scheduled Shifts.
*If the shift was never published, setting draft_shift_details.is_deleted to true in an UpdateScheduledShift request deletes the shift. Otherwise, the shift is just marked for deletion and you must publish the change to delete it.
Note
The diagram doesn't include calls used to obtain the location_id, team_member_id, and job_id from other Square APIs or calls to RetrieveScheduledShift and SearchScheduledShifts for retrieving information about a scheduled shift.
The following key concepts apply to scheduling with the Labor API:
You work with two primary objects for shift management:
- ScheduledShift - A specific time slot in a work schedule. This object is used to manage the draft and published versions of a shift:
draft_shift_details- Stores the latest draft shift details.published_shift_details- Stores the current published shift details. This field is initially added when the scheduled shift is first published and then updated with every subsequent published version.After the initial publish, you can determine whether there are unpublished changes by comparing
draft_shift_detailstopublished_shift_details.
- ScheduledShiftDetails - The data type for the
draft_shift_detailsandpublished_shift_detailsfields of aScheduledShift. The following fields are required:location_id,job_id,start_at, andend_at.
Only the latest draft shift details and current published shift details are accessible for a scheduled shift.
Draft shift details are writable using the CreateScheduledShift and UpdateScheduledShift endpoints.
To change the details for a published shift:
Call
UpdateScheduledShiftand provide the updateddraft_shift_details.Call
PublishScheduledShiftorBulkPublishScheduledShiftsto make the changes public.When a scheduled shift is published, Square copies
draft_shift_detailstopublished_shift_details.
The PublishScheduledShift and BulkPublishScheduledShifts endpoints provide a scheduled_shift_notification_audience parameter that lets you control whether Square notifies team members about new, changed, or deleted shifts.
Notifications can be sent to affected team members only (default) or all active team members, or you can choose not to send notifications. Notifications are sent to the email address on record for team members.
The Labor API provides a set of endpoints used for managing team schedules. Applications using OAuth to authorize API requests require the TIMECARDS_WRITE or TIMECARDS_READ permission to call scheduling endpoints.
Use the following endpoints to create and manage scheduled shifts.
| Endpoint | Permission | Description |
|---|---|---|
| CreateScheduledShift | TIMECARDS_WRITE | Creates a scheduled shift by providing draft shift details such as job ID, team member assignment, and start and end times. |
| UpdateScheduledShift | TIMECARDS_WRITE | Updates the draft shift details for a scheduled shift. |
| PublishScheduledShift | TIMECARDS_WRITE | Publishes a scheduled shift to make the current draft details visible to all team members. |
| BulkPublishScheduledShifts | TIMECARDS_WRITE | Publishes 1 – 100 scheduled shifts to make the current draft details visible to all team members. |
Use the following endpoints to retrieve and search scheduled shifts.
| Endpoint | Permission | Description |
|---|---|---|
| RetrieveScheduledShift | TIMECARDS_READ | Retrieves a scheduled shift by ID. |
| SearchScheduledShifts | TIMECARDS_READ | Retrieves a paginated list of scheduled shifts, with optional filter and sort settings. |
Note
You can use the scheduledShifts entry point in Square GraphQL queries to access scheduling data through read-only operations. GraphQL queries can improve performance and reduce development time by letting you request exactly the data you need in fewer, more compact data transfers.