---
title: "SearchScheduledShifts"
method: POST
path: "/v2/labor/scheduled-shifts/search"
tags: ["Labor"]
---

# SearchScheduledShifts

`POST /v2/labor/scheduled-shifts/search`

Returns a paginated list of scheduled shifts, with optional filter and sort settings.
By default, results are sorted by `start_at` in ascending order.

## Request body

- SearchScheduledShiftsRequest — Represents a [SearchScheduledShift](api-endpoint:Labor-SearchScheduledShift) request.
  - `query` ScheduledShiftQuery — Represents filter and sort criteria for the `query` field in a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request.
    - `filter` ScheduledShiftFilter — Defines filter criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. Multiple filters in a query are combined as an `AND` operation.
      - `location_ids` string[], nullable — Return shifts for the specified locations. When omitted, shifts for all locations are returned. If needed, call [ListLocations](api-endpoint:Locations-ListLocations) to get location IDs.
      - `start` TimeRange — Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
        - `start_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range starts.
        - `end_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range ends.
      - `end` TimeRange — Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
        - `start_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range starts.
        - `end_at` string, nullable — A datetime value in RFC 3339 format indicating when the time range ends.
      - `workday` ScheduledShiftWorkday — A `ScheduledShift` search query filter parameter that sets a range of days that a `Shift` must start or end in before passing the filter condition.
        - `date_range` DateRange — A range defined by two dates. Used for filtering a query for Connect v2 objects that have date properties.
          - `start_date` string, nullable — A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO 8601 extended format for calendar dates. The beginning of a date range (inclusive).
          - `end_date` string, nullable — A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO 8601 extended format for calendar dates. The end of a date range (inclusive).
        - `match_scheduled_shifts_by` 'START_AT' | 'END_AT' | 'INTERSECTION' — Defines the logic used to apply a workday filter.
        - `default_timezone` string, nullable — Location-specific timezones convert workdays to datetime filters. Every location included in the query must have a timezone or this field must be provided as a fallback. Format: the IANA timezone database identifier for the relevant timezone.
      - `team_member_ids` string[], nullable — Return shifts assigned to specified team members. If needed, call [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers) to get team member IDs. To return only the shifts assigned to the specified team members, include the `assignment_status` filter in the query. Otherwise, all unassigned shifts are returned along with shifts assigned to the specified team members.
      - `assignment_status` 'ASSIGNED' | 'UNASSIGNED' — Defines valid values for the `assignment_status` filter in a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request. Assignment status is based on the `draft_shift_details.team_member_id` and `published_shift_details.team_member_id` fields of the scheduled shift.
      - `scheduled_shift_statuses` ScheduledShiftFilterScheduledShiftStatus[], nullable — Return shifts based on the draft or published status of the shift. A shift is published if the `published_shift_details` field is present. Note that shifts with `draft_shift_details.is_deleted` set to `true` are ignored with the `DRAFT` filter. See [ScheduledShiftFilterScheduledShiftStatus](#type-scheduledshiftfilterscheduledshiftstatus) for possible values
    - `sort` ScheduledShiftSort — Defines sort criteria for a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request.
      - `field` 'START_AT' | 'END_AT' | 'CREATED_AT' | 'UPDATED_AT' — Defines valid values for the `field` sort setting in a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) request.
      - `order` 'DESC' | 'ASC' — The order (e.g., chronological or alphabetical) in which results from a request are returned.
  - `limit` integer — The maximum number of results to return in a single response page. The default value is 50.
  - `cursor` string — The pagination cursor returned by the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

## Response `200`

Success

- SearchScheduledShiftsResponse — Represents a [SearchScheduledShifts](api-endpoint:Labor-SearchScheduledShifts) response. Either `scheduled_shifts` or `errors` is present in the response.
  - `scheduled_shifts` ScheduledShift[] — A paginated list of scheduled shifts that match the query conditions.
    - `id` string — **Read only** The Square-issued ID of the scheduled shift.
    - `draft_shift_details` ScheduledShiftDetails — Represents shift details for draft and published versions of a [scheduled shift](entity:ScheduledShift), such as job ID, team member assignment, and start and end times.
      - `team_member_id` string, nullable — The ID of the [team member](entity:TeamMember) scheduled for the shift.
      - `location_id` string, nullable — The ID of the [location](entity:Location) the shift is scheduled for.
      - `job_id` string, nullable — The ID of the [job](entity:Job) the shift is scheduled for.
      - `start_at` string, nullable — The start time of the shift, in RFC 3339 format in the time zone + offset of the shift location specified in `location_id`. Precision up to the minute is respected; seconds are truncated.
      - `end_at` string, nullable — The end time for the shift, in RFC 3339 format in the time zone + offset of the shift location specified in `location_id`. Precision up to the minute is respected; seconds are truncated.
      - `notes` string, nullable — Optional notes for the shift.
      - `is_deleted` boolean, nullable — Indicates whether the draft shift version is deleted. If set to `true` when the shift is published, the entire scheduled shift (including the published shift) is deleted and cannot be accessed using any endpoint.
      - `timezone` string — The time zone of the shift location, calculated based on the `location_id`. This field is provided for convenience.
    - `published_shift_details` ScheduledShiftDetails — Represents shift details for draft and published versions of a [scheduled shift](entity:ScheduledShift), such as job ID, team member assignment, and start and end times.
      - `team_member_id` string, nullable — The ID of the [team member](entity:TeamMember) scheduled for the shift.
      - `location_id` string, nullable — The ID of the [location](entity:Location) the shift is scheduled for.
      - `job_id` string, nullable — The ID of the [job](entity:Job) the shift is scheduled for.
      - `start_at` string, nullable — The start time of the shift, in RFC 3339 format in the time zone + offset of the shift location specified in `location_id`. Precision up to the minute is respected; seconds are truncated.
      - `end_at` string, nullable — The end time for the shift, in RFC 3339 format in the time zone + offset of the shift location specified in `location_id`. Precision up to the minute is respected; seconds are truncated.
      - `notes` string, nullable — Optional notes for the shift.
      - `is_deleted` boolean, nullable — Indicates whether the draft shift version is deleted. If set to `true` when the shift is published, the entire scheduled shift (including the published shift) is deleted and cannot be accessed using any endpoint.
      - `timezone` string — The time zone of the shift location, calculated based on the `location_id`. This field is provided for convenience.
    - `version` integer — **Read only** The current version of the scheduled shift, which is incremented with each update. This field is used for [optimistic concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) control to ensure that requests don't overwrite data from another request.
    - `created_at` string — The timestamp of when the scheduled shift was created, in RFC 3339 format presented as UTC.
    - `updated_at` string — The timestamp of when the scheduled shift was last updated, in RFC 3339 format presented as UTC.
  - `cursor` string — The pagination cursor used to retrieve the next page of results. This field is present only if additional results are available.
  - `errors` Error[] — Any errors that occurred during the request.
    - `category` 'API_ERROR' | 'AUTHENTICATION_ERROR' | 'INVALID_REQUEST_ERROR' | 'RATE_LIMIT_ERROR' | 'PAYMENT_METHOD_ERROR' | 'REFUND_ERROR' | 'MERCHANT_SUBSCRIPTION_ERROR' | 'EXTERNAL_VENDOR_ERROR', required — Indicates which high-level category of error has occurred during a request to the Connect API.
    - `code` 'INTERNAL_SERVER_ERROR' | 'UNAUTHORIZED' | 'ACCESS_TOKEN_EXPIRED' | 'ACCESS_TOKEN_REVOKED' | 'CLIENT_DISABLED' | 'FORBIDDEN' | 'INSUFFICIENT_SCOPES' | 'APPLICATION_DISABLED' | 'V1_APPLICATION' | 'V1_ACCESS_TOKEN' | 'CARD_PROCESSING_NOT_ENABLED' | 'MERCHANT_SUBSCRIPTION_NOT_FOUND' | 'BAD_REQUEST' | 'MISSING_REQUIRED_PARAMETER' | 'INCORRECT_TYPE' | 'INVALID_TIME' | 'INVALID_TIME_RANGE' | 'INVALID_VALUE' | 'INVALID_CURSOR' | 'UNKNOWN_QUERY_PARAMETER' | 'CONFLICTING_PARAMETERS' | 'EXPECTED_JSON_BODY' | 'INVALID_SORT_ORDER' | 'VALUE_REGEX_MISMATCH' | 'VALUE_TOO_SHORT' | 'VALUE_TOO_LONG' | 'VALUE_TOO_LOW' | 'VALUE_TOO_HIGH' | 'VALUE_EMPTY' | 'ARRAY_LENGTH_TOO_LONG' | 'ARRAY_LENGTH_TOO_SHORT' | 'ARRAY_EMPTY' | 'EXPECTED_BOOLEAN' | 'EXPECTED_INTEGER' | 'EXPECTED_FLOAT' | 'EXPECTED_STRING' | 'EXPECTED_OBJECT' | 'EXPECTED_ARRAY' | 'EXPECTED_MAP' | 'EXPECTED_BASE64_ENCODED_BYTE_ARRAY' | 'INVALID_ARRAY_VALUE' | 'INVALID_ENUM_VALUE' | 'INVALID_CONTENT_TYPE' | 'INVALID_FORM_VALUE' | 'CUSTOMER_NOT_FOUND' | 'ONE_INSTRUMENT_EXPECTED' | 'NO_FIELDS_SET' | 'TOO_MANY_MAP_ENTRIES' | 'MAP_KEY_LENGTH_TOO_SHORT' | 'MAP_KEY_LENGTH_TOO_LONG' | 'CUSTOMER_MISSING_NAME' | 'CUSTOMER_MISSING_EMAIL' | 'INVALID_PAUSE_LENGTH' | 'INVALID_DATE' | 'UNSUPPORTED_COUNTRY' | 'UNSUPPORTED_CURRENCY' | 'APPLE_TTP_PIN_TOKEN' | 'CARD_EXPIRED' | 'INVALID_EXPIRATION' | 'INVALID_EXPIRATION_YEAR' | 'INVALID_EXPIRATION_DATE' | 'UNSUPPORTED_CARD_BRAND' | 'UNSUPPORTED_ENTRY_METHOD' | 'INVALID_ENCRYPTED_CARD' | 'INVALID_CARD' | 'PAYMENT_AMOUNT_MISMATCH' | 'GENERIC_DECLINE' | 'CVV_FAILURE' | 'ADDRESS_VERIFICATION_FAILURE' | 'INVALID_ACCOUNT' | 'CURRENCY_MISMATCH' | 'INSUFFICIENT_FUNDS' | 'INSUFFICIENT_PERMISSIONS' | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' | 'INVALID_LOCATION' | 'TRANSACTION_LIMIT' | 'VOICE_FAILURE' | 'PAN_FAILURE' | 'EXPIRATION_FAILURE' | 'CARD_NOT_SUPPORTED' | 'READER_DECLINED' | 'INVALID_PIN' | 'MISSING_PIN' | 'MISSING_ACCOUNT_TYPE' | 'INVALID_POSTAL_CODE' | 'INVALID_FEES' | 'MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED' | 'PAYMENT_LIMIT_EXCEEDED' | 'GIFT_CARD_AVAILABLE_AMOUNT' | 'ACCOUNT_UNUSABLE' | 'BUYER_REFUSED_PAYMENT' | 'DELAYED_TRANSACTION_EXPIRED' | 'DELAYED_TRANSACTION_CANCELED' | 'DELAYED_TRANSACTION_CAPTURED' | 'DELAYED_TRANSACTION_FAILED' | 'CARD_TOKEN_EXPIRED' | 'CARD_TOKEN_USED' | 'AMOUNT_TOO_HIGH' | 'UNSUPPORTED_INSTRUMENT_TYPE' | 'REFUND_AMOUNT_INVALID' | 'REFUND_ALREADY_PENDING' | 'PAYMENT_NOT_REFUNDABLE' | 'PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE' | 'REFUND_ERROR_PAYMENT_NEEDS_COMPLETION' | 'REFUND_DECLINED' | 'INSUFFICIENT_PERMISSIONS_FOR_REFUND' | 'INVALID_CARD_DATA' | 'SOURCE_USED' | 'SOURCE_EXPIRED' | 'UNSUPPORTED_LOYALTY_REWARD_TIER' | 'LOCATION_MISMATCH' | 'ORDER_UNPAID_NOT_RETURNABLE' | 'PARTIAL_PAYMENT_DELAY_CAPTURE_NOT_SUPPORTED' | 'IDEMPOTENCY_KEY_REUSED' | 'UNEXPECTED_VALUE' | 'SANDBOX_NOT_SUPPORTED' | 'INVALID_EMAIL_ADDRESS' | 'INVALID_PHONE_NUMBER' | 'CHECKOUT_EXPIRED' | 'BAD_CERTIFICATE' | 'INVALID_SQUARE_VERSION_FORMAT' | 'API_VERSION_INCOMPATIBLE' | 'CARD_PRESENCE_REQUIRED' | 'UNSUPPORTED_SOURCE_TYPE' | 'CARD_MISMATCH' | 'PLAID_ERROR' | 'PLAID_ERROR_ITEM_LOGIN_REQUIRED' | 'PLAID_ERROR_RATE_LIMIT' | 'PAYMENT_SOURCE_NOT_ENABLED_FOR_TARGET' | 'CARD_DECLINED' | 'VERIFY_CVV_FAILURE' | 'VERIFY_AVS_FAILURE' | 'CARD_DECLINED_CALL_ISSUER' | 'CARD_DECLINED_VERIFICATION_REQUIRED' | 'BAD_EXPIRATION' | 'CHIP_INSERTION_REQUIRED' | 'ALLOWABLE_PIN_TRIES_EXCEEDED' | 'RESERVATION_DECLINED' | 'UNKNOWN_BODY_PARAMETER' | 'NOT_FOUND' | 'APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND' | 'METHOD_NOT_ALLOWED' | 'NOT_ACCEPTABLE' | 'REQUEST_TIMEOUT' | 'CONFLICT' | 'GONE' | 'REQUEST_ENTITY_TOO_LARGE' | 'UNSUPPORTED_MEDIA_TYPE' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'NOT_IMPLEMENTED' | 'BAD_GATEWAY' | 'SERVICE_UNAVAILABLE' | 'TEMPORARY_ERROR' | 'GATEWAY_TIMEOUT', required — Indicates the specific error that occurred during a request to a Square API.
    - `detail` string — A human-readable description of the error for debugging purposes.
    - `field` string — The name of the field provided in the original request (if any) that the error pertains to.

---

[API](https://skmtc.net/square/apis/connect-api.md) · [All operations](https://skmtc.net/square/apis/connect-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/connect-api/revisions/6a5164284e41/schema)