This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Getting Time Entries for Employees

Send a GET request to the /labor/v1/timeEntries resource of the labor API to get the time entry records for the employees at your restaurant. Time entries record information about the shifts that employees complete. The resource returns an array of JSON objects containing information about the time entries.

Keep in mind that if an employee (such as a server) has not clocked out of the work shift, the outDate value for the time entry is null because the time entry period is not yet complete. This means that the time entry values can change as the server takes new orders and payments during the active work shift.

When the server clocks out, the outDate value is set to the date and time that the employee closed the work shift and the time entry is then complete. At this point, the monetary values in the time entry are static and are not updated by other activities in the restaurant. For example, if a server has $100 of non-cash sales in their time entry when the server clocks out, and then an order of $10 non-cash sales is later transferred to the server, the nonCashSales value of the time entry will still be $100 (not $110). The same applies to tips.

The following example curl command sends a GET request to the /labor/v1/timeEntries resource.

Get the Time Entries for the Employees of a Restaurant

curl -v -X GET \
-H "Authorization: Bearer eyJzI1NiJ9hbGciOiJSU.eyJhd9yaXR5Ij
oiQ1JVTkNIVElNRSIsInJzR3VpZCI6IjE4YzQ5YWJlLWFlODItNGFlYy04ND
M1LWJhYTRjMjVlYTY2MiIsInNjb3BlIjpbImxWQiOlsidG9hc3QiXSwibmFt
aW5nQXV0aGhYm9yIiwib3JkZXJzIiwidXNlcm1nbXQiXSwiZXhwIjoxNDg0M
zg5ODUwLCJqdGkiOiJlMDYzZjJkMy1jNGYyLTRiZjItODJmNi01MTg1NWMzZ
DAxM2YiLCJjbGllbnRfaWQiOiJjcnVuY2h0aW1lIn0.X1_0y9Hzj5F9gdOw2
o6VSYTyZwooAJiFMDmNakbZrtiUdYwLzuLwLpCMQzX5pKYtOqDUz_cetGJL3
txKL1L-K2j1Enoq8An8hEM6e8J0KdAiwrYFO3W3CmWedaoz95K9ghNZVCs28
Td2Sp3Ix3fObxbrvanocx9_OT8S9uM8hdSXmBI_ykTWvOVgK4hO24V3DJy4b
9bz1FtgOvrClhELxCe8dJy7jiwAR60xczlCF5rna98RMLN6zY4ffjmljKFZ6
QV0KkVppWjEiJn7oFHiIylCX1sSg7sddrGatj0xJzts3GJ8u8_lryUNHaEvJ
dWq4Yzwo007AMgxjH9d241Y-g" \
-H "Toast-Restaurant-External-ID: 4622e7a9-b4be-3fef-9220-b3dad273e0b4" \1
"https://[toast-api-hostname]/labor/v1/timeEntries?startDate=2
2018-11-14T01:00:00.000-0000&endDate=2018-11-16T01:00:00.000-0000
&includeMissedBreaks=true"3

1

Specify the GUID of the restaurant that you want to get time entries for. This must be an individual restaurant, not the GUID for a restaurant group.

2

Specify the start and end dates of the time period you want to get shifts for. You can select a period of up to 30 days.

3

The timeEntries endpoint accepts the includeMissedBreaks query parameter. If you set the value of includeMissedBreaks to true, the timeEntries endpoint returns TimeEntryBreak objects for scheduled break periods even if an employee did not take them. The includeMissedBreaks parameter is optional. If you do not include the parameter, the endpoint returns only breaks that were taken, not breaks that were missed.


The following example shows the JSON message body data that provides information about a time entry for an employee.

JSON Message Body Content for Time Entries

[
  {1
    "guid": "26ac616b-b0d2-4d4e-b89b-62291be33d80",
    "entityType": null,
    "externalId": null,
    "nonCashSales": 0,2
    "outDate": "2018-11-15T19:17:34.653+0000",3
    "overtimeHours": 0,
    "breaks": [4
      {
        "breakType": {
          "guid": "8ed442b0-ca52-416d-8976-f941184eba15",
          "entityType": "BreakType"
        },
        "paid": true,
        "inDate": "2018-11-15T14:19:27.043+0000",
        "outDate": "2018-11-15T14:30:35.490+0000",
        "missed": false,
        "auditResponse": true
      },
      {
        "breakType": {
          "guid": "8ed442b0-ca52-416d-8976-f941184eba15",
          "entityType": "BreakType"
        },
        "paid": true,
        "inDate": "2018-11-15T18:13:46.894+0000",
        "outDate": null,
        "missed": true,
        "auditResponse": true
      }
    ],
    "employeeReference": {5
      "guid": "a0c9070e-fffd-4e97-b3ea-fc356fbf9224",
      "entityType": "RestaurantUser",
      "externalId": null
    },
    "shiftReference": "56387b8e-78df-47a4-9395-e5e1cb3f04d1",6
    "nonCashGratuityServiceCharges": 0,7
    "inDate": "2018-11-15T14:14:46.894+0000",
    "regularHours": 5.046599722222222,
    "jobReference": {8
      "guid": "8b623183-7d6f-4f7c-babb-e74fe722ad30",
      "entityType": "RestaurantJob",
      "externalId": null
    },
    "tipsWithheld": 0,9
    "businessDate": "20181115",
    "cashGratuityServiceCharges": 12.95,10
    "createdDate": "2018-11-15T14:14:47.503+0000",
    "deleted": false,
    "deletedDate": null,
    "cashSales": 139.02,11
    "hourlyWage": 7.5,
    "nonCashTips": 0,12
    "modifiedDate": "2018-11-15T19:17:35.801+0000",
    "declaredCashTips": 3013
  }
]

1

The GET request returns a JSON array of time entry objects. Each object contains information about an employee's shift.

2

The nonCashSales value shows the total non-cash sales in the orders opened by the employee during the time entry period. For example, nonCashSales includes credit card payments, gift card payments, and payments using options that you configure in the Other Payment Options screen of the Toast administration back-end.

If the outDate value for the time entry is null (the time entry period is not complete), the sales totals are 0. If the outDate value for the time entry is set, the sales totals are final and will not change. If you make changes to an order after the time entry is complete, the sales totals for the time entry do not change.

3

The time entry object contains information about the shift worked. For example, this outDate value specifies the date and time that the employee clocked out (the value is null if the employee has not clocked out).

4

The breaks array contains break type objects that contain information about breaks taken by the employee:

  • breakType is the Toast POS system GUID of the type of employee break period. You configure types of employee break periods for your restaurant.

  • inDate specifies when the employee started the break and outDate is when the employee ended the break. The datetime values are in UTC (Universal Time Coordinated).

  • paid is a Boolean value that indicates whether the employee was paid for the break (a value of true) or not paid for the break (a value of false).

  • missed is a Boolean value that indicates whether the employee took the break. If the value is true, the employee did not take the break. If the value is false, the employee did take the break.

  • auditResponse is a Boolean value that indicates whether the employee was asked to take the break. If the value is is true, the employee was asked to take the break. If the value is false, the employee was not asked to take the break. If the value is null, the break type is not configured to use break acknowledgement or the employee did not respond to the break acknowledgement prompt on the Toast POS device.

    For information on configuring missed breaks and break acknowledgements, see Employee breaks overview in the Toast Administrator's Guide.

5

The employeeReference value specifies the employee who worked the shift.

6

The GUID of the Shift object associated with this time entry. The shiftReference value on a TimeEntry object will only be populated if the restaurant uses Toast's clock-in enforcement feature, and the employee clocked into their shift within the restaurant's allowed window. Otherwise, the shiftReference value is null.

7

The nonCashGratuityServiceCharges value is the amount of gratuity service charges paid to the employee in non-cash tender (such as credit cards).

8

The jobReference value specifies the job that the employee performed.

9

The tipsWithheld value specifies the amount withheld from the employee's credit card tips.

10

The cashGratuityServiceCharges value is the amount of gratuity service charges paid in cash to the employee.

11

The cashSales value shows the total cash sales in the orders opened by the employee during the time entry period. The cash sales amount includes tax amounts, but does not include tip or gratuity amounts.

If the outDate value for the time entry is null (the time entry period is not complete), the sales totals are 0. If the outDate value for the time entry is set, the sales totals are final and will not change. If you make changes to an order after the time entry is complete, the sales totals for the time entry do not change.

12

The nonCashTips value lists the total amount of tips paid to the employee in non-cash tender.

13

The declaredCashTips value is the amount of tips paid to the employee in cash.