Follow the steps below to build a security integration with the Toast platform. This guide outlines how your integration can use Toast orders data in coordination with video footage from your security monitoring service to develop a security business solution. Using time stamps, you can integrate video footage with order data, allowing restaurants to monitor operations and detect possible fraud or theft.
After you complete and test these steps, you can complete an end-to-end test of your integration functionality.
To build a security integration, you must have the following scopes:
-
cashmgmt:read
-
config:read
-
labor:read
-
labor.employees:read
-
menus:read
-
orders:read
-
restaurants:read
You can retrieve a list of your current scopes through your Toast developer portal account. If you lack the required scopes, refer to the Integration partnership process guide for instructions on requesting access.
Review and implement the instructions in How to build a Toast integration.
Reporting on sales depends on a restaurant’s usage of menu items and the overall structure of orders.
To understand Toast menu concepts before you begin development, review Menu hierarchy.
To review order structure, see Orders API overview and Order object summary. For more information about the orders API, see the orders API reference documentation.
Before beginning development, decide how you will report on the data retrieved. You should consider what information you will need to align transactions with video footage to detect possible fraud, theft, and so on. We specifically recommend you report on discounts, voids, and refunds. This guide will also describe how to determine the time a transaction began and ended, on which device, and by which employee, in order to sync this with video footage.
The following table provides suggested information that you can use when displaying order data alongside video footage or in reports.
Report type |
Object |
Values |
---|---|---|
Order data |
Orders |
Consider displaying the following reporting information for orders:
|
Checks |
Consider displaying the following reporting information for checks:
|
|
Menu item selections |
Consider displaying the following reporting information for menu item selections:
|
|
Payments |
Consider displaying the following reporting information for payments:
|
|
Cash transactions |
Cash entries |
Consider displaying the following reporting information for cash entries:
|
Deposits |
Consider displaying the following reporting information for cash deposits:
|
Consider including the following configuration information in your integration. After deciding which configuration information you want to retrieve, set up a daily poll to the configuration API and menus API to retrieve it.
In addition to the information in the table below, query the following configuration API endpoints at least once a day to ensure your integration captures any changes a restaurant makes to their configuration:
To reduce the amount of data that you receive when you poll the configuration API and menus API: Use the menus webhook or query the /metadata endpoint of menus API throughout the day.
Note |
Only retrieve a new menu when you determine that your existing menu is outdated. |
-
Use the
lastModified
query parameter to only retrieve entities modified after the specified timestamp. -
Use the menus webhook or query the /metadata endpoint of menus API throughout the day. Only retrieve a new menu when you determine that your existing menu is outdated.
Information type |
Configuration |
---|---|
Order configuration |
These pieces of configuration are often associated with orders. They describe how the order was placed and how its price was calculated.
|
Menu information |
The menus API returns menu item names and other menu-related information you may want to display in your platform.
|
Cash configuration |
Cash configuration allows you to display metadata about the cash transactions at a restaurant. For more information about working with cash entries, see Cash management overview.
|
Labor configuration |
This labor information allows you to acquire information about restaurant employees and the jobs they do.
|
To report on completed orders, you need to retrieve orders at
least once per day using the startDate
and
endDate
parameters of the /ordersBulk
endpoint of the orders API. See Getting detailed information about multiple orders for more
information.
For real-time order information, Toast support recommends using the Orders webhook to receive order updates as they occur instead of pulling order updates with the /ordersBulk endpoint.
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 order entities changes
after the closeoutHour
.
Consider daylight savings time when interacting with the closeout hour.
Based on the response from the /diningOptions
endpoint, determine which dining options your security integration needs
to sync with video footage and/or report on. Each dining option has a
corresponding behavior such as "DINE_IN
",
"TAKE_OUT
", or "DELIVERY
". Special
consideration should be taken for dining options indicating an
off-premise order and payment experience (such as orders placed
through the orders API or online orders) as these orders will not have
an on-premise payment transaction to sync to video footage. Optionally,
you can use timestamps on these orders to sync with preparation video
footage.
While off-premise orders will have limited relation to video footage, these orders may need to be included in any reports provided - such as reporting on discounts, voids, and so on. In this case, the order source should be considered. Possible order sources include in-store, online, API, kiosk, and so on. All order sources are documented on the order object API reference.
There are many timestamps included in the order
object and check
object that will be helpful to consider when syncing in-store
transactions with video footage. Review the order
object API reference with consideration to the
createdDate
, openedDate
,
paidDate
, closedDate
, and
modifiedDate
. For void reporting, the voidDate
and voidBusinessDate
will also be useful.
Servers can void orders, checks, item selections, and payments. If
the voided
value on an order, check, selection, or payment
is true
, your integration should include this data in the
applicable void report. Consider displaying selection and payment void
reasons by mapping the voidReason
value on the selection or
payment to the information in the /voidReasons
endpoint of the configuration API.
See this Toast Central article for more information about how to test void functionality.
Discounts can be applied to checks and item selections. Parse the
checks and selections objects for the appliedDiscounts
array in order to appropriately report on discounts.
If the payment object of a check
includes a refundStatus
value of PARTIAL
or
FULL
, details of the refund can be found on the refund
object.