Labor API

Get Completed Shifts

Before you start
Step 1: Get all closed shifts for the workweek
Step 2: Get additional results

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

Link to section
Before you start

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.

Link to section
Step 1: Get all closed shifts for the workweek

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).

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
  }'

Link to section
Step 2: Get additional results

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"
  }'

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Get Completed Shifts

On this page

Link to section
Before you start

Link to section
Step 1: Get all closed shifts for the workweek

Did you know?

Link to section
Step 2: Get additional results

On this page

Docs

Get Completed Shifts

On this page

Link to section Before you start

Link to section Step 1: Get all closed shifts for the workweek

Did you know?

Link to section Step 2: Get additional results

On this page

Link to section
Before you start

Link to section
Step 1: Get all closed shifts for the workweek

Link to section
Step 2: Get additional results