Building an ordering integration

Follow the steps below to build an online ordering integration with the Toast platform.

To follow these instructions, you must have the following scopes:

  • config:read

  • credit_cards.authorization:write

  • digital_schedule:read

  • menus:read

  • orders.delivery_info:write

  • orders.orders:write

  • restaurants:read

  • stock:read

Initial Setup and Testing

  1. Complete initial integration setup 

    Review and implement the instructions on the Getting Started section.

  2. Learn menu hierarchy concepts 

    To familiarize yourself with restaurants' menu structure, read Toast's menu hierarchy documentation. Then use the menus API to retrieve the full menu from a test location so that you understand the menu structure and review menu hierarchy information before you begin development related to menus.

  3. Retrieve configuration components 

    Use the configuration API to retrieve the configuration you will need to place successful orders. Configuration options you may need include:

    • Dining options

    • Discounts

    • Revenue centers

    • Service charges

    • Tax rates

    • Alternative payment types

  4. Place a test order 

    To learn how Toast platform orders are structured, place an order using example API requests. To place a successful test order, you will need to retrieve an authentication token and replace the entity identifiers in the test order with entity identifiers at your test restaurant (retrieved through the configuration and menus APIs).

Functionality Planning

  1. Determine how you will use free-text fields 

    You can set checks’ tab names and display numbers in the way you choose. Toast support recommends using these fields in the following ways:

    • Use the following tab name structure: “Your company name - order number”, where “order number” represents the order number in your own system.

    • Do not include a custom display number when submitting orders. This way, the Toast platform will automatically set a check number to the integer following the previous check number.

    • If you want to provide the ability to include order-level notes, submit a special request as an item selection on an order. For example, guests might use this selection to request specific packaging.

  2. Decide which menu item pricing strategies you will support 

    Most Toast online ordering integrations support base price, menu-specific pricing, and size pricing. Supporting time-specific pricing is recommended and will be a differentiator for your integration.

  3. Decide which modifier group pricing strategies you will support 

    In addition to the menu item pricing strategies described above, modifier groups can also use sequence pricing and size/sequence pricing. Using these pricing strategies is a recommended differentiator for your online ordering integration.

Menu Display

  1. Build your menu display 

    Your menu should display at least menu entity names (at all levels of the menu hierarchy), item descriptions, item images, and prices. Displaying item tags is recommended and optional (common item tags include “gluten free” and “vegetarian”). For more information about the menus API, see the reference documentation. Be sure your menu display allows multiple menus, multiple menu groups within a menu, subgroups within menu groups, and menu items shared by multiple groups.

  2. Filter based on menu visibility 

    Restaurants can decide whether or not a menu entity should be visible in online ordering integrations. Your integration should only display menu entities if they are configured to be visible to ordering partners. For more information about menu visibility, see Determining if a menu entity should be visible on an ordering partner site.

  3. Only display a menu while it is configured to be available 

    Restaurants can configure menus to only be available at certain times of day, such as a brunch or happy hour menu. Your integration should only display menus when their corresponding Availability object in the /menus endpoint of the menus API says that they should be visible. Consider Daylight Savings Time when building menu display times.

  4. Update menus on a near-real-time basis 

    The menus webhook and the /metadata endpoint of the menus API tells you the timestamp of the most recent change to a restaurant's published menu. IF you do not use the menus webhook, your integration should poll the /metadata endpoint once every 1-5 minutes and retrieve new menu information if and only if the webhook or /metadata endpoint says that the menu has changed since you last retrieved it. For more information about menu syncing, see Determining if a restaurant's menu data has gone stale.

  5. Avoid infinite loops when parsing menus 

    There is a rare but possible menu configuration that can send your integration into an infinite loop when parsing a restaurant menu. To avoid this problem, see Detecting and avoiding infinite loops in the menus API JSON.

