Creating orders

To create an order in the Toast platform, you send a POST request that contains a JSON Order object to the /orders endpoint of the orders API.

Before you POST the order, you must GET the check prices from the /prices endpoint. The /prices endpoint is the only reliable and supported way to determine the payment amount for a check.

If you POST an order with a payment amount that does not match the results from the /prices endpoint, then restaurant employees must handle the underpayment or overpayment during order fulfillment.

Order creation process for the orders API

To use the orders API to create and POST a new order:

  1. Create a JSON Order object that includes the dining option, checks, and menu item selections for the order. You can also include a revenue center.

    For information about the required details for different dining options, as well as example order objects for each type, see Order details based on the order dining option.

    For other limitations on menu selection items, scheduling, and how orders from the API are processed, see Orders API limitations.

    For information on providing revenue center information in an order, see Providing revenue center information for an order.

    To create a scheduled order to be fulfilled at later time, provide a promisedDate value. See Scheduling future orders.

    For detailed information about all of the values in an Order object, see the reference documentation for the orders API.

  2. Retrieve the price information for the order.

    To do this, send a POST request to the /prices endpoint of the orders API. In the message body of the POST request, include the JSON Order object. See Get order prices.

    The Order object returned by the /prices endpoint includes the base price, tax amount, and total price of each check.

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

  3. Optionally, add payment information for the checks to the Order object.

    To include payment information for a check, add a payments value to the Check object.

    The payment type must be either CREDIT or OTHER.

    For more information about CREDIT payments, see Credit card payments.

    For an OTHER type payment, include in the Payment object the GUID of a previously configured alternative payment type. Note that the orders API ignores the tax exempt setting for the payment type. The order is taxed regardless of whether the payment type is configured to be tax exempt.

    Payment information is optional. If an order is not yet paid for, you can omit the payments value. When the order is paid for, you can update the order to add the payment information. See Adding payments to an existing check.

  4. Send a POST request to the /orders endpoint of the orders API.

    The body of the POST request contains the JSON Order object for the order.

  5. The response from the /orders endpoint indicates whether the order was created successfully.

    The orders API does not verify the restaurant service hours before it creates the order. It creates the order even if the restaurant is closed.

    If a restaurant uses a Kitchen Display System (KDS) device, and has properly configured an auto-firing device, then the order is sent directly to the kitchen. The order is not subject to approval rules or manual approval when an auto-firing device is used.

Orders API limitations

When using the orders API to create an order, be aware of the following limitations and default behavior.

Order scheduling

By default, the orders API creates an order that is to be fulfilled as soon as possible. It does not verify the restaurant service hours.

You are responsible for submitting orders while the restaurant is open. For more information, see Getting information about a specific restaurant.

You also can create an order to be fulfilled at a specific time. For example, you can create an order when the restaurant is closed, but indicate to fulfill the order when the restaurant is open. See Scheduling future orders.

Order menu selection items

For the menu selection items in API orders, the following limitations apply:

  • You cannot add open menu items to an Order object. An open menu item is one where the restaurant employee specifies both the item description and price.

    However, you can add open priced menu items. An open priced menu item has a specified description. The restaurant employee only specifies the item price.

  • The orders API cannot verify the availability of items based on time, menu visibility, or inventory.

    You are responsible for preventing guests from ordering items that are not available.

Order payment

Orders created using the orders API are limited to the CREDIT and OTHER payment types.

Note that the orders API ignores the tax exempt setting for OTHER payment types. The order is taxed regardless of whether the payment type is configured to be tax exempt.

The orders API does not allow you to create cash orders or orders that use Toast gift cards.

Loyalty programs

You cannot use Toast loyalty functionality with orders that are created using the orders API.

You can use the orders API to apply a third-party loyalty program that is integrated with Toast. For details, see Working with loyalty programs.

Order communication to the kitchen

If a restaurant uses a Kitchen Display System (KDS) device, and has properly configured an auto-firing device, then the order is sent straight to the kitchen.

The order is not subject to approval rules or manual approval.

Order text messages

Orders that are entered using the orders API do not initiate SMS text messages. Guests or servers only receive text messages when an order is entered in the Toast platform, for example, from a Toast POS device.

To allow guests to receive order fulfillment text messages from your platform, you must build this functionality based on the approvalStatus value on the order.