Search shifts

POST

/v2/labor/shifts/search

Returns a paginated list of Shift records for a business.

The list to be returned can be filtered by:

Location IDs
Team member IDs
Shift status (OPEN or CLOSED)
Shift start
Shift end
Workday details

The list can be sorted by:

START_AT
END_AT
CREATED_AT
UPDATED_AT

Permissions:TIMECARDS_READ

Try in API Explorer

Link to section

Request body

Example code

Link to section

query

Query filters.

Link to section

limit

integer(32-bit)

The number of resources in a page (200 by default).

Min

Max

200

Link to section

cursor

string

An opaque cursor for fetching the next page.

Link to section

Response fields

Link to section

shifts

Shifts.

Link to section

cursor

string

An opaque cursor for fetching the next page.

Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

POST /v2/labor/shifts/search

curl https://connect.squareup.com/v2/labor/shifts/search \
  -X POST \
  -H 'Square-Version: 2025-04-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "workday": {
          "date_range": {
            "start_date": "2019-01-20",
            "end_date": "2019-02-03"
          },
          "match_shifts_by": "START_AT",
          "default_timezone": "America/Los_Angeles"
        }
      }
    },
    "limit": 100
  }'

Response JSON

{
  "shifts": [
    {
      "id": "X714F3HA6D1PT",
      "team_member_id": "ormj0jJJZ5OZIzxrZYJI",
      "employee_id": "ormj0jJJZ5OZIzxrZYJI",
      "location_id": "PAA1RJZZKXBFG",
      "timezone": "America/New_York",
      "start_at": "2019-01-21T03:11:00-05:00",
      "end_at": "2019-01-21T13:11:00-05:00",
      "wage": {
        "title": "Barista",
        "hourly_rate": {
          "amount": 1100,
          "currency": "USD"
        },
        "job_id": "FzbJAtt9qEWncK1BWgVCxQ6M",
        "tip_eligible": true
      },
      "breaks": [
        {
          "id": "SJW7X6AKEJQ65",
          "start_at": "2019-01-21T06:11:00-05:00",
          "end_at": "2019-01-21T06:11:00-05:00",
          "break_type_id": "REGS1EQR1TPZ5",
          "name": "Tea Break",
          "expected_duration": "PT10M",
          "is_paid": true
        }
      ],
      "declared_cash_tip_money": {
        "amount": 500,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 6,
      "created_at": "2019-01-24T01:12:03Z",
      "updated_at": "2019-02-07T22:21:08Z"
    },
    {
      "id": "GDHYBZYWK0P2V",
      "team_member_id": "33fJchumvVdJwxV0H6L9",
      "employee_id": "33fJchumvVdJwxV0H6L9",
      "location_id": "PAA1RJZZKXBFG",
      "timezone": "America/New_York",
      "start_at": "2019-01-22T12:02:00-05:00",
      "end_at": "2019-01-22T13:02:00-05:00",
      "wage": {
        "title": "Cook",
        "hourly_rate": {
          "amount": 1600,
          "currency": "USD"
        },
        "job_id": "gcbz15vKGnMKmaWJJ152kjim",
        "tip_eligible": true
      },
      "breaks": [
        {
          "id": "BKS6VR7WR748A",
          "start_at": "2019-01-23T14:30:00-05:00",
          "end_at": "2019-01-23T14:40:00-05:00",
          "break_type_id": "WQX00VR99F53J",
          "name": "Tea Break",
          "expected_duration": "PT10M",
          "is_paid": true
        },
        {
          "id": "BQFEZSHFZSC51",
          "start_at": "2019-01-22T12:30:00-05:00",
          "end_at": "2019-01-22T12:44:00-05:00",
          "break_type_id": "P6Q468ZFRN1AC",
          "name": "Coffee Break",
          "expected_duration": "PT15M",
          "is_paid": false
        }
      ],
      "declared_cash_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 16,
      "created_at": "2019-01-23T23:32:45Z",
      "updated_at": "2019-01-24T00:56:25Z"
    }
  ]
}