Building a reservation integration -

Building a reservation integration

Follow the steps below to build a reservation integration with the Toast platform.

This integration allows you to let guests place reservations at Toast restaurants, and provides restaurants with reporting on guest ordering preferences and order analytics.

In this guide, references to submitting reservation information to the Toast platform means using the Toast orders API to send reservation-specific details. Toast does not have a reservation API. Submitting reservation information to the Toast platform is done by submitting an order that only includes the information specific to the reservation. This approach enables your integration to share reservation information effectively and maintain consistency between your system and the Toast platform.

Required scopes

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

config:read
labor:read (this is optional. For more information, see Determine what optional functionality you will support)
labor.employees:read (this is optional. For more information, see Determine what optional functionality you will support)
menus:read
orders.channel:read
orders:read
orders.orders:write (for read-write integration only. For more information, see Building a read-write reservation integration)
restaurants:read

You can retrieve a list of your current scopes through your Toast developer portal account. If you lack the required scopes, refer to the Integration partnership process guide for instructions on requesting access.

Setup and planning

Complete initial integration setup

Review and implement the instructions in How to build a Toast integration.

Determine if you will pass reservation information to the Toast platform

Reservation integrations can follow one of two methods:

Read-only reservation integration: Manage reservations within your system without sharing details with the Toast platform.
Read-write reservation integration: Your integration will pass reservation information to the Toast platform.

With either method, your system will be the source of truth for reservation requests and availability. Toast recommends building a read-write integration to ensure consistency between your system and the Toast platform.

Retrieve configuration information

Retrieve restaurant configurations using the following endpoints of configuration API. To ensure you have the latest restaurant configuration, poll the configuration API once per restaurant location per day, and update configuration information in your system based on newly added, updated, or deleted information.

Alternative payment types (this is optional. For more information, see Determine what optional functionality you will support)
Dining options
Revenue centers
Service charges (this is optional. For more information, see Determine what optional functionality you will support)
Tables

Use the configuration API to retrieve the restaurant configuration you will need for reporting. Configuration options you may need include:

Alternative payment types
Dining options
Discounts
Revenue centers
Sales categories
Service areas
Service charges
Tables

Use the restaurants API to retrieve information about the configuration of a restaurant, including restaurant service hours and location information. Use the restaurant information to ensure guests cannot create reservations outside of the restaurant's hours of operation.

Learn order structure concepts

Familiarize yourself with the structure of an order by reading the Orders API overview and Order object summary. For more information about the orders API, see the reference documentation.

Poll the /ordersBulk endpoint of the orders API using the startDate and endDate query parameters to understand new and modified orders placed within the specified timeframe. Your polling frequency should align with your polling window. For example, if you poll for a window of five minutes, you should poll roughly once every five minutes.

Ensure your integration adheres to the endpoint specific rate-limit for the /ordersBulk endpoint when retrieving order data. For more information about Toast rate limits, see Rate limiting.

To understand which order elements are relevant to your integration, see Understanding reservation order data.

Building a read-only reservation integration

Since your integration will handle reservations entirely within your system, you will rely on the response from the orders API to obtain the necessary order data for updating reservation information in your system. For more information, see Understanding reservation order data.

Building a read-write reservation integration

If your integration is passing reservation information to the Toast platform, you will submit an order without menu item selections and include the required information listed below. Your integration will do this by sending a POST request to the /orders endpoint of the orders API. For more information, see Creating orders.

Understand required information

When passing reservation information to the Toast platform, your integration must include the following information.

Dining option

Include a diningOption with a DINE_IN dining behavior in the order. Send a GET request to the /diningOptions endpoint of the configuration API to retrieve the restaurant's dining options. Your integration should allow restaurants to choose which dining options they want your integration to use in your system's user interface.

Revenue center

Include a revenueCenter in the order. Assigning a revenue center to orders allows restaurants to categorize reservation orders in their revenue reporting. Send a GET request to the /revenueCenters endpoint of the configuration API to retrieve the restaurant's revenue centers. Your integration should allow restaurants to choose which revenue center they want your integration to use in your system's user interface.

Table

Include a table in the order. This links the reservation details to the specific table at the restaurant where the guest will be dining. Send a GET request to the /tables endpoint of the configuration API to retrieve information about a restaurant's tables. Your table configurations should match the table configurations in the Toast platform.

Guest count

Include the numberOfGuests value in the order to identify guest count. This helps restaurant staff prepare and manage the table effectively by knowing how many guests are dining. Additionally, the numberOfGuests provides useful information for building reports.

Tab name

Include a tabName value in the order to identify your integration and guest information. Use the naming convention: {Partner name} - {Guest first name} {Guest last initial}. Your integration should allow restaurants to customize tab naming conventions in your system's user interface based on restaurant requirements.

For more information about where tab names appear in the Toast platform, see Guest personal identifiable information.

Determine what optional functionality you will support

When passing reservation information to the Toast platform, your integration may include the following optional functionality.

Deposits

