Use the instructions below to build cash transaction reports using information from the Toast platform. This information helps when validating cash drawer values, spotting large cash transactions, reviewing payout activity, and more.
To follow these instructions, you must have the following scopes:
-
cashmgmt:read
-
config:read
-
labor.employees:read
-
restaurants: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. This guide describes how to report on the following cash transaction information:
-
Addition and removal of miscellaneous cash from cash drawer
-
Addition and removal of cash tips from cash drawer
-
"No sale" transactions
-
Cash payments for goods and services
-
Delivery driver reimbursement
-
Closeouts
-
Deposits
-
Expected value in cash drawer
-
Anomalous cash transactions
-
-
Retrieving restaurant information
Set up recurring retrieval of configuration and employee informationTo display additional information associated with cash transactions, query the following configuration API endpoints at least once per day:
-
/cashDrawers
-
/noSaleReasons
-
/payoutReasons
In addition, query the
/employees
endpoint of the labor API at least once per day to retrieve information about the employees associated with cash transactions.Set up recurring retrieval of cash transactionsTo report on cash transactions, you need to retrieve cash entries and deposits once per day. using the
businessDate
parameter of the/entries
endpoint and/deposits
endpoint of the cash management API.For cash entries, use the businessDate parameter of the
/entries
endpoint of the cash management API. Toast support recommends retrieving cash entries for the previous business day every day.For deposits, use the businessDate parameter of the
/deposits
endpoint of the cash management API. Toast support recommends retrieving cash entries for the previous business day every day.Consider historical backfillWhen a restaurant first connects to your integration, they may expect to see some historical information already displayed in your system.
Define how many days of historical cash transactions you retrieve when a restaurant first connects to your integration.
Toast support recommends that you retrieve twelve weeks of historical cash transactions when a restaurant first connects to your integration.
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 cash transactions changes after thecloseoutHour
.Consider Daylight Savings Time when interacting with the closeout hour.
-
-
Building report functionality
Associate cash drawer information with cash entriesTo display the cash drawer associated with the cash entry, identify the
cashDrawer
value of theCashEntry
object returned by the/entries
endpoint of the cash management API. Then display thename
of the associatedCashDrawer
object returned by the/cashDrawers
endpoint of the configuration API.Addition and removal of miscellaneous cash from cash drawerTo report on the addition and removal of miscellaneous cash from the cash drawer, your reports should display cash entries whose
type
values areCASH_IN
andCASH_OUT
.Cash entries whose
type
isCASH_IN
represent employees adding cash into a cash drawer. Cash entries whosetype
isCASH_OUT
represent employees removing cash from a cash drawer. Cash entries whose 'type' isCASH_IN
orCASH_OUT
indicate employees adding cash to a cash drawer or removing cash from a cash drawer outside of a transaction.To display the name of the employee who initiated the addition or removal of cash from the cash drawer, match the GUID of the
employee
1 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.To display the name of the employee who approved the addition or removal of cash from the cash drawer, match the GUID of the
employee
2 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.When a restaurant employee undoes a
CASH_IN
entry, there is a correspondingCASH_OUT
entry. In thatCASH_OUT
entry, theundoes
value contains the GUID of the originalCASH_IN
transaction. Similarly, when a restaurant employee undoes aCASH_OUT
entry, there is a correspondingCASH_IN
entry. In thatCASH_IN
entry, theundoes
value contains the GUID of the originalCASH_OUT
transaction. If theundoes
value on a cash entry contains information, your reports should match this cash entry with the original entry it undoes. TheCASH_IN
and correspondingCASH_OUT
entries may occur on different business days.Addition and removal of cash tips from cash drawerTo report on the addition and removal of miscellaneous cash from the cash drawer, your reports should display cash entries whose
type
values areCASH_COLLECTED
andTIP_OUT
.Cash entries whose
type
isCASH_COLLECTED
represent employees adding cash tips into a cash drawer. This does not include cash transactions that are paid into a cash drawer at the time that the guest pays for a check.Cash entries whose
type
isTIP_OUT
represent employees removing cash from a cash drawer to pay non-cash tips or gratuities to restaurant employees. For example, a tip out entry might pay tips that were entered in credit card payments.To display the name of the employee who performed the shift review that created the cash entry, match the GUID of the
employee
1 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.To display the name of the employee who is the subject of the shift review that created the cash entry, match the GUID of the
employee2
value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.When a restaurant employee undoes a
CASH_COLLECTED
entry, there is a correspondingTIP_OUT
entry. In thatTIP_OUT
entry, theundoes
value contains the GUID of the originalCASH_COLLECTED
transaction. Similarly, when a restaurant employee undoes aTIP_OUT
entry, there is a correspondingCASH_COLLECTED
entry. In thatCASH_COLLECTED
entry, theundoes
value contains the GUID of the originalTIP_OUT
transaction. If theundoes
value on a cash entry contains information, your reports should match this cash entry with the original entry it undoes. TheCASH_COLLECTED
and correspondingTIP_OUT
entries may occur on different business days."No sale" transactionsTo report on the addition and removal of miscellaneous cash from the cash drawer, your reports should display cash entries whose
type
value isNO_SALE
.A restaurant employee opens a cash drawer and does not make a change to the cash balance. For example, a restaurant employee might perform a "no sale" transaction to make change for a guest. The restaurant employee can select a pre-configured reason to explain the nature of the no sale transaction.
To display the reason the employee performed the "no sale" transaction, display the
name
of theNoSaleReason
object associated with thenoSaleReason
value on the cash entry. The/noSaleReasons
endpoint of the configuration API returns no-sale reasons.To display the name of the employee who initiated the cash transaction, match the GUID of the
employee
1 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.Cash payments for goods and servicesTo report on cash payments for goods and services, your reports should display cash entries whose
type
values arePAY_OUT
andUNDO_PAY_OUT
.Cash entries whose
type
isPAY_OUT
represent employees removing cash from a cash drawer to pay for goods or services. For example, an employee might pay cash for a window washing service.To display the reason the employee performed the payout transaction, display the
name
of thePayoutReason
object associated with thepayoutReason
value on the cash entry. The/payoutReasons
endpoint of the configuration API returns payout reasons.To display the name of the employee who initiated the payout transaction, match the GUID of the
employee
1 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.To display the name of the employee who approved the payout transaction, match the GUID of the
employee
2 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.When a restaurant employee undoes a
PAY_OUT
entry, there is a correspondingUNDO_PAY_OUT
entry. In thatUNDO_PAY_OUT
transaction, theundoes
value contains the GUID of the originalPAY_OUT
transaction. If theundoes
value on a cash entry contains information, your reports should match this cash entry with the original entry it undoes. ThePAY_OUT
and correspondingUNDO_PAY_OUT
entries may occur on different business days.Delivery driver reimbursementTo report on cash reimbursement of delivery drivers, your reports should display cash entries whose
type
value isDRIVER_REIMBURSEMENT
.Cash entries whose
type
isDRIVER_REIMBURSEMENT
represent employees removing cash from a cash drawer to pay a delivery driver for delivery driving expenses.To display the name of the employee who performed the shift review that created the driver reimbursement transaction, match the GUID of the
employee
1 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.To display the name of the employee who is the subject of the shift review that created the driver reimbursement transaction, match the GUID of the
employee
2 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.CloseoutsTo report on when employees close a cash drawer, your reports should display cash entries whose
type
value isCLOSE_OUT_EXACT
,CLOSE_OUT_OVERAGE
, andCLOSE_OUT_SHORTAGE
.-
If the cash drawer's close out balance is equal to the expected balance, the
type
of the cash entry isCLOSE_OUT_EXACT
. -
If the cash drawer's close out balance is greater than the expected balance, the
type
of the cash entry isCLOSE_OUT_OVERAGE
. -
If the cash drawer's close out balance is less than the expected balance, the
type
of the cash entry isCLOSE_OUT_SHORTAGE
.
To display the name of the employee who initiated the cash transaction, match the GUID of the
employee
1 value on theCashEntry
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.DepositsTo report on cash deposits from the previous business day, display the deposits you retrieved from the
/deposits
endpoint of the cash management API. The amount value indicates theamount
of cash deposited in the cash drawer.To display the name of the employee who deposited the cash, match the GUID of the
employee
value on theDeposit
object with that of the corresponding employee from the/employees
endpoint of the labor API and display the employee name.Expected cash balance in cash drawerFollow these instructions to report on the expected cash balance in a cash drawer at the end of a business day.
Anomalous cash transactionsConsider flagging cash transactions that restaurants may consider noteworthy.
For example, your service may allow restaurants to configure a dollar threshold they consider to be a high-dollar cash transaction. Consider highlighting cash transactions whose value is greater than this threshold.
You can use the
Schedules
object in the restaurants API to determine a restaurant's hours. Consider highlighting cash transactions that occurred after hours. -
You are now ready to provide customers with detailed information about cash transactions, providing restaurants with useful information to understand their daily cash flow.