Code Cookbook

Add Breaks to a Shift

Start and end breaks on a shift.

Labor API
Employees API
PHP (Connect SDK)
Connect SDK
Command Line
Save

Before you start

  • You will need an access token. 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 Build With Labor API Guide to create your first Shift object.

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.

Start a shift break

  1. Get the shift to update
curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27 \
 -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. 
{
    "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"
    }
}
  public function retrieveOpenShifts(  array $employees) {
    $laborApi = new SquareConnect\Api\LaborApi();

    if (size_of($employees) == 0) {
       return;
    }
    $shiftQuery = new SquareConnect\model\ShiftQuery();
    $shiftFilter = new SquareConnect\model\ShiftFilter();
    $searchShiftsRequest = new SquareConnect\model\SearchShiftsRequest();
    $shiftFilter->setEmployeeId($employees);
    $shiftFilter->setStatus("OPEN");
    $shiftQuery->setFilter($shiftFilter);
    $searchShiftsRequest->setQuery($shiftQuery);
    $searchShiftsResponse =  $laborApi->searchShifts($searchShiftsRequest);
    return $searchShiftsResponse->getShifts()[0];
  }
  1. Retrieve the break types available in this location.
curl https://connect.squareup.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.

{
    "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"
        }
    ]
}
    //Get all of the break type templates to find the break type whose
    //name matches YOUR_BREAK_NAME
    $response = $laborApi->listBreakTypes(YOUR_LOCATION_ID, 10, NULL);
    $selectedBreak = NULL;

    //Iterate over all break types until we find the break type
    //whose name matches the $breakName function argument
    foreach ($response->getBreakTypes() as &$breakType) {
      if ($breakType->getBreakName() == YOUR_BREAK_NAME) {
        $selectedBreak = $breakType;
        break;
      }
    }
  1. Update the $shiftToUpdate with new Break with a start time, name, and the ID of the BreakType that the break is based on.
curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27 \
 -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 :
{
    "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,
...
    }
}
     $modelBreak = new SquareConnect\Model\ModelBreak();
     $updateShiftRequest = new SquareConnect\Model\UpdateShiftRequest();

     //Set required break fields, including the break start timestamp
     //of the current time.
     $modelBreak->setStartAt(date(DATE_ATOM, time()));
     $modelBreak->setBreakTypeId($selectedBreak->getId());
     $modelBreak->setName($selectedBreak->getBreakName());
     $modelBreak->setExpectedDuration($selectedBreak->getExpectedDuration());
     $modelBreak->setIsPaid($selectedBreak->getIsPaid());

     //Stuff new Break object into array
     $breaks = Array($modelBreak);
     $shiftToUpdate->setBreaks($breaks);
     $updateShiftRequest->setShift($shiftToUpdate);
     $updatedShift = $laborApi->updateShift(
       $shiftToUpdate->getId(), 
       $updateShiftRequest);

{
    "errors": [
        {
            "code": "VERSION_MISMATCH",
            "detail": "The version of the resource on the server does not match
            the version provided with the request. Please re-fetch the resource
            and try again.",
            "field": "version",
            "category": "INVALID_REQUEST_ERROR"
        }
    ]
}

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.

End a shift break

  1. Get the shift to update
curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27 \
 -H 'Content-Type: application/json'                       \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'     \

The response to the shift search request is a Shift object that match the specified Shift ID.

{
    "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,
...
    }
}
  public function retrieveOpenShifts(  array $employees) {
    $laborApi = new SquareConnect\Api\LaborApi();

    if (size_of($employees) == 0) {
       return;
    }
    $shiftQuery = new SquareConnect\model\ShiftQuery();
    $shiftFilter = new SquareConnect\model\ShiftFilter();
    $searchShiftsRequest = new SquareConnect\model\SearchShiftsRequest();
    $shiftFilter->setEmployeeId($employees);
    $shiftFilter->setStatus("OPEN");
    $shiftQuery->setFilter($shiftFilter);
    $searchShiftsRequest->setQuery($shiftQuery);
    $searchShiftsResponse =  $laborApi->searchShifts($searchShiftsRequest);
    return $searchShiftsResponse->getShifts()[0];
  }
  1. Update the shift break with an end time.
curl https://connect.squareup.com/v2/labor/shifts/3DBHNF9E8CG27 \
 -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:

{
    "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,
...
    }
}
    $updateShiftRequest = new SquareConnect\Model\UpdateShiftRequest();

    //Get the array of breaks that have previously been added to
    //the shift
    $shiftBreaks = $shiftToUpdate->getBreaks();
    $modelBreakToEnd = NULL;

    //Iterate over all shift breaks until we find the shift break
    //that has not ended
    for ($x = 0; $x <= sizeof($shiftBreaks); $x++) {
      if ($shiftBreaks[$x]->getEndAt() == NULL) {
        $shiftBreaks[$x]->setEndAt(date(DATE_ATOM, time()));
        break;
      }
    }

    $shiftToUpdate->setBreaks($shiftBreaks);
    $updateShiftRequest->setShift($shiftToUpdate);
    try {
      return $this->laborApi->updateShift($shiftID, $updateShiftRequest);
    } 
    catch (Exception $e) {
      return NULL;
    }

Prev
< Labor API Code Cookbook

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow