Labor API

Add Breaks to a Shift

Before you start
Step 1: Get details for the shift you want to update
Step 2: Get available break types
Step 3: Add the break to the shift
Step 4: End the shift break

Learn how to get details for the shift you want to update, get available break types, and add a break to a shift.

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

A shift is complete when it has a start time and end time. If an employee takes breaks during a shift, the shift must be updated with each break including start and end times for the breaks taken.

Link to section
Step 1: Get details for the shift you want to update

Get Shift

curl https://connect.squareup.com/v2/labor/shifts/ID_OF_THE_SHIFT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The response to the shift request is a Shift object that matches the specified shift ID. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "shift": {
    "id": "3DBHNF9E8CG27",
    "employee_id": "AN_EMPLOYEE_ID",
    "location_id": "YOUR_LOCATION_ID",
    "timezone": "America/Los_Angeles",
    "start_at": "2018-10-05T04:00:00-07:00",
    "wage": {
      "title": "Bartender",
      "hourly_rate": {
        "amount": 123,
        "currency": "USD"
      }
    },
    "status": "OPEN",
    "version": 1,
    "created_at": "2019-02-20T01:28:49Z",
    "updated_at": "2019-02-20T01:28:49Z"
  }
}

Link to section
Step 2: Get available break types

List Break Types

curl https://connect.squareup.com/v2/labor/break-types \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The response to the request is an array of BreakType objects assigned to the Location ID. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{
    "break_types": [
        {
            "id": "3X212GX9NDJA9",
            "location_id": "89EKRBA8A0BET",
            "break_name": "Breakfast",
            "expected_duration": "PT10M",
            "is_paid": true,
            "version": 1,
            "created_at": "2019-02-20T17:57:41Z",
            "updated_at": "2019-02-20T17:57:41Z"
        },
        {
            "id": "Y32XW5N9JHHW3",
            "location_id": "89EKRBA8A0BET",
            "break_name": "2nd Breakfast",
            "expected_duration": "PT10M",
            "is_paid": true,
            "version": 1,
            "created_at": "2019-02-20T18:06:07Z",
            "updated_at": "2019-02-20T18:06:07Z"
        }
    ]
}

Link to section
Step 3: Add the break to the shift

Create a new break object with a start time, a name, and the ID of the break template and then add it to the shift.

If the version value of the most recently updated shift does not equal the value of the Shift object you are updating, the update fails and you receive an error response. If this happens, it is typically because a different client endpoint has updated the same shift after your application got the shift. To resolve the error, get a fresh instance of the shift by restarting the workflow from step 1.

Update Shift

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
30
31
32
33
34

curl https://connect.squareup.com/v2/labor/shifts/ID_OF_THE_SHIFT \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shift": {
      "id": "3DBHNF9E8CG27",
      "employee_id": "aq8XS-F0-VA0UrgH6h3w",
      "location_id": "YOUR_LOCATION_ID",
      "timezone": "America/Los_Angeles",
      "start_at": "2018-10-16T04:00:00-07:00",
      "breaks": [
        {
          "start_at": "2018-10-16T04:00:00Z",
          "break_type_id": "Y32XW5N9JHHW3",
          "name": "2nd Breakfast",
          "expected_duration": "PT10M",
          "is_paid": true
        }
      ],
      "wage": {
        "title": "Bartender",
        "hourly_rate": {
          "amount": 123,
          "currency": "USD"
        }
      },
      "status": "OPEN",
      "version": 1,
      "created_at": "2019-02-21T20:22:10Z",
      "updated_at": "2019-02-21T20:22:10Z"
    }
  }'

The response is a Shift object updated with the added break and an incremented version number. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
    "shift": {
        "id": "3DBHNF9E8CG27",
...
        "breaks": [
            {
                "id": "42AWYR29PYV52",
                "start_at": "2018-10-16T04:00:00-07:00",
                "break_type_id": "Y32XW5N9JHHW3",
                "name": "2nd Breakfast",
                "expected_duration": "PT10M",
                "is_paid": true
            }
        ],
        "status": "OPEN",
        "version": 2,
...
    }
}

Link to section
Step 4: End the shift break

Update the shift break with an end time and call UpdateShift again.

Update Shift

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
30
31
32
33
34
35
36

curl https://connect.squareup.com/v2/labor/shifts/ID_OF_THE_SHIFT \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "shift": {
      "id": "3DBHNF9E8CG27",
      "employee_id": "aq8XS-F0-VA0UrgH6h3w",
      "location_id": "YOUR_LOCATION_ID",
      "timezone": "America/Los_Angeles",
      "start_at": "2018-10-16T04:00:00-07:00",
      "wage": {
        "title": "Bartender",
        "hourly_rate": {
          "amount": 123,
          "currency": "USD"
        }
      },
      "breaks": [
        {
          "id": "42AWYR29PYV52",
          "start_at": "2018-10-16T04:00:00-07:00",
          "end_at": "2018-10-16T04:10:00-07:00",
          "break_type_id": "Y32XW5N9JHHW3",
          "name": "2nd Breakfast",
          "expected_duration": "PT10M",
          "is_paid": true
        }
      ],
      "status": "OPEN",
      "version": 2,
      "created_at": "2019-02-21T20:22:10Z",
      "updated_at": "2019-02-21T20:24:34Z"
    }
  }'

The response is an updated version of the Shift object with an incremented version number. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
    "shift": {
        "id": "3DBHNF9E8CG27",
...
        "breaks": [
            {
                "id": "42AWYR29PYV52",
                "start_at": "2018-10-16T04:00:00-07:00",
                "end_at": "2018-10-16T04:10:00-07:00",
                "break_type_id": "Y32XW5N9JHHW3",
                "name": "2nd Breakfast",
                "expected_duration": "PT10M",
                "is_paid": true
            }
        ],
        "status": "OPEN",
        "version": 3,
...
    }
}

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

Docs

Add Breaks to a Shift

On this page

Link to section
Before you start

Important

Link to section
Step 1: Get details for the shift you want to update

Link to section
Step 2: Get available break types

Link to section
Step 3: Add the break to the shift

Important

Link to section
Step 4: End the shift break

On this page

Docs

Add Breaks to a Shift

On this page

Link to section Before you start

Important

Link to section Step 1: Get details for the shift you want to update

Link to section Step 2: Get available break types

Link to section Step 3: Add the break to the shift

Important

Link to section Step 4: End the shift break

On this page

Link to section
Before you start

Link to section
Step 1: Get details for the shift you want to update

Link to section
Step 2: Get available break types

Link to section
Step 3: Add the break to the shift

Link to section
Step 4: End the shift break