Labor API: Code Cookbook

Add Breaks to a Shift

Before you start Permalink Get a link to this section

  • A valid access token. You should test with Sandbox credentials whenever possible. For more information, see Square API Access Tokens.

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

Step 1: Get details for the shift you want to update Permalink Get a link to this section

Get Shift
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/labor/shifts/ID_OF_THE_SHIFT \
  -H 'Square-Version: 2021-03-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:

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

Step 2: Get available break types Permalink Get a link to this section

List Break Types
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/labor/break-types \
  -H 'Square-Version: 2021-03-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:

{
    "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"
        }
    ]
}

Step 3: Add the break to the shift Permalink Get a link to this section

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: 2021-03-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:

{
    "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,
...
    }
}

Step 4: End the shift break Permalink Get a link to this section

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: 2021-03-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:

{
    "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,
...
    }
}