Follow the steps below to build a delivery dispatch integration with the Toast platform.
This integration allows you to provide dispatch information to restaurants and guests for delivery orders throughout the delivery process. If you support first-party delivery, this integration also allows you to update the employee associated with delivery orders.
To follow these instructions, you must have the following scopes:
-
config:read -
delivery_info.address:read -
guest.pi:read -
labor:read -
labor.employees:read -
orders:read -
orders.delivery_info:write -
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.
Review and implement the instructions in How to build a Toast integration.
Within Toast Web, restaurants must enable first-party delivery in their delivery settings when using a delivery integration. Restaurants cannot use both Toast Delivery Services and a delivery integration simultaneously. For guidance on how restaurants can enable first-party delivery, see Configuring first-party delivery.
To successfully retrieve information relevant to delivery orders, 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.
Use the configuration API to retrieve the dining options configuration you need to dispatch drivers and deliver orders.
Use the restaurants API to retrieve general information about the configuration of a restaurant. If you support first-party delivery, the delivery area configured by restaurants in Toast Web is available in the restaurants API. The delivery area is only configurable when restaurants have first-party delivery enabled. To learn more about how restaurants configure their delivery area, see Configuring your delivery area.
To ensure you have the latest restaurant configuration, poll the configuration API and restaurants API once per restaurant location per day, and update configuration information in your system based on anything that was added, updated, or deleted.
All Toast orders contain a dining option with a defined dining
behavior. Your integration can only update orders whose
diningOption has the behavior of
DELIVERY. You can understand dining option dining behavior
by calling the /diningOptions endpoint of the configuration
API. Restaurants may have multiple dining options configured with the
delivery behavior. Your integration should allow restaurants to choose
which dining options they want your integration to deliver in your
system's user interface.
For more information about the /diningOptions
endpoint of the configuration API, see the reference
documentation.
If your integration supports restaurants fulfilling delivery
orders using the restaurant's own drivers (first-party delivery), versus
using drivers provided by your integration, you need to pass the Toast
platform GUID of the employee assigned as the delivery driver in your
PATCH request to the /deliveryInfo endpoint of
the orders API.
To get information about the employees of a restaurant, send a
GET request to the /employees endpoint of the
labor API.
For more information about the labor API, see the reference documentation.
Information is limited in the orders API response for catering orders. Your integration will only have access to the data that is captured in the following sections of the Toast Catering and Events page under Create order in Toast Web.
In the Customer section, the guest's first
and last name, email address, and phone number are exposed in the
customer object of the orders API.
In the Order details section, the
Deliver to address and Delivery
notes are exposed in the deliveryInfo object of
the orders API.
Toast does not expose additional catering information in the orders API besides what is available in the two sections outlined above. When integrating with restaurants using the Toast Catering and Events module, it is important they understand what your integration can access. This way, they can build their catering orders so that your integration has the information needed to fulfill the delivery.
To understand if an order is a catering order, reference the
source value in the orders API response. Catering orders
have have a source value of any of the following:
-
Invoice -
Catering -
Catering Online Ordering
For more information about Toast Catering and Events, see Get Started with Toast Catering and Events.
Your integration will need real-time order data. 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.
Your integration can understand which orders to fulfill based on dining options. Allow restaurants to specify which dining options they would like fulfilled for delivery dispatch. A restaurant may not want your integration to deliver all delivery orders it receives. For example, a restaurant may use a third-party ordering source that submits and dispatches delivery for some dining options but not others.
The Toast platform supports as soon as possible (ASAP) orders
and scheduled orders. Both of these order types return an
estimatedFulfillmentDate in the order object
of the orders API. The estimatedFulfillmentDate indicates
the date and time the order is expected to be delivered. Scheduled
orders also include a promisedDate, which is the time the
order has been scheduled for delivery. Your integration should use the
promisedDate to know when to dispatch drivers. Including
delivery details for scheduled orders in your integration allows
restaurants to understand future delivery schedules.
Examine the deliveryInfo object from the orders API
to understand where orders will be delivered. The
deliveryInfo object contains the delivery address and
delivery notes.
The customer object in the orders API will provide
the name, email address, and phone number of the guest who placed the
order.
Understand if an order has been paid and determine if your
integration will collect cash on delivery. To understand if an order
has been paid, examine the paymentStatus from the
order.check object of the orders API for values
PAID or CLOSED. The payment status of the
check may be updated after the initial order creation. As you poll the
/ordersBulk endpoint of the orders API, examine modified
orders for updates to the paymentStatus.
If your integration supports the collection of cash payment on
delivery, these orders will have a paymentStatus of
OPEN, indicating there is a balance due.
|
Note |
|
Orders may contain multiple check objects. |
Learn how the Toast platform structures delivery information
PATCH requests. Follow the Updating delivery information for an order guide to use the orders
API to update the delivery information for orders using the
/deliveryInfo endpoint of the orders API.
Place a test update by following the steps in the Example API requests guide.