Handling Out of Stock Items (86'ing)

  • Display item stock information 

    Your menu display should prevent guests from ordering items that are out of stock. Use the stock webhook to receive real-time notifications about item stock updates. Fall back to the stock API if you ever miss a webhook update or in case your webhook subscription is ever paused. See this page information about how to test out of stock items.

Handling Dining Option Behavior

  1. Review dining option behaviors 

    The “behavior” value on a dining option controls the order data you are required to submit. For more information about dining option behaviors, see Types of dining options.

  2. Build takeout order UI 

    When a guest submits a takeout order, you must submit the guest name, phone number, and email address with the order. For more information about submitting takeout orders, see Creating a takeout order.

  3. Build curbside pickup order UI 

    When a guest submits a curbside pickup order, you must submit the guest name, phone number, and email address with the order as well as information about the guest’s mode of transport. For more information about submitting curbside pickup orders, see Creating a curbside pickup order.

  4. Build delivery order UI 

    When a guest submits a delivery order, you must submit the guest name, phone number, email address, and delivery address with the order. For more information about submitting delivery orders, see Creating a delivery order.

  5. Validate guest information format 

    Guest phone numbers must contain ten numeric digits. Guest email addresses must be unique per individual guest and must contain an at-sign (@) and a period (.).

Handling Modifiers

  1. Handle default modifiers 

    The isDefault boolean value on modifier options indicates whether or not a modifier option is included with its parent menu item by default. If a modifier option is a default modifier on its parent item, your integration should display it be default and guests should have the option to remove it. For example, a hamburger menu item may include lettuce or tomato modifier options by default, but guests may want to remove one or both of these default options.

  2. Handle minimum and maximum selection options 

    Modifier Groups have minSelection and maxSelection values that describe the minimum and maximum number of selections a guest may make from a modifier group. Your ordering integration must enforce these values.

  3. Handle duplicate selections from a modifier group 

    The allowsDuplicates boolean value on a modifier group indicates whether a guest can select the same option from a modifier group multiple times on the same menu item selection. For example, if allowsDuplicates is true for a pepperoni modifier option on a pizza menu item, a guest may add two servings of pepperoni to their pizza. If allowsDuplicates is false, the guest may only add one serving of pepperoni to their pizza. See Requirements for modifier quantities for information about how to apply multiple quantities of the same modifier option on a menu item selection.

  4. Handle nested modifiers 

    Restaurant employees can nest modifiers as deeply as they want in a menu.. For example, a “burger” menu item may have an “add-ons” modifier group, which includes a modifier option of “cheese.” The “cheese” modifier option may include its own modifier group of “cheese type,” which contains modifier options of “American” and “Swiss.” Your integration should be able to handle at least three layers of nested modifiers (meaning an item and three layers of modifiers).

  5. Handle pre-modifiers 

    Modifier groups can have associated pre-modifiers. Common examples of pre-modifiers include “no,” “light,” “extra,” or “on the side.” As a differentiator, it is beneficial for your integration to allow guests to include pre-modifiers in the ordering process.

  6. Handle special requests 

    Orders can have free-text special requests on menu items and modifiers. To add special request functionality to your ordering integration, see Special requests and instructions.

Order Timing

Review Daylight Savings Time documentation when developing functionality related to order timing.

  1. Display restaurant hours 

    Use the /orderingSchedule endpoint to retrieve a restaurant location’s hours of operation. Display these hours on the restaurant's ordering site. Use these hours to control the times at which you submit orders. You are responsible for preventing order submission while the restaurant is closed; the orders API does not enforce restaurant hours.

  2. Build future order functionality 

    If your integration will support future order submission (for example, placing a catering order on Monday to be fulfilled on Friday), review the instructions on Scheduling future orders. In particular, ensure that the openedDate and promisedDate on a future order match one another and are both the expected time of order fulfillment. Use the order management configuration API to determine if a restaurant accepts future orders and the number of days in the future guests may schedule orders. Also be sure to accommodate daylight savings time when building future order submission functionality.

Pricing

  1. Charge prices calculated by the Toast platform 

    Before charging a guest for an order, call the /prices endpoint of the orders API to get the price of each item selection calculated by the Toast platform.. For an order to arrive fully paid, the payment you submit must match the Toast platform price for the item selection, including taxes. It is critical that you charge the order and tax price returned in the /prices endpoint. For more information, see Getting check prices before you submit an order.

  2. Display correct prices in your UI 

    The Toast platform has many pricing strategies and you will need to display accurate prices to guests. For more information about the Toast platform’s more complex pricing strategies, see Using PricingRules and PricingStrategy to calculate prices.

  3. Calculate taxes 

    The /prices endpoint of the orders API provides the taxes associated with an order. If you want to calculate taxes yourself for display purposes, you can do so using these instructions.

  4. Handle discounts 

    The isDiscountable value on MenuItem objects in the menus API indicates whether or not an item can be discounted. Do not allow guests to apply discounts to menu items that have an isDiscountable value of false. If your integration will allow guests to use discounts, see Applying discounts to a new order for more information.

  5. Service charges 

    Restaurants may add service charges to orders. Examples of service charges include delivery fees and automatic gratuities. For more information about adding services charges, see Service charges for checks.

Payments

Steps 1-3 only apply to ordering integrations who use Toast’s credit cards API.

  1. Encrypt card data 

    Before submitting an authorization request, you must create an encrypted card data string using the credit card encryption key that Toast support provides. For more information about encrypting card data, see Encrypting credit card information.

  2. Authorize credit cards 

    After you create an encrypted card data string, you submit the string in a credit card authorization request with the other required metadata. For more information about credit card authorization, see Authorizing a credit card payment.

  3. Distinguish between new and saved cards 

    The cardNumberOrigin value on credit card authorization requests must distinguish between new and saved credit cards. When a guest pays by manually entering credit card information, cardNumberOrigin should be END_USER. When a guest pays with a credit card using saved information that is stored in an external vaulting service, cardNumberOrigin should be PARTNER_VAULT. For more information, see Optimizing fraud detection.

  4. Submit payments 

    If you use the Toast credit cards API, you should submit the payment you authorized using these instructions. If you are not using the’s credit cards API, you submit payments using alternative payment types. A restaurant's alternative payment types can be found in the configuration API.

  5. Submit tips 

    To submit tips, populate the tipAmount value on your payment authorization and include a tipAmount on the payment you submit with an order.

  6. Document your refund workflow 

    If you use the Toast credit cards API, servers can refund guests using the Toast POS. If you do not use the credit cards API, servers must separately refund guests out of the Toast POS and your credit card processing system. In either case, you will need to explain how to process refunds for restaurant employees.

Delivery Dispatch

  • Update delivery status over time 

    If your online ordering application supports delivery orders and your organization manages the employees who deliver them, you can update the orders' delivery information when that information becomes available. You can update the order's delivery status, dispatch and delivery timestamps, and assigned delivery employee. For more information, see Updating delivery information for an order.

Reporting

  • Submit revenue centers 

    To make it easier for restaurants to report on which orders came from your integration, submit revenue centers on your orders. You can retrieve revenue centers from the configuration API. Instructions for adding revenue centers to orders are here.

Configuration Syncing

  • Sync configuration regularly 

    After your integration goes live, restaurants may add, change, or remove configuration such as dining options and revenue centers. Your integration should check the configuration information that is available from the configuration API and alert your organization if a restaurant has deleted any configurations your integration relies on.

Once you have completed and tested the steps above, you will be ready to complete an end-to-end test of your integration functionality. Congratulations on building your online ordering integration!