If your system collects deposits with reservations, you must communicate this information to the Toast platform when you submit the reservation so that the guest is not asked to repay their deposit amount. Deposits are processed through your system when the guest makes the reservation and is communicated to Toast when you submit the order. Deposits are not processed through Toast and use an alternative payment type in the reservation order submission. You are responsible for paying the restaurant for deposits made outside of the Toast platform.

To retrieve your alternative payment type identifier, send a GET request to the /alternativePaymentTypes endpoint of the configuration API and submit this payment type in the payments object of your reservation order. For more information, see Alternative payment types to learn more about submitting payments using the orders API.

If you support deposits, your onboarding process should include working with restaurants to create an alternative payment type specific to your integration. This guide outlines how to create alternative payment types in the Toast platform. Creating an alternative payment type cannot be done via API.

Employee information

You can optionally allow restaurant operators to assign servers to reservations when guests check in. If your integration will support this, send a GET request to the /employees endpoint of the labor API to retrieve information about restaurant employees. Include the identifier of the employee in the server field in your order submission.

Service charges

You can optionally pass service charges with reservation orders. Including a service charge enables restaurants to add additional fees to reservation orders, such as gratuity. To retrieve service charge information, send a GET request to the /serviceCharges endpoint of the configuration API. Your integration should allow restaurants to choose which service charges they want your integration to use in your system's user interface. For more information, see Service charge overview to learn more.

Reservation creation workflow

Create and submit a reservation to the Toast platform

The workflow below outlines how to create a reservation in your system and submit the reservation information to the Toast platform:

The guest creates a reservation in your system.
- If your system requires a deposit, collect it now.
- Ensure guests cannot create reservations outside of the restaurant's hours of operation.
- Collect the reservation information required by Toast for order submission.
When the guest arrives at the restaurant, the restaurant operator checks in the guest through your reservation system. Once checked in:
- Send a POST request to /orders endpoint the orders API containing information about the reservation, including the dining option, revenue center, table, number of guests, and tab name.
- Optionally include payment information for the deposit.
- Optionally include employee information to indicate the server assigned to the reservation.
- Optionally include a service charge.
Update the reservation in your system using the information outlined in Understanding reservation order data.

Example POST request to the orders API

{
  "diningOption": {
    "guid": "374d500f-c6d8-44d0-a18d-43fe5e7f750c"
  },
  "revenueCenter": {
    "guid": "81665a60-c20d-41da-a362-6474eab830d3"
  },
  "table": {
    "guid": "880a2f72-8960-4a3f-b2a2-60b7a19975e7"
  },
  "numberOfGuests": 4,
  "server": {
    "guid": "90d97fb8-931f-4196-aae9-d71bbcd5d3df"
  },
  "checks": [
    {
      "tabName": "Reservation Partner - Ann M"
    },
    {
      "appliedServiceCharges": [
        {
          "serviceCharge": {
            "guid": "9b2dd3cc-f4ab-4586-8c5a-2bbf6a9eef8d"
           }
         }
       ]
     },

    {
      "payments": [
        {
          "type": "OTHER",
          "amount": "20.00",
          "tipAmount": "0.00",
          "otherPayment": {
            "guid": "40dbc841-7f29-47d0-9834-9cf9c5b591d2"
          }
        }
      ]
    }
  ]
}

	The `diningOption` used by restaurants for orders with a dining behavior of `DINE_IN`.
	The `revenueCenter` used by the restaurant for reservation orders.
	The `table` the guest has been assigned to.
	The number of guests for the reservation.
	The employee guid of the `server` assigned to the reservation.
	The `tabName` for the order to identify your reservation and guest information.
	The `serviceCharge` used by the restaurant for reservation orders.
	The deposit amount.
	The guid used to identify the `alternativePaymentType` used for reservation deposits.

Understanding reservation order data

Use the following information from the orders API response to update the reservation in your system in real-time.

Information type	Transactional information	Additional information
Dining option	`order.diningOption.guid`	Review the `guid` value associated with the `diningOption` assigned to the order to understand dining behavior. Orders associated with reservations will have a `diningOption` with a `DINE_IN` dining behavior. For more information, see the orders API reference documentation on the `diningOption` object.
Guest count	`order.numberOfGuests`	Review the value associated with the `numberOfGuests` assigned to the order to understand guest count. For more information, see the orders API reference documentation on the `numberOfGuests` key.
Order status	`order.closedDate`	Review the date to understand when guests have paid for their meal. This indicates that the table will be available soon. For more information, see the orders API reference documentation on the `closedDate`.
Table	`order.table.guid`	Review the `guid` value associated with the `table` assigned to the order to understand `table` assignment. For more information, see the orders API reference documentation on the `table` object. To understand the `table guid` values, send a `GET` request to the `/tables` endpoint of the configuration API to retrieve the restaurant's tables.

Reporting

The /ordersBulk endpoint response of the orders API response will allow you to understand order details required for reporting. Consider reporting on item selection and check amount, including discounts and service charges. Information about orders can also be related to guest profiles managed within your system. Options for reporting categorization that can be understood from the orders API include:

Dining options
Revenue center
Sales categories
Service areas

Use the menus API to retrieve menu and item information to understand guest selections for reporting.

See Building a sales report for additional guidance on order reporting.