Labor API: Code Cookbook

Add Breaks to a Shift

Backend
Labor API
cURL (Command Line)

Before you start
Permalink Get a link to this section

  • A valid access token. Square recommends testing with sandbox credentials whenever possible. See Square API Access Tokens for more information.

  • If you are using OAuth, you will need TIMECARDS_WRITE permission to update a shift and TIMECARDS_READ permission to retrieve shifts.

  • You need to have created a Shift object using the Labor API. You can follow the Labor API build guide to create your first shift.

  • 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 shift you want to update
Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/labor/shifts/ID_OF_THE_SHIFT  \
 -H 'Content-Type: application/json'                               \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'

The response to the shift request is a Shift object that match 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 the break types available
Permalink Get a link to this section

curl https://connect.squareupsandbox.com/v2/labor/break-types?location_id=YOUR_LOCATION_ID \
 -H 'Content-Type: application/json'                                                \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'

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, name, and the ID of the break template, and 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 that you are updating, the update will fail and you will receive an error response. If this happens, it is typically because a different client endpoint has updated the same shift after your app got the shift. To resolve the error, get a fresh instance of the shift by re-starting the workflow from Step 1.

curl https://connect.squareupsandbox.com/v2/labor/shifts/ID_OF_THE_SHIFT  \
 -H 'Content-Type: application/json'                               \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'             \
 -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.

curl https://connect.squareupsandbox.com/v2/labor/shifts/ID_OF_THE_SHIFT  \
 -H 'Content-Type: application/json'                               \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'             \
 -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,
...
    }
}