Get Completed Shifts

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

Applies to: Labor API

Link to section

Before you start

You need a valid access token - The steps in this topic call Square APIs in the Square Sandbox, so you can use your Sandbox access token in the requests. Square recommends testing with Sandbox credentials when possible.
Applications that use OAuth access tokens require the TIMECARDS_READ permission to perform these steps. When calling Square APIs in the production environment, change the base URL to https://connect.squareup.com.
You need at least one closed shift - To learn how to start and end a shift, see Build with the Labor API.

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 results are 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 Square Dashboard for the targeted location.

Calls to the SearchShifts endpoint must use a POST command:

Search shifts

Link to section

Response

The Labor API sends a list of Shift objects for the team members specified in the request and within the requested date range.

The wage field shows the settings applied to the shift, including the team member's job title for the shift and the internal job title ID assigned by Square when the job title is created in the Square Dashboard.

A seller can change a team member's job title at any time after the shift is created. For example, the "Bartender" job title can be changed to "Bar server". Any existing shift with that job ID now carries the wage.title of "Bar server". However, the job_id remains 1.

{
  "shifts": [
    {
      "id": "F4TXCQN30D7QG",
      "employee_id": "TM89nRVkpARCW66D",
      "location_id": "KACM8A41GR60X",
      "timezone": "America/Los_Angeles",
      "start_at": "2023-05-19T09:00:00-08:00",
      "end_at": "2023-05-19T14:00:00-08:00",
      "wage": {
        "title": "Bartender",
        "hourly_rate": {
          "amount": 3500,
          "currency": "USD"
        },
      "declared_cash_tip_money": {
        "amount": 2250,
        "currency": "USD"
      },
        "job_id": "1",
        "tip_eligible": true
      },
      "status": "CLOSED",
      "version": 1,
      "created_at": "2023-05-19T18:06:01-08:00",
      "updated_at": "2023-05-19T18:06:01-08:00",
      "team_member_id": "TM89nRVkpARCW66D"
    },
    {
      "id": "7NEDHJWA2SQW1",
      "employee_id": "TMKhulbHJDbTsaY0",
      "location_id": "KACM8A41GR60X",
      "timezone": "America/Los_Angeles",
      "start_at": "2023-05-19T09:00:00-08:00",
      "end_at": "2023-05-19T14:00:00-08:00",
      "wage": {
        "title": "Bartender",
        "hourly_rate": {
          "amount": 3500,
          "currency": "USD"
        },
        "job_id": "1",
        "tip_eligible": true
      },
      "declared_cash_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 1,
      "created_at": "2023-05-19T18:06:00-08:00",
      "updated_at": "2023-05-19T18:06:00-08:00",
      "team_member_id": "TMKhulbHJDbTsaY0"
    },
    {
      "id": "CK0WV6Y0EKY84",
      "employee_id": "TMI5_L2aJKwB4BjY",
      "location_id": "KACM8A41GR60X",
      "timezone": "America/Los_Angeles",
      "start_at": "2023-05-19T09:00:00-08:00",
      "end_at": "2023-05-19T14:00:00-08:00",
      "wage": {
        "title": "Server",
        "hourly_rate": {
          "amount": 3000,
          "currency": "USD"
        },
        "job_id": "2",
        "tip_eligible": true
      },
      "declared_cash_tip_money": {
        "amount": 4500,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 1,
      "created_at": "2023-05-19T18:05:58-08:00",
      "updated_at": "2023-05-19T18:05:58-08:00",
      "team_member_id": "TMI5_L2aJKwB4BjY"
    },
    {
      "id": "SKXJ0BRHEWEP2",
      "employee_id": "TMunHRm_uOvsqQts",
      "location_id": "KACM8A41GR60X",
      "timezone": "America/Los_Angeles",
      "start_at": "2023-05-19T09:00:00-08:00",
      "end_at": "2023-05-19T14:00:00-08:00",
      "wage": {
        "title": "Manager",
        "hourly_rate": {
          "amount": 3900,
          "currency": "USD"
        },
        "job_id": "3",
        "tip_eligible": false
      },
      "declared_cash_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 1,
      "created_at": "2023-05-19T18:05:57-08:00",
      "updated_at": "2023-05-19T18:05:57-08:00",
      "team_member_id": "TMunHRm_uOvsqQts"
    },
    {
      "id": "T5WXVEA4WYN17",
      "employee_id": "TM1dh73UnfQcTuLh",
      "location_id": "KACM8A41GR60X",
      "timezone": "America/Los_Angeles",
      "start_at": "2023-05-19T09:00:00-08:00",
      "end_at": "2023-05-19T14:00:00-08:00",
      "wage": {
        "title": "Manager",
        "hourly_rate": {
          "amount": 3900,
          "currency": "USD"
        },
        "job_id": "3",
        "tip_eligible": false
      },
      "declared_cash_tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 1,
      "created_at": "2023-05-19T18:05:55-08:00",
      "updated_at": "2023-05-19T18:05:55-08:00",
      "team_member_id": "TM1dh73UnfQcTuLh"
    },
    {
      "id": "VVMN1K1F1GMN2",
      "employee_id": "TMKK37xgGEINz0FV",
      "location_id": "KACM8A41GR60X",
      "timezone": "America/Los_Angeles",
      "start_at": "2023-05-19T09:00:00-08:00",
      "end_at": "2023-05-19T14:00:00-08:00",
      "wage": {
        "title": "Bartender",
        "hourly_rate": {
          "amount": 3500,
          "currency": "USD"
        },
        "job_id": "1",
        "tip_eligible": true
      },
      "declared_cash_tip_money": {
        "amount": 1500,
        "currency": "USD"
      },
      "status": "CLOSED",
      "version": 1,
      "created_at": "2023-05-19T18:05:54-08:00",
      "updated_at": "2023-05-19T18:05:54-08:00",
      "team_member_id": "TMKK37xgGEINz0FV"
    },
    ... // 14 more shifts
  ],
  "cursor": "MgBkM87tV9237Pamp26hI8E2g4PatKhVaMPlZwAi3MMgEXAMPLE"
}

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

Docs

Get Completed Shifts

Before you start

Step 1: Get all closed shifts for the workweek

Did you know?

Response

Step 2: Get additional results

On this page