Code Cookbook

Get Completed Shifts

Get all closed shifts for a 7 day workweek.

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.

Query for a set of closed shifts for a workweek

The https://connect.squareup.com/v2/labor/shifts/searchendpoint takes a POST request that includes filter and sorting instructions in the body.

The following shift search request asks for all of a location's completed shifts for a 1 week pay period assuming that a work week starts on Monday at 4am:

  • Closed shifts for all employees
  • At a specified location
  • With shifts that start between
    • October 1, 2018 and October 8, 2018:
  • Sort on the shift creation timestamp in ascending order
  • Limit result page size to 20 shifts
curl https://connect.squareup.com/v2/labor/shifts/search \
 -H 'Content-Type: application/json'                       \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'     \
 -d '{
        "query": {
                "filter": {
                        "location_id": ["YOUR_LOCATION_ID"],
                        "workday": {
                                "date_range": {
                                        "start_date": "2018-10-01",
                                        "end_date": "2018-10-08"
                },
                "match_on": "START_AT"
                        },
                        "Status": "CLOSED"
                },
                "sort": {
                        "field": "CREATED_AT",
                        "order": "ASC"
                }
        },
        "limit": 20
}'

The response to the shift search request is an array of Shift objects that match the filter criteria. If more results are available, the response includes a cursor property: "cursor": "KFuNoJ1SQp1xkgb7EsxjSucfgx3K5PZbe0HifD22A43l03ZofED"

{
    "shifts": [
        {
            "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",
            "end_at": "2018-10-05T08:00:00-07:00",
            "wage": {
                "title": "Bartender",
                "hourly_rate": {
                    "amount": 123,
                    "currency": "USD"
                }
            },
            "breaks": [
                {
                    "id": "42AWYR29PYV52",
                    "start_at": "2018-10-05T04:00:00-07:00",
                    "end_at": "2018-10-05T08:00:00-07:00",
                    "break_type_id": "HQHZ5N3A3FSC9",
                    "name": "2nd Breakfast",
                    "expected_duration": "PT10M",
                    "is_paid": true
                }
            ],
            "status": "CLOSED",
            "version": 1,
            "created_at": "2019-02-20T01:28:49Z",
            "updated_at": "2019-02-20T01:28:49Z"
        },
        {
            "id": "YA05X7RPH2YD7",
            "employee_id": "AN_EMPLOYEE_ID",
             ...
        },
        {
            "id": "2ZH996MTJ80BE",
            "employee_id": "AN_EMPLOYEE_ID",
            ...
        }
    ],
    "cursor": "KFuNoJ1SQp1xkgb7EsxjSucfgx3K5PZbe0HifD22A43l03ZofED"
}

To produce a shifts search query using the PHP Connect v2 SDK, complete the following steps:

  1. Initialize the Labor API.
<?php
require_once(__DIR__ . '/vendor/autoload.php');
SquareConnect\Configuration::getDefaultConfiguration()->setAccessToken(
  'YOUR_ACCESS_TOKEN');
$api_instance = new SquareConnect\Api\LaborApi();
$Employees_api = new SquareConnect\Api\EmployeesApi();
?>
  1. Construct new search shift objects
public function retrieveShiftsByWorkweek(
   $status,
   $startWorkDay,
   $endWorkDay,
   $cursor = NULL)
 {
     $dateRange = new SquareConnect\model\DateRange();
     $shiftWorkday = new SquareConnect\model\ShiftWorkday();
     $shiftQuery = new SquareConnect\model\ShiftQuery();
     $shiftFilter = new SquareConnect\model\ShiftFilter();
     $shiftSort = new SquareConnect\model\ShiftSort();
     $searchShiftsRequest = new SquareConnect\model\SearchShiftsRequest();

  1. Set filter values
     if ($this->locationId != NULL) {
       $locations = Array($this->locationId);
       $shiftFilter->setLocationId($locations);
     }
     $dateRange->setStartDate($startWorkDay);
     $dateRange->setEndDate($endWorkDay);
     $shiftWorkday->setDateRange($dateRange);
     $shiftWorkday->setDefaultTimezone("America/Detroit");
     $shiftFilter->setWorkday($shiftWorkday);
     $shiftFilter->setStatus($status);

  1. Set sort values
   $shiftSort->setField("CREATED_AT");
   $shiftSort->setOrder("ASC");
  1. Set query values
   $shiftQuery->setFilter($shiftFilter);
   $shiftQuery->setSort($shiftSort);
  1. Create and send search shifts request
   $searchShiftsRequest->setQuery($shiftQuery);
   $searchShiftsRequest->setLimit($pageSize);
   if ($cursor != NULL) {
     $searchShiftsRequest->setCursor($cursor);
   }
    return $api_instance->searchShifts($searchShiftsRequest);
 }

Get result pages

Add a cursor key to the request body and set the value to the cursor value from the previous response.

curl https://connect.squareup.com/v2/labor/shifts/search \
 -H 'Content-Type: application/json'                       \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN'     \
 -d '{
        "query": {
                "filter": {
                        "location_id": ["YOUR_LOCATION_ID"],
                        "workday": {
                                "date_range": {
                                        "start_date": "2018-10-01",
                                        "end_date": "2018-10-05"
                },
                "match_on": "START_AT"
                        },
                        "Status": "CLOSED"
                },
                "sort": {
                        "field": "CREATED_AT",
                        "order": "ASC"
                }
        },
        "limit": 20
       "cursor": "KFuNoJ1SQp1xkgb7EsxjSucfgx3K5PZbe0HifD22A43l03ZofED" 
}'
  1. Call $retrieveShifts once to get the first page of results. If there are more results, call $retrieveShifts until there are no more results.
//Get the first page of employee shifts between Oct 4, 2018, 4am and Oct 11, 2018, 6pm
 $startRangeStart = date(DATE_ATOM, mktime(4, 0, 0, 10, 4, 2018)); //"2018-10-04T04:00:00Z"
 $startRangeEnd =  date(DATE_ATOM, mktime(18, 0, 0, 10, 11, 2018)); //"2018-10-11T18:00:00Z"
 $employees = Array($selectedEmployeeID);
 $listEmployeeShiftsResponse = $retrieveShifts(
   $startRangeStart,
   $startRangeEnd,
   NULL,
   NULL,
   NULL,
   $employees);
  //Do something with first page of results

 //Get next page of employee shifts until all pages have been received
 while ($listEmployeeShiftsResponse->getCursor() != NULL) {
   $listEmployeeShiftsResponse = $retrieveShifts(
     $startRangeStart,
     $startRangeEnd,
     NULL,
     NULL,
     $listEmployeeShiftsResponse->getCursor(),
     $employees);
     //Do something with this page of results
 }

List Shift details

There is no content for this step.

Details include: * Employee's last name * Start and end times for the shift * Hourly rate paid for the shift

public function listEmployeeShifts($shiftList) {
 if (method_exists($shiftList, "getShifts")) {
   foreach($shiftList->getShifts() as $shift) {
     $employeeResult = $Employees_api->retrieveEmployee(
        $shift->getEmployeeId());
     $this->displayEmployeeShifts(
       $employeeResult->getEmployee()->getLastName(),
       $shift->getStartAt(),
       $shift->getEndAt(),
       $shift->getWage()->getHourlyRate()->getAmount());
   }
 } 
} 
Prev
< Labor API Code Cookbook

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