Use the instructions below to build labor reports using information from the Toast platform. This information will help when creating a payroll integration, predicting future staffing needs, identifying the most efficient employees, and more.
To follow these instructions, you must have the following scopes:
-
config:read
-
labor.employees:read
-
labor:read
-
restaurants:read
-
orders:read
-
Setup and planning
Complete initial integration setupReview and implement the instructions on the Getting Started section.
Decide what information your reports will provideBefore beginning development, decide what reports you will build. The steps below describe how to extract the following labor data:
-
Hours worked per employee
-
Overtime hours worked per employee
-
Breaks taken
-
Shift clock-in timeliness (only possible if the restaurant uses clock-in enforcement functionality)
-
Sales per employee
-
Wages earned per employee (does not include overtime wages)
-
Tips earned per employee
-
-
Retrieving restaurant information
Build initial employee and job loadIf a restaurant begins using your integration after they are already live on the Toast platform, you will need to map the existing employees and jobs in the Toast platform to employees and jobs in your service.
Consider doing an initial employee load when a restaurant first connects to your platform. You can match employees based on identifying information such as names and email addresses. If you will use the
externalEmployeeId
field, you can also use this field for mapping employees in the Toast platform to employees in your service.Use the
/jobs
endpoint of the labor API to load initial job information. See this page for the jobs endpoint specification. If your integration allows restaurants to create employees in your platform and submit this information to the Toast platform, see Building an employee management integration.Set up recurring retrieval of employees, jobs, and configuration informationQuery the following endpoints at least once per location per day to ensure you maintain accurate labor information over time:
-
The
/employees
and/jobs
endpoints of the labor API -
The
/tipWithholding
endpoint of the configuration API if you report on tips earned per employee -
The
/breakTypes
endpoint of the configuration API if you report on breaks taken
Set up recurring retrieval of transactional informationTo report on labor information, you will need to retrieve transactional information from restaurants at least once per day. Use the following endpoints to retrieve transactional information:
-
If you report on hours worked or breaks taken, retrieve yesterday's time entries using the
modifiedStartDate
andmodifiedEndDate
parameters of the/timeEntries
endpoint of the labor API. See Getting time entries for employees for more information. -
If you report on shift clock-in timeliness, retrieve yesterday's shifts using the
startDate
andendDate
parameters of the/shifts
endpoint of the labor API. See Getting shift assignments for employees for more information. -
If you report on sales or tips per employee, retrieve yesterday's orders using the
startDate
andendDate
parameters of the/ordersBulk
endpoint of the orders API. See Getting detailed information about multiple orders for more information.
Determine closeout hourThe
closeoutHour
value in theGeneral
object returned by the restaurants API contains the restaurant's closeout hour.The default closeout hour is 4:00 a.m. local time unless a Toast employee changes this setting. The
businessDate
value on time entries changes after thecloseoutHour
.Consider Daylight Savings Time when interacting with the closeout hour.
-
-
Building report functionality
Reporting on hours worked and wages earnedUse the
regularHours
andovertimeHours
values onTimeEntry
objects to determine how many regular and overtime hours an employee worked while they were clocked in.To determine an hourly employee’s wages earned, multiply the
regularHours
andhourlyWage
values from theTimeEntry
object. The labor API does not expose the overtime factor to determine overtime wages earned. IfhourlyWage
is null, the time entry is associated with a salaried job.Reporting on breaks takenUse the
breaks
value onTimeEntry
objects to determine how much paid and unpaid break time an employee took while clocked in. ThebreakType
value on the time entry corresponds to aBreakType
object in the configuration API.Reporting on shift clock-in timelinessIf the restaurant uses clock-in enforcement functionality, then the
shiftReference
on aTimeEntry
object is populated with the GUID of the employee's scheduled shift.If the employee clocked in outside of the restaurant's allowed clock-in window or the restaurant does not use clock-in enforcement functionality, the
shiftReference
on the time entry is null.To compare the employee's scheduled shift time with their actual clock-in and clock-out times, compare the
inDate
andoutDate
values on the correspondingTimeEntry
andShift
objects.Reporting on sales and tips per employeeThe employee associated with an order is listed in the
server
value on anOrder
object in the orders API. To calculate an employee's sales and tips, sum theamount
(for total sales) andtipAmount
(for tips) on the payments associated with their orders.If the
/tipWithholding
endpoint of the configuration API indicates that the restaurant uses tip withholding functionality, your reports should reflect the tip values that were withheld from the employee.Toast support recommends using the orders API rather than the
cashSales
,nonCashSales
,declaredCashTips
, andnonCashTips
values on theTimeEntry
object to calculate an employee's sales and tips. The sales values on time entries may not reflect orders an employee handled outside of their shift, and time entry values will not update if a manager administratively adjusts the beginning or end time of a time entry.To determine if a payment or tip was cash, credit, or another payment type, use the
type
value on thePayment
object in the orders API.Additional reporting ideasConsider using the labor information you retrieve from Toast APIs in the following ways:
-
Predict how restaurants should plan future staffing. For example, if a particular day of the week or time of day tends to have a higher order volume, restaurants may want more team members to work during that timeframe.
-
Identify efficient employees as measured by sales or tips per hour worked and shift clock-in timeliness.
-
Use sales, tips, hours worked, and breaks taken when building a payroll product.
-
You are now ready to provide customers with detailed information related to labor costs and efficiency, providing restaurants with useful information to run their business.