This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Orders API Overview

An order can contain multiple checks. Checks in an order include information about the menu items that have been provided to restaurant customers or that will be provided in the future. A check can also contain detailed information about the services a restaurant provides. For example, information about payments, guests, discounts, service charges, and restaurant employees.

The following diagram shows checks, menu item selections, guest information, payment information, and delivery information in an order.

You can use the orders API to:

  • Get information about an existing order. For more information, see Orders API overview.

  • Get prices for the checks in an order that you have not created yet. For more information, see Getting check prices before you submit an order.

  • Create an order, with payment or without payment. If you create an order without payment information, you cannot use the orders API to add payment information to it later. For more information, see Creating orders.

  • Get information about payments made for checks. For more information about the orders API endpoints for getting payment information, see the reference documentation for the orders API.

A common use of the orders API is to get calculated price and tax information for an order and then create that order in the Toast platform. The following procedure explains how to get order prices and then add the order in the orders API.

Getting Order Prices and Creating an Order

  1. Create a JSON Order object that includes the dining option, checks, and selections (menu items) for the order. For some dining options, you may need to add more information. For example, an order with a dining option configured with the Take Out behavior requires information about the guest who will pick up the order.

    For an example of an Order object, see Example Order object for a request to the /prices endpoint. For detailed information about the values in an Order object, see the reference documentation for the orders API.

  2. Get the price of each check in the order by sending a POST request to the /prices endpoint of the orders API. Include the JSON Order object for the order in the message body of the POST request.

    Find the price for each check in the response data returned by the /prices endpoint. The response data includes the price, tax amount, and total price of each check.

    For more information, see Getting check prices before you submit an order.

  3. Include payment information for the checks in the JSON Order object for the order. You can include payment information for a check by adding a payments value to the Check object in the Order object for an order.

    For an example of a payments value for a check, see POST request message body to create a dine-in order with payment information. For detailed information about the payments value and the Check object, see the reference documentation for the orders API.

    Payment information is optional, if you want to create an order that has not been paid for, you can omit the payments value for the checks in that order.

  4. Send a POST request to the /orders endpoint of the orders API. Include the JSON Order object for the order in the message body of the POST request.

  5. Find information about the order that you created in the response data returned by the /orders endpoint. For an example of the response data, see Orders endpoint response for a dine-in order with an alternative payment.

Important

You must get check prices from the /prices endpoint before POSTing an order. The /prices endpoint is the only reliable and supported way to determine the payment amount for a check. If you POST an order with an inaccurate payment amount, the Toast platform will require restaurant employees to handle the underpayment or overpayment during order fulfillment. For more information, see Rounding options.

The following sections provide information about Toast platform orders.