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

Add Breaks to a Shift

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

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

Important

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.

Get Shift
  • 1
  • 2
  • 3
  • 4
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:

List Break Types
  • 1
  • 2
  • 3
  • 4
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:

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.

Important

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:

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:

We've made improvements to our docs.
Prefer the old format?