Technical considerations for regional expansion

You will use the same Toast API endpoints across regions, but certain configurations and fields may vary. When offering your integration to new regions, use the guidance below to ensure your integration functions correctly.

Note

Toast operates in Australia, Canada, Ireland, the United Kingdom, and the United States. Other locations may be added at a later time.

Location configuration information

To view location configuration information, send a GET request to the /restaurants endpoint of the restaurants API. The following values change depending on the geographic region of a location:

  • In the Location object, the country value indicates the country in which the location operates.

  • In the Location object, the administrativeArea value is the name of the geographical region of the location, such as a state, province, or county, depending on the location's country.

  • In the General object, the currencyCode value is the ISO-4217 currency code used at the location. Any monetary value returned from any Toast API will use the currencyCode.

Menu pricing

Menu items can be configured as tax-inclusive or tax-exclusive on a per-item basis, using the taxInclusion field. This is a menu configuration setting, not a fixed property of a geographic region, so a single location, and even a single order, can include a mix of tax-inclusive and tax-exclusive items. Consumer pricing conventions vary by country, for example, tax-inclusive pricing is standard practice (and often legally required) in the United Kingdom, Australia, and Ireland, while tax-exclusive pricing, where tax is added at checkout, is standard in the United States and Canada. Whether your integration needs to check the item's own taxInclusion value, and how, depends on what your integration is doing.

Even though the Toast platform calculates the final, authoritative prices for an order, your integration may still need to understand tax inclusion directly. For example, if you're building a shopping cart or menu display where guests see running totals before checkout, you need to know whether a listed price already includes tax to show an accurate subtotal. Similarly, if you're building sales or accounting reports from completed orders, you need to know whether a discount or price value includes a tax component so your calculations are accurate.

Tax inclusion values across APIs

taxInclusion is represented differently depending on which API you're reading from, and differently again for a modifier than for the menu item it applies to. The following details will help you interpret the value correctly wherever you encounter it.

  • The menus API and orders API represent tax inclusion with different values. In the menus API, MenuItem.taxInclusion is TAX_INCLUDED or TAX_NOT_INCLUDED. In the orders API, Selection.taxInclusion is INCLUDED or NOT_INCLUDED on a menu item selection, or INHERITED on a modifier selection. Check the correct value set depending on which API your integration is reading from.

  • Modifiers always inherit the tax inclusion behavior of the menu item they apply to. In the orders API, a modifier's own Selection.taxInclusion value is always INHERITED, this is the only case where INHERITED appears, since a non-modifier selection that inherits its tax inclusion setting from a menu or menu group is still reported as INCLUDED or NOT_INCLUDED. A modifier's own tax and appliedTaxes values are always zero. The modifier's tax impact is calculated together with the parent item and reported in the parent selection's price and tax values, not in the modifier's own selection. In the menus API, the modifierOptionReferences object does not expose a taxInclusion field at all, only MenuItem does. The INHERITED value only appears in the orders API, on a modifier's Selection object once it's applied to an order, so don't expect to find it on the menu side.

Displaying menu prices to guests

If you display menu prices to guests (for example, in a kiosk, online ordering flow, or receipt), use the taxInclusion value to understand whether the displayed price already reflects tax. Don't assume every item on a menu, or every location in a given country, uses the same pricing model.

Calculating totals for order placement

When placing an order, use the /prices endpoint to retrieve check and item prices calculated by the Toast platform. This is the only supported way to determine the amount to charge a guest, and it already accounts for tax inclusion correctly. For more information, see Order prices.

Calculating totals and building reports

Your integration may still calculate totals independently of the orders API response, for example, when reporting on orders that have already been placed. In that case, check each item's taxInclusion value before summing or displaying totals, since inclusion is set per item and a single order can require different handling for different line items. When calculating totals across an item and its modifiers, sum each selection's price and tax independently, your totals will already be correct. Don't calculate tax per modifier using the modifier's own tax or appliedTaxes fields, since those are always zero under INHERITED, and doing so will undercount.

If you build sales or accounting reports from order data, keep the following in mind:

  • check.amount and selection.price always exclude tax, regardless of an item's taxInclusion setting. Tax is reported separately, as taxAmount on the Check object and as tax on the Selection object. taxInclusion affects how the guest-facing price is built and displayed, not whether amount, price, or taxAmount include tax.

  • If your integration calculates prices from menu data instead of reading order fields directly (for example, multiplying a menu item's listed price by quantity), check the item's taxInclusion value first. A tax-inclusive listed price is not the same as the selection.price value returned by the orders API, since selection.price always has tax removed.

  • When totaling discounts, sum the discountAmount value on each AppliedDiscount for tax-exclusive items. For tax-inclusive items, sum nonTaxDiscountAmount instead. For tax-exclusive items, these two values are the same, since there's no tax component to separate out; for tax-inclusive items, discountAmount includes a portion attributable to tax, and using it directly will overstate how much the discount reduced the item's price.

  • If you report total tax collected, or break that total down by individual tax rate, you don't need to change your logic based on taxInclusion. The taxAmount value is reported the same way regardless of whether an item is tax-inclusive or tax-exclusive.

For full guidance on building these reports, see Building a sales report.

Orders

When submitting orders to the orders API, consider regional variations in formatting.

  • If you include guest information when you create orders using the orders API, include a phoneCountryCode value in the Customer object for non-US phone numbers.

  • When updating the DeliveryInfo object in the orders API, use the guidance in the Orders developer guide to determine whether to use the state or administrativeArea value.

Payments

The Toast platform cannot process credit card payments in regions outside of the United States. Instead, use an alternative payment type when placing an order using the orders API.

Labor

When adding or updating employee phone number information in the labor API, ensure that the phoneNumberCountryCode value is accurate for the region of the employee's location.

Outbound integrations

If you have a loyalty integration, ensure that your integration can accept the appropriate phone number length for LOYALTY_SEARCH transactions.