Retrieve Scheduled Shifts

Applies to: Labor API | Team API | Locations API

Use the Labor API to search and retrieve scheduled shifts with flexible filtering options.

Applications can use the Labor API to search and retrieve scheduled shifts. You can search shifts using various filters, including date ranges, locations, team members, assignment status, and published status.

The following requirements and limitations apply when retrieving scheduled shifts using the Labor API.

• Square API version - Square API version 2025-05-21 or later is required to access or manage scheduled shifts.

• 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 when working with team schedules:

  • MERCHANT_PROFILE_READ to retrieve location information.
  • EMPLOYEES_READ to retrieve team member and job information.
  • TIMECARDS_READ to retrieve scheduled shifts.
  • TIMECARDS_WRITE to create, update, and publish scheduled shifts.

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

To retrieve a specific scheduled shift, call RetrieveScheduledShift and provide the shift ID.

To search for scheduled shifts, call SearchScheduledShifts with optional filter and sort settings. By default, results are sorted by start_at in ascending order.

To list all scheduled shifts, call SearchScheduledShifts without any filters:

Use the optional limit field to control the page size (default 50, maximum 50) and the cursor field to page through the results. For more information, see Pagination.

The following filter options can be used in a search query. Multiple filters in a query are combined as an AND operation, which means shifts must match all specified filters to be included in the results. For information about how some filters interact, see Filter combinations.

Use the following fields to sort the query. By default, results are sorted by START_AT and ASC.

The workday filter provides a way to search scheduled shifts using YYYY-MM-DD calendar dates. You define whether to match shifts based on their start time, their end time, or either their start time or end time.

"query": {
  "filter": {
    "workday": {
      "match_shifts_by": "START_AT",
      "date_range": {
        "start_date": "2024-10-14",
        "end_date": "2024-10-27"
      }
    }
  }
}

This filter has three components:

When combined in a query, certain filters might interact in ways that aren't immediately apparent. Understanding the interactions between the following combinations can help you create more effective queries:

• Team member and assignment status:

  • Using team_member_ids alone returns shifts for the specified team members plus all unassigned shifts.
  • Add assignment_status: "ASSIGNED" to only get shifts assigned to the specified team members.

• Shift status and assignment status:

  • The scheduled_shift_statuses filter affects which shift details are checked:
    • DRAFT - Evaluates draft_shift_details (includes unpublished shifts and shifts with modified drafts).
    • PUBLISHED - Evaluates published_shift_details.
    • DRAFT and PUBLISHED (default) - Evaluates both sets of details.
  • The assignment status is evaluated against the specified shift details.
  • Shifts marked for deletion (is_deleted: true) are ignored with the DRAFT status filter.

• Date range filters:

  • The start and end filters use exact timestamps.
  • The workday filter uses calendar dates and can match shifts based on different criteria.
  • When both are specified, shifts must match both conditions.

The following example finds all published shifts that start during a specific time window at the specified location:

The following example gets all published and assigned shifts on the specified date at the specified location, matching shifts based on their start time:

• Scheduling with the Labor API
• Manage Scheduled Shifts
• Labor API
• Team API