Learn how to get all closed shifts for the workweek and get additional results.
Labor API

Get Completed Shifts

Learn how to get all closed shifts for the workweek and get additional results.

  • You need a valid access token. You should test with Sandbox credentials whenever possible. For more information, see Access Tokens and Other Square Credentials.

  • If you're using OAuth, you need TIMECARDS_WRITE permission to update a Shift and TIMECARDS_READ permission to retrieve a Shift.

  • You need to create a Shift object using the Labor API. To create your first shift, see Build with the Labor API.

  • You need to know the shift ID you want to update.

Requests to the SearchShifts endpoint include search filters and sorting instructions. The following request asks for all complete shifts during a 1-week pay period for the given location with the following characteristics:

  • The targeted pay period is May 12, 2023, through May 19, 2023.

  • The result is sorted using the shift creation timestamp in ascending order.

  • The results are limited to 20 shifts per response (page size).

Did you know?

The default time zone is set in the filter and used in the query when a time zone isn't set in the Seller Dashboard for the targeted location.

Calls to the SearchShifts endpoint must use a POST command:

Search Shifts
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
curl https://connect.squareup.com/v2/labor/shifts/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_id": [
          "YOUR_LOCATION_ID"
        ],
        "workday": {
          "date_range": {
            "start_date": "2018-10-01",
            "end_date": "2018-10-08"
          },
          "default_timezone": "America/Los Angeles",
          "match_shifts_by": "START_AT"
        },
        "status": "CLOSED"
      },
      "sort": {
        "field": "CREATED_AT",
        "order": "ASC"
      }
    },
    "limit": 20
  }'

If more results are available, the response includes a cursor object that can be used in subsequent calls to fetch the additional results. To use the cursor object from the previous response, add it to your request body and call the endpoint again:

Search Shifts
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
curl https://connect.squareup.com/v2/labor/shifts/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_id": [
          "YOUR_LOCATION_ID"
        ],
        "workday": {
          "date_range": {
            "start_date": "2018-10-01",
            "end_date": "2018-10-08"
          },
          "default_timezone": "America/Los Angeles",
          "match_shifts_by": "START_AT"
        },
        "status": "CLOSED"
      },
      "sort": {
        "field": "CREATED_AT",
        "order": "ASC"
      }
    },
    "limit": 20,
    "cursor": "CURSOR_FROM_PREVIOUS_RESPONSE"
  }'
We've made improvements to our docs.
Prefer the old format?