Review and implement the instructions in How to build a Toast integration.

Before you begin development, decide what reports you will build.

The steps below describe how to extract the following labor data:

If a restaurant begins to use your integration after they are already live on the Toast platform, you must 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 to map employees in the Toast platform to employees in your service.

Use the /jobs endpoint of the labor API to load initial job information. See the labor API 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.

Query the following endpoints at least once per location per day to ensure you maintain accurate labor information over time:

To report on labor information, you need to retrieve transactional information from restaurants at least once per day.

Use the following endpoints to retrieve transactional information:

The closeoutHour value in the General 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 the closeoutHour.

Consider daylight savings time when interacting with the closeout hour.

Use the regularHours and overtimeHours values on TimeEntry 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 and hourlyWage values from the TimeEntry object.

The labor API does not expose the overtime factor to determine overtime wages earned.

If hourlyWage is null, the time entry is associated with a salaried job.

Use the breaks value on TimeEntry objects to determine how much paid and unpaid break time an employee took while clocked in.

The breakType value on the time entry corresponds to a BreakType object in the configuration API.

If the restaurant uses clock-in enforcement functionality, then the shiftReference on a TimeEntry 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 and outDate values on the corresponding TimeEntry and Shift objects.

The employee associated with an order is listed in the server value on an Order object in the orders API. To calculate an employee's sales and tips, sum the amount (for total sales) and tipAmount (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, and nonCashTips values on the TimeEntry 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 the Payment object in the orders API.

Consider using the labor information you retrieve from Toast APIs in the following ways: