This document describes the changes in Toast API releases.
|
Note |
|
As Toast products continue to improve, historical release notes may not reflect the current state of API functionality. For the most up to date API information, see the Toast API Reference. |
For more information about using Toast APIs and building integrations, see the How to build a Toast integration.
When a gift card is purchased, the first five and last four digits
of the new gift card identifier are now visible in the orders API
response. The gift card identifier is found in the
giftCardSelectionInfo field of the orders API
selections object.
The first five digits are shown if the following criteria is met:
-
Your API client has the
orders.gift_cards:readscope. -
The gift card identifier is fewer than 15 digits.
-
The gift card provider encrypts the gift card.
-
The gift card is scanned using a QR code scanner during the gift card purchase.
For more information about gift cards, see the Gift cards integration overview.
This change is in limited release. This change does not affect all Toast POS locations.
You can now use the
/orders/v2/orders/{orderGuid}/void endpoint to void orders
placed in error, for the wrong location, or when a guest changes their
mind.
To void an order, you must have the
orders.channel:void scope. At this time, you can void orders
with the Other payment type. Voiding orders paid
with cash, card, or a Toast gift card is not supported. Additionally,
orders with discounts and orders already voided, deleted, or restricted
cannot be voided using this endpoint.
For more information, see Void an order.
On 2025-06-16, the cardType value in the loyalty
integration API Payment object will include new enumerated
values. Make sure your loyalty API integration will handle new
cardType values before 2025-06-16. For information about
the cardType value, see the
Payment object reference documentation.
|
Note |
|
Your integration should handle unexpected values in any Toast API enumerated value without disrupting restaurant operations. |
On 2025-05-05, the source value in the
Order object of the orders API will include new enumerated
values. The source value indicates the way that a Toast POS order was
created. The new values are:
-
ECOMMERCE_OO- the order was created by a Toast Online Ordering Pro e-commerce site. For more information about e-commerce sites, see this Toast Central article. -
BRANDED_MOBILE_APP- the order was created by a Toast branded mobile app ordering application. For more information about branded mobile apps, see this Toast Central article.
Make sure your integration can handle these new order source
values before they appear in production orders API response data on
2025-05-05. For more information about the orders API Order
object, see Toast
API reference documentation.
|
Note |
|
Your integration should handle unexpected values in any Toast API enumerated value without disrupting restaurant operations. |
The MenuItem and ModifierOption objects
of the menu item have been updated to include the following
values:
-
length: The length of the item or modifier. -
height: The height of the item or modifier. -
width: The width of the item or modifier. -
dimensionUnitOfMeasure: The unit of measure for the length, height, and width values. -
weight: The weight of the item or modifier. -
weightUnitOfMeasure: The unit of measure for the width value. -
guestCount: The number of guests the item or modifier is intended to serve.Note
Size-priced items use modifiers to define their sizes. For example, a pizza with the Small modifier could serve 1 guest while a pizza with a Large modifier could serve 2.
-
images: An array of strings that contain URLs for images that have been uploaded for the menu item or modifier. The array is empty if no images have been uploaded.Note
The
imagesarray contains multiple URLs for multiple images for the same menu item or modifier. The olderimagevalue contains a single URL for a single image of the item or modifier.
The length, height, width,
dimensionUnitOfMeasure, weight, and
weightUnitOfMeasure values can be used to determine the
overall size and weight for an item or modifier. This information is
useful, for example, when calculating shipping costs or determining a
delivery vehicle to use. All of these values can be null if
they are not specified.
Like all changes to the menus API, these new values become available in the response data after a restaurant has made a menus-related change and published the new menu, which regenerates the restaurant's menu data. For more information, see Menus API returns published data only.
This change applies to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
On 2025-06-23, the tender API will change the way it represents
Toast POS checks in requests it makes to your integration. On
2025-06-23, the
Check object in some tender API requests will
reflect Toast POS checks in the same way that the
orders API represents guest checks. This will fix some current
problems with tender API Check object information.
This change to the tender API behavior will affect the information about guest checks that you receive from the integration. For example:
-
The
appliedServiceChargesarray in the tender APICheckobject will include anAppliedServiceChargeobject for each service charge on the check. Currently, the array is empty even when a check includes service charges. -
The
totalAmountvalue in the tender APICheckobject will correctly include the total price of the check, including taxes and discounts. Currently, this value is alwaysnull. -
The
amountvalue in the tender APICheckobject will correctly include the check price after discounts but before tax. Currently theamountvalue includes the check price after discounts and after taxes. -
The
modifiersarray in the tender APISelectionobject will include aSelectionobject for each modifier for a menu item selection. Currently, the array is empty even when a menu item selection includes modifiers.
This change does not affect all tender API request types. Some request types already use the orders API check object behavior, some request types will change the check behavior on 2025-06-23, and one type will not change the check behavior. The following table describes which request types are changing check behavior and when the changes will happen.
|
Request type |
Check object change status |
|---|---|
|
The |
|
The |
|
The |
|
These tender API request types do not include a
|
The change to the tender API Check object is
currently deployed in the Toast API sandbox
environment. Verify that your tender API integration handles the
updated guest check information in the sandbox environment before the
change is deployed in the production environment on 2025-06-23.
For more information about the tender API, see Tender provider integrations overview.
On 2025-06-16, the cardType value in the orders API
Payment object will include new enumerated values. Make
sure your orders API integration will handle new cardType
values before 2025-06-16. For information about the
cardType value, see the
Payment object reference documentation.
|
Note |
|
Your integration should handle unexpected values in any Toast API enumerated value without disrupting restaurant operations. |
On 2025-05-26 the payload of the orders webhook will no
longer include the itemType value in the
AppliedPackagingItem object. This value does not include
any information and is always null. Before 2025-02-19, make
sure your orders webhook integration will function correctly without the
null itemType value.
On 2025-05-26, the selectionType value in the
Selection object in the
orders API ordersBulk endpoint will include two new enumerated
values. The following values indicate that the selection is a Toast gift
card purchase or a transaction to add value to a Toast gift card.
-
TOAST_CARD_SELL -
TOAST_CARD_RELOAD
Beginning on 2025-05-26, the order information that you get from
the ordersBulk endpoint might contain these new
selectionType values. Make sure your integration will
handle the new values without interruption.
These two enumerated values were added to other orders API response data in a previous Toast API update.
On 2025-05-12, the orders API will restrict the size of
POST request message body parameters to 1 megabyte (1 MB).
On 2025-05-12, if you include more than 1 MB in the message body of a
POST request, the orders API will return an HTTP 400 error
response.
This change affects all orders API endpoints that accept a message body parameter. For example, the change affects the following endpoints:
The orders API already restricts Order
objects in POST requests to 1000 top-level Selection
objects. The new message body size restriction is in
addition to the 1000 selection limit.
The orders API message body size restriction is currently in
effect for the Toast API sandbox environment.
You can test your orders API integration to make sure that the message
body parameters for POST requests do not exceed 1 MB before
the restriction is enforced in the production environment on
2025-05-12.
The MenuItem object has been updated with an
eligiblePaymentAssistancePrograms value. This value
contains an array of strings that indicate which payment assistance
programs may be used to pay for the menu item. Possible strings include
SNAP.
The eligiblePaymentAssistancePrograms array is empty
if no eligible assistance programs have been assigned to the menu
item.
The eligiblePaymentAssistancePrograms value is
primarily used by Toast Retail services. It allows retail locations to
charge a menu item to an electronic benefits transfer (EBT) card
associated with one of the eligible assistance programs assigned to that
item. Currently, only the United States Supplemental Nutrition
Assistance Program (SNAP) program is supported.
This new value will become available in the menu API response data after a location has made a menus-related change and published the new menu, which initiates regeneration of the location's menus data. For more information, see Menus API returns published data only.
This change applies to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
On 2025-02-03, the tender API search configuration request sent by the Toast platform will no longer include a body parameter. The search configuration request does not require a body parameter and does not include any meaningful body parameter content in current requests.
This change has been made in the sandbox environment so
that you can test your integration. Make sure your tender API
integration can accept HTTP POST search configuration
requests that do not include a body parameter before 2025-02-03.
For more information about the tender API search configuration request, see Configure search.
When you authenticate your API client to use Toast APIs, you must
provide a bearer-type authentication token in the
Authorization header field of your request. The string
Bearer is a required part of the header field format
Authorization: Bearer
.
[token]
On 2024-10-28, the Toast APIs will enforce the required bearer
token Authorization field format, including the string
Bearer. If your integration does not include the string
Bearer in the Authorization header field for
all Toast API requests, implement authentication in a way that includes
that string. Requests without the required bearer token field format
will receive an error response
For more information about Toast API authentication, see Using an authentication token.
The Toast platform includes a new orders updated webhook. You can use the orders updated webhook to receive order updates as they occur. The orders updated webhook provides details about new orders, and updates to existing orders. When a restaurant makes any update to an order, or creates a new order, the orders webhook sends an HTTP request to an endpoint you specify using the order_updated webhook event.
The HTTP request that you receive includes:
-
The Toast platform unique identifier (GUID) of the order_updated event.
-
A timestamp value indicating when an order is updated or created.
-
An Order object containing the complete order information.
-
The Toast platform unique identifier (GUID) for the restaurant that made the update.
For more information about the new orders webhook, see Orders webhook.
|
Note |
|
If your integration currently polls the |
The Premodifier object of the menus API has been
updated with the following values:
-
posName: Specifies the button label name displayed for the premodifier in the Toast POS app. -
posButtonColorDark: Defines the button color for the premodifier in the Toast POS app when it is in dark mode. The color is specified in hexadecimal RGB notation. -
posButtonColorLight: Defines the button color for the premodifier in the Toast POS app when it is in light mode. The color is specified in hexadecimal RGB notation.
When an employee configures the POS button color for a
premodifier, they select a color pairing that consists of two colors,
one for light mode and one for dark mode.
posButtonColorLight contains the hexadecimal (hex) code for
the light mode color. posButtonColorDark contains the hex
code for the dark mode color.
The default color pairing is WHITE. In the
WHITE color pairing, posButtonColorLight is
#f7f7f7 and posButtonColorDark is
#1a1c23.
For a table that shows the color pairing names and the color hex codes for light and dark mode associated with each pairing, see POS button color hex codes for light and dark modes.
Like all changes to the menus API, these new values become available in the menu JSON after a restaurant has made a menus-related change and published the new menu, which regenerates the restaurant's menu data. For more information, see Menus API returns published data only.
This change applies to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
You can now download OpenAPI specification files for Toast platform APIs. OpenAPI is a standard for defining HTTP REST APIs. You can use OpenAPI specification files to make building and maintaining your Toast platform integration more efficient and reliable. For example, you can use tools such as OpenAPI Generator to generate API client code.
Download OpenAPI specification files for Toast APIs from the overview page for an API in the Toast API reference documentation. You open the overview page for an API by selecting the API name in the left navigation pane of the API reference documentation page. For example, you can download the authentication API OpenAPI specification from the authentication API overview page. The following image shows the download link for the authentication API.
The tender API will include an
HTTP Accept header field in the REST requests it
sends to your tender API integration on 2024-09-19. The value of the new
Accept header field will be application/json
for all tender API requests. The Accept header field
indicates that the tender API (the client) will accept response data
(for example, a
TenderTransactionResponse object) in JSON format.
This change has already been deployed in the sandbox environment.
You can now verify that your integration can accept requests that
include the HTTP header Accept field in the sandbox
environment to make sure that you do not experience disruption when the
change affects the production environment on 2024-09-19.
The gift cards integration API includes a new
relatedTransaction value in the
TransactionInformationRedeem object for gift card redeem
transactions. The relatedTransaction value is the Toast
platform unique identifier for a previous gift card transaction. Your
integration can use this identifier to confirm information about a
previous, related transaction such as PIN verification. For example, if
a restaurant employee adds a tip or gratuity to a transaction, the Toast
POS reverses the initial redemption and sends another redemption with
the new amount. This value provides the identifier of the initial
transaction. If the current transaction is not part of an adjustment
(for example, reversing a transaction) the
relatedTransaction value is null.
The Order object in the orders API has been updated
with a displayNumber value that provides a number for each
order in a single day. Typically, the displayNumber value
starts with 1 for the first order of the day and increments by 1 for
each additional order placed that same day. displayNumber
restarts each day. This pattern, however, is not guaranteed and you
should not rely on it when programming critical functions for your
integration.
While the displayNumber typically contains numeric
values, it is of type string.
For menus API V2, the Menu, MenuGroup,
MenuItem, ModifierGroup, and
ModifierOption objects have been updated with a
posName value. This value contains the button label name
displayed for the menu entity in the Toast POS app.
For menus API V3, the MenuGroup,
MenuItem, ModifierGroup, and
ModifierOption objects have been updated with the
posName value. The Menu object has not been
updated with the posName value in menus API V3.
posName contains an empty string if a
posName has not been defined for the menu entity and the
name value is used for the button label instead.
Like all changes to the menus API, these new values become available in the menu JSON after a restaurant has made a menus-related change and published the new menu, which initiates regeneration of the restaurant's menus data. For more information, see Menus API returns published data only.
This change applies to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
The behavior of the /stock/v1/inventory/update
endpoint of the stock API will change on 2024-08-26. The endpoint will
no longer return an error response if some menu items in the request are
not found in the restaurant location menu configuration. After the
behavior change, the endpoint will make updates to inventory information
for menu items in an update request, even if some menu items are not
found.
-
Currently, if any menu item identifier in an update request is invalid (the identifier does not match an active menu item configured for the restaurant location), the endpoint returns an HTTP 404 response listing each invalid identifier and does not take any action.
-
On 2024-08-26, if any menu item identifier in an update request is invalid, the endpoint will return an HTTP 200 response and will update the inventory information for each menu item in the request that matches existing menu items. The response body will include an array of the
MenuItemInventoryobjects in your request. TheitemGuidValidityvalue in each object will indicate whether the menu item was found and the inventory information updated or not found and no action was taken. If a menu item status isINVALID, your integration should update the list of menu items it associates with the restaurant location.
The following example shows the HTTP 200 response data that you
will receive from the /stock/v1/inventory/update endpoint
starting on 2024-08-26.
[
{
"guid": "e1e874d8-08fe-40dd-88b7-03686a2fbaf5",
"itemGuidValidity": "VALID",
"status": "QUANTITY",
"quantity": 70.0,
"multiLocationId": "200000008746447369",
"versionId": "e1e874d8-08fe-40dd-88b7-03686a2fbaf5"
},
{
"guid": "12ed7e46-58cf-42bf-817d-2c3980b82a20",
"itemGuidValidity": "INVALID",
"status": "QUANTITY",
"quantity": 80.0,
"multiLocationId": "200000008746446309",
"versionId": "12ed7e46-58cf-42bf-817d-2c3980b82a20"
}
]|
When a menu item identifier in the inventory update request
matches a menu item configured for the restaurant location, the
|
|
|
On 2024-08-26, the endpoint will return an HTTP 200 response
even when some menu item identifiers do not match menu items
configured for the restaurant location. In the response data, the
|
The /v1/restaurants/{restaurantGUID} endpoint of the
restaurants API has a new includeArchived query parameter.
You use the includeArchived parameter to control whether
the endpoint will return information about a Toast platform restaurant
that has been archived. The restaurants API General object
includes a new archived value that indicates whether a
restaurant is in the archived status.
Archiving a restaurant is functionally similar to deleting a
restaurant from the Toast platform. Archiving restaurants is rare, and
you do not need to actively check the status of restaurants to determine
whether they are archived. An example reason for archiving a restaurant
is that the restaurant was created in error. A Toast platform restaurant
location that becomes inactive because it goes out of business or no
longer uses the Toast platform is not archived. An inactive
state for a restaurant is more common than the archived state.
By default, the /v1/restaurants/{restaurantGUID}
endpoint returns an HTTP 404 Not Found response when you
request information about an archived restaurant. Now when you set the
includeArchived query parameter to true, the
endpoint will return information about the archived restaurant.
The PartnerAccessExternalRep object in the partners
API includes a new deleted value to indicate whether a
restaurant is actively using the Toast platform. You can use this value
to understand the status of Toast platform restaurant locations that are
connected to your integration. For example, if a restaurant is no longer
operating, or is no longer using the Toast platform, the restaurant
location is inactive and the deleted value is
true.
The Menu, MenuGroup,
MenuItem, ModifierGroup, and
Modifier objects of the menus API have been updated with
the following values:
-
posButtonColorDark: Specifies the button color for the menu entity on the Toast POS app when the app is running in dark mode. -
posButtonColorLight: Specifies the button color for the menu entity on the Toast POS app when the app is running in light mode.
When an employee configures a POS button's color, they select a
color pairing that consists of two colors, one for light mode and one
for dark mode. posButtonColorLight contains the HEX code
for the light mode color. posButtonColorDark contains the
HEX code for the dark mode color.
posButtonColorLight defaults to #f7f7f7
and posButtonColorDark defaults to #1a1c23,
the HEX codes when the WHITE color pairing is
chosen.
The following table shows the color pairing names and the color HEX codes for light and dark mode associated with each pairing.
Color pairing names and their light and dark HEX codes
|
Color pairing name |
Light HEX code |
Dark HEX code |
|---|---|---|
|
WHITE |
#f7f7f7 |
#1a1c23 |
|
TERRACOTTA_1 |
#ffe6e9 |
#7e635d |
|
TERRACOTTA_2 |
#efa49f |
#74504D |
|
TERRACOTTA_3 |
#f07166 |
#722e25 |
|
TERRACOTTA_4 |
#e45a4e |
#561408 |
|
ORANGE_1 |
#fbd9b6 |
#8f5f3d |
|
ORANGE_2 |
#f7be6e |
#7e4116 |
|
ORANGE_3 |
#f98c1f |
#803500 |
|
ORANGE_4 |
#e56f1a |
#682d03 |
|
YELLOW_1 |
#fbf5b6 |
#7e6b44 |
|
YELLOW_2 |
#fed850 |
#7b5f27 |
|
YELLOW_3 |
#e9b10c |
#7c5000 |
|
YELLOW_4 |
#c78605 |
#633d09 |
|
GRASS_1 |
#e8f7d4 |
#657552 |
|
GRASS_2 |
#afe26c |
#556e34 |
|
GRASS_3 |
#71b314 |
#37570a |
|
GRASS_4 |
#32a206 |
#113a00 |
|
SKY_1 |
#e3f0fb |
#637486 |
|
SKY_2 |
#9fc5f0 |
#4d6074 |
|
SKY_3 |
#77a5e4 |
#2a456b |
|
SKY_4 |
#558edd |
#213554 |
|
LAVENDER_1 |
#f1e3fd |
#78668a |
|
LAVENDER_2 |
#dab2f7 |
#5e4776 |
|
LAVENDER_3 |
#b26ee2 |
#402960 |
|
LAVENDER_4 |
#a270db |
#25174f |
|
GRAY_1 |
#d0d0d0 |
#6c6c6c |
|
GRAY_2 |
#c3c3c3 |
#5f5f5f |
|
GRAY_3 |
#b1b1b1 |
#474747 |
|
GRAY_4 |
#989898 |
#404040 |
Like all changes to the menus API, these new values become available in the menu JSON after a restaurant has made a menus-related change and published the new menu, which initiates regeneration of the restaurant's menus data. For more information, see Menus API returns published data only.
This change applies to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
When you authenticate your API client to use Toast APIs, you
provide a bearer-type authentication token in the
Authorization header field of your request. The string
Bearer is a required part of the header field format
Authorization: Bearer
.
[token]
Toast APIs will enforce the required bearer token
Authorization field format, including the string
Bearer, on 2024-08-26. If your integration does not already
include the string Bearer in the Authorization
header field for all Toast API requests, you must implement
authentication in a way that includes that string before
2024-08-26.
For more information about Toast API authentication, see Using an authentication token.
The TLS certificate provider for Toast APIs will change from Let's Encrypt™ to Google™. The Let's Encrypt root certificate is changing in September 2024 to a newer trust root that is not installed in older devices and systems. By switching from Let's Encrypt to Google, the Toast platform remains on a trust chain that is installed on all systems in current use on the internet.
This change has already been made to the Toast sandbox environment and will be made to the Toast production environment on or after 2024-05-20. Make test API requests in the sandbox environment and confirm that your integration can correctly handle the new certificate provider.
For more information, see:
The orders API customer object now includes the
optional phoneCountryCode field. The
phoneCountryCode field specifies the international phone
number country code for a guest.
For more information about the phoneCountryCode
field, and the orders API customer object, see the orders
API customer object.
The orders API DeliveryInfo object now includes an
administrativeArea value. The
administrativeArea value indicates the geographic or
government division, larger than a city/town, for the delivery
destination. For example, the name of a province, county, or region
might be the administrativeArea value for a delivery
address.
The new administrativeArea value is optional, not all
delivery addresses include a regional area name other than a city. If
you include the state value, you would
not include an administrativeArea.
Use the following rules to choose either the new
administrativeArea value or the existing state
value for a delivery address when you create orders in the orders
API.
-
If the country for the delivery address is the United States (U.S.) or Canada, use the state value for the U.S. state or Canadian province. Omit the
administrativeAreavalue. -
If the country for the delivery address is not the U.S. or Canada (anywhere else in the world), use the
administrativeAreavalue. Include the stringXXin the requiredstatevalue.
The packaging configuration API is now available. The packaging configuration API lets you retrieve a restaurant's packaging preferences and add them to an order using the orders API. Packaging preferences are specifications that a guest can add to their order to indicate whether they want to include items like napkins, utensils, and condiments.
To retrieve packaging preferences with the packaging configuration API, restaurants must have packaging preferences configured. Restaurant leaders can configure packaging preferences in Toast Web at Takeout & delivery > Packaging preferences.
For more information about the packaging configuration API and packaging preferences, see Packaging preferences and Packaging configuration API.
The tender API has been updated in the following ways:
-
The
TENDER_GRATUITYtransaction now includes thecheckobject which describes a transaction's complete order details.The TENDER_GRATUITYtransaction payload is now larger as a result of adding thecheckobject. -
The
TENDER_GRATUITYtransaction now includes theorderGuidfield. TheorderGuidis the transaction's unique Toast identifier. -
The
TENDER_REVERSEtransaction now includes the refunded order'sorderGuid.
For more information about the tender API, see Tender provider integrations overview.
Menu visibility settings that control whether menus are available in specific ordering integrations are now available at all Toast platform restaurant locations.
-
If your ordering integration uses menus API v3 to get menu information, you can expect that all Toast restaurants can now choose which menus appear in your menus API v3 response.
-
If your integration uses menus API v2, you need to transition to using menus API v3. You can work with Toast restaurants to make sure that their menu visibility settings are configured to include the correct menu information in your menus API v3 response.
Toast restaurants can choose which ordering partners a menu is visible to. They manage visibility settings from the menu builder configuration controls in Toast Web. For more information about configuring visibility settings and the menus API, see Specifying ordering channel visibility, Restricting menu visibility to specific online ordering partners, and Comparing menus API V2 and V3.
When a restaurant turns On your integration in the Online ordering partners channel visibility option for a menu, that menu is in the response data you get from the menus API v3. If the restaurant turns your integration Off in the channel visibility option, the menu is not included in the menus API v3 response.
The following image shows the Online ordering partners channel visibility options for menu visibility.
If your integration uses menus API v2, you need to transition to using menus API v3. The way that your integration filters the menus API v2 response to show only the menu information that a restaurant intends to offer in your integration makes a difference in the way that you can transition to using menus API v3:
-
If your integration only filters menus in the menus API v2 by
ORDERING_PARTNERSvisibility (the Online ordering partners visibility option in Toast Web), you can safely transition to the v3 endpoint without losing access to menus. -
If your integration allows restaurants to use visibility settings for menus API v2 other than
ORDERING_PARTNERS(the Online ordering partners visibility option in Toast Web), the restaurant will need to update their menu visibility settings to be compatible with menus API v3.
For example, if your integration is still using menus API v2 and you integrate with a restaurant that indicates that a menu should be available in your integration by setting Kiosk, Toast Order and Pay visibility, these menus would be visible to you in the menus v2 response but not in the menus v3 response. To make the visibility setting compatible with menus API v3, the restaurant can select Online order partners and make sure that your integration is set to On in addition to Kiosk, Toast Order and Pay.
Make sure that your ordering integration uses menus API v3 by 2024-08-01.
The Toast gift card integration now includes new enumeration values:
-
The
identifierSourcevalue of theTransactionInformationobject now includes aKEYED_ONLINEvalue. TheKEYED_ONLINEvalue indicates that a guest entered the identifier of a gift card account while using a Toast Online Ordering website. -
The source value of the
VerificationCodeobject now includes aVERIFIEDvalue. TheVERIFIEDvalue indicates that the Toast platform previously verified the gift card account verification code for this transaction. Typically, your integration receives a request with thesourceset toVERIFIEDfor subsequent transactions on an order, after the guest's account is already verified. If your integration receives a request with the verification code source set toVERIFIED, do not verify the guest's code again. For more information about verification codes, see Handle verification codes.
|
Note |
|
If your gift card program has not opted-in to these features, your integration will not receive the new enumeration values. Contact developer support to inquire about adding Verification Code (PIN) support to your Toast API implementation scope. |
Toast Online Ordering sites now support integrated loyalty programs. Your loyalty program integration will now receive loyalty integration API requests from Toast restaurant guests who are using Toast Online Ordering site functionality. For more information about loyalty program integrations and Toast Online Ordering sites, see this Toast Central article.
The ModifierOption object of the menus API has been
updated to include a kitchenName value. This value
specifies the name that appears on kitchen tickets for the modifier. The
kitchenName value is null if a kitchen name is not
configured for the modifier.
The ModifierOption object of the menus API has also
been updated to include a prepStations value. This value
contains an array of GUIDs for the prep stations that have been assigned
to this modifier option.
If a modifier's item reference has prep stations assigned to it, then the modifier uses those prep stations. If the modifier's item reference does not have prep stations assigned to it, then the modifier inherits the prep stations of the menu item, menu group, or modifier (in the case of nested modifiers) it is modifying.
The array is empty if no prep stations have been assigned to the modifier.
Like all changes to the menus API, this new value will become available in the menu JSON after a restaurant has made a menus-related change and published the new menu, which initiates regeneration of the restaurant's menus data. For more information, see Menus API returns published data only.
This change has been made to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
On 2024-01-22, the selectionType value in the
Selection object of the orders API will include two
new enumerated values. The following values indicate that the selection
is a Toast gift card purchase or a transaction to add value to a Toast
gift card.
-
TOAST_CARD_SELL -
TOAST_CARD_RELOAD
Beginning on 2023-01-22, the order information that you get from
the orders API might contain these new selectionType
values. Make sure your integration will handle the new values without
interruption.
The labor API Employee object now includes an
optional phoneNumberCountryCode value to hold the
international country code of an employee's telephone number. You can
set the country code for an employee's telephone number when you create
an employee record.
You can use Toast platform reports and Toast product information
resources to understand how different repayment amounts make up the
total mcaRepaymentAmount value in an orders API
order.
The mcaRepaymentAmount value in
the Payment object for an order indicates the total
amount withheld as payments or repayments that apply to your business.
For example, the mcaRepaymentAmount might include:
-
Toast Capital payments
-
Marketplace facilitator tax
-
Toast Delivery Services costs
-
Instant deposits
You can use the following resources to understand the different
repayment amounts that are included in the orders API
mcaRepaymentAmount value.
The AppliedServiceCharge object in the orders API
includes information about credit card payment surcharges and also
service charges in two new values:
-
serviceChargeCategory- the type of the service charge or surcharge. Values are:SERVICE_CHARGE- the default value. Used for service charges that are not in one of the other categories.CREDIT_CARD_SURCHARGE- a fee assessed only on payment transactions that use a credit card.FUNDRAISING_CAMPAIGN- a service charge applied for a charity or similar fundraising effort. -
paymentGuid- the unique identifier of the credit card payment that a credit card surcharge service charge is applied to. You can use this identifier to match a service charge to aPaymentobject on aCheck. ThepaymentGuidvalue isnullfor any service charge that is not a credit card surcharge.
The Toast platform functionality that sets this service charge and surcharge information in the orders API is in limited release. Initially, API orders only include service charge and surcharge information for orders created by the Toast POS app.
Orders created by the Toast Takeout ordering app and the Toast
local ordering
website now remit tax payments for restaurants as marketplace
facilitators. The facilitatorCollectAndRemitTax value in
the AppliedTaxRate object for order items indicates whether
the tax payment was remitted by a marketplace facilitator on behalf of
the restaurant. If your integration uses detailed tax payment
information, this change might affect the way you handle orders API
response data for some restaurant locations.
The Toast platform change that handles tax payments as marketplace facilitator tax payments for Toast Takeout and Toast local orders is in limited release. Not all Toast platform restaurants are configured to use Toast Takeout and the Toast local ordering site as marketplace facilitators.
For more information about getting marketplace facilitator tax information from the orders API, see Marketplace facilitator tax information.
The menuItem object of the menus API has been updated
to include a kitchenName value. This value specifies the
name that appears on kitchen tickets for the menu item. The
kitchenName value is null if a kitchen name has not been
configured for the menu item.
Like all changes to the menus API, this new value will become available in the menu JSON after a restaurant has made a menus-related change and published the new menu, which initiates regeneration of the restaurant's menus data. For more information, see Menus API returns published data only.
This change has been made to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
You can now set the guestIdentifier value in the
PaymentRequestMetadata object of the credit cards API to
any identifying string for a guest. For example, you can set the
guestIdentifier value to an email address or phone number.
Previously, the guestIdentifier value required a UUID
(Universal Unique Identifier) identifier string. You include an
identifying string for guests to improve fraud evaluation for credit
card payments. For more information about using the
guestIdentifier value, see Using guestIdentifier values.
The General object in the restaurants API now
includes a currencyCode value. The
currencyCode value is the ISO-4217 currency code of the
monetary currency a restaurant accepts for purchases. For example, if a
restaurant accepts United States dollars, the currencyCode
value is USD.
The disabled value in the labor API
Employee object is deprecated and will be removed in the
Toast production API environment on 2023-11-27. There is no replacement
for the disabled value. This functionality is no longer
used by the Toast platform.
The orders API now returns a daily excess food order for restaurants that use the Toast platform's waste tracking feature. An excess food order, also referred to as a waste order, is a special type of order created in the Toast platform to track excess food in a restaurant. Like guest orders, excess food orders may contain menu items, modifiers, or both.
The Toast platform creates one excess food order per day at each restaurant using the waste tracking feature. The Toast platform creates the daily excess food order the first time a restaurant employee uses the waste tracking feature to identify excess food. If restaurant employees identify additional excess food over the course of the business day, that excess food is added to the daily excess food order. If no excess food is identified on a given day, no excess food order is created for that day.
The orders API indicates that an order is an excess food order
using the excessFood value on the Order
object. Excess food orders are structurally the same as standard guest
orders. However, certain behavior is applied to these orders
automatically by the waste tracking feature:
-
The
excessFoodfield is set totrue. -
Exactly one check is created on each excess food order.
-
Each selection on the check is discounted to $0 using an item-level 100% discount. This discount is created automatically by the Toast platform and has the name
Waste. -
If the restaurant has configured waste reasons and the employee identifying the waste selects one of those reasons when tracking the item in the POS, that reason is applied to the discounted selection. Note that waste reasons are not returned in orders API responses.
Because all selections on the check are discounted, the
price value on each selection and the amount
value of the check is always $0. The preDiscountPrice value
on each selection, however, reflects the retail value of each selection.
If you use the preDiscountPrice field in order to report on
gross sales, you might want to exclude excess food orders from this
calculation.
The waste tracking feature is not available to Toast restaurants yet, so you won't see excess food orders right away. Toast support is providing this information ahead of time so you can prepare your integration if it performs reporting activities for Toast restaurants. The waste tracking feature will be available to Toast restaurants in approximately 90 days.
You can use the new includeArchived query parameter
for the labor API /timeEntries endpoint to get information
about deleted (archived) time entries. The includeArchived
parameter controls whether the endpoint response includes deleted time
entries, when using the startDate and endDate
parameters.
|
Important |
|
The |
-
Querying by a date and time range using the
startDateandendDateparameters of the/timeEntriesendpoint returns deleted time entries if you include theincludeArchivedparameter and set it totrue. TheincludeArchivedparameter is optional and its default value isfalse. -
Querying by modified date range using the the
modifiedStartDateandmodifiedEndDateparameters of the/timeEntriesendpoint always returns deleted time entries. -
Querying by business date using the
businessDateparameter of the/timeEntriesendpoint never returns deleted time entries.
You can identify deleted time entries in the response data for the
/timeEntries endpoint by checking the deleted
and deletedDate values of a
TimeEntry object. If the deleted value
is true and the deletedDate is not
null, the time entry is deleted. The following example
shows a TimeEntry object for a deleted time entry.
The Location object in the restaurants API includes
two new values:
-
administrativeArea - The name of the geographical division (for example, state, province, or county) that the restaurant is located in.
-
phoneCountryCode- A numeric code corresponding to one or more countries, used as a telephone number prefix when making international telephone calls.
The stateCode value in the Location
object is now deprecated. Use the administrativeArea value
to get the state or province of a restaurant, instead of the
stateCode value.
The API
reference documentation for Toast APIs now includes information
about the authentication method and authorization scopes required for
each API endpoint. For example, the
API reference documentation for the /orders/{guid} endpoint of
the orders API indicates that the endpoint requires the
orders:read scope.
Previously, Toast support announced the availability of V3 of the
menus API for online ordering integrations. With menus API V3,
the /menus endpoint only returns the menu entities that are
visible to the online ordering integration that is making a
request.
The corresponding UI that allows restaurants to configure which menus should be visible to each online ordering integration has been released to the sandbox environment. For more information on using these settings, see Restricting menu visibility to specific online ordering partners.
The partner-specific settings are not yet available for restaurants to use in the production environment. Toast support is making these settings available to you in the sandbox environment so you can test your integrations with them.
The ModifierOption object of the menus API has been
updated to include a prepTime value. This value specifies
the amount of time, in seconds, that it takes to prepare the modifier
option. The prepTime value is null if a prep time has not
been configured for the modifier option.
Like all changes to the menus API, this new value will become available in the menu JSON after a restaurant has made a menus-related change and published the new menu, which initiates regeneration of the restaurant's menus data. For more information, see Menus API returns published data only.
This change has been made to both V2 and V3 of the menus API.
|
Note |
|
For information on the differences between V2 and V3 of the menus API, see Comparing menus API V2 and V3. |
The orders
API Order object now contains a
createdInTestMode value. The Boolean
createdInTestMode value indicates whether an order was
created while a restaurant location was configured to allow employees to
test and train with Toast POS system functionality without affecting
real production data. For more information about test mode, see this
Toast Central article.
The maximum pageSize query parameter value for
response data from the
partners API connectedRestaurants endpoint is now
200. Previously the maximum page size was 100.
You use the pageSize query parameter to control the number
of connected restaurants the endpoint returns in a single, paginated
response body.
The multiLocationId value has been added to the
PreModifer and PreModifierGroup objects in
both V2 and V3 of the menus API.
A multiLocationId is used to identify and consolidate
menu entities that are versions of each other.
For more information on multilocation IDs, see Toast identifiers. For more information on premodifiers, see Applying modifiers and pre-modifiers.
The source value of the orders
API Order object will include a new order source
value on 2023-02-13. The following new order source value indicates that
an order originated from the Toast Tables table waitlist
function.
-
Toast Tables
The source value of the orders
API Order object will include two new order source
values on 2022-12-05. The following new order source values indicate
that an order originated from Toast platform catering and event
functionality.
-
Catering -
Catering Online Ordering
The loyalty integration
API Customer object and the customer
value in the Check object have been deprecated and will be
removed from the API on 2022-11-01. The information about restaurant
guests in the Customer object is no longer used by the
loyalty integration API.
A new version of the menus API, version 3 (V3), is now available.
|
Important |
|
Ordering partner integrations must switch to using V3 of the menus API by 2023-01-13. Other partner integration types should continue to use V2 until further notice. |
With menus API V3, the /menus endpoint has been
re-factored for ordering partners so that it returns only those entities
that are visible to the online ordering partner making the request. This
eliminates the need for an ordering partner integration to filter the
menu data it receives from the /menus endpoint. The Toast
platform uses the partner token included with the request to determine
which ordering partner has made the request and filters the menu data
accordingly.
To access the /V3/menus endpoint, an ordering
partner's API account must have the menus.channel:read
scope. Toast support will assign the menus.channel:read
scope to ordering partners. Only ordering partners will receive this
scope.
Note that currently menus API V3 only supports ordering partners.
Additional re-factoring will happen in the future to support other types
of partner integrations, including integrations that continue to need
the aggregated view of all of a restaurant's menu entities that menus
API V2 provides. Other integration partners should continue to use menus
API V2 until further notice. Access to menus API V2 will continue to be
gated by the menus:read scope.
Ordering partners, see Switching to menus API V3 for more information on switching to menus API V3.
All partners, see Comparing menus API V2 and V3 for more information on the differences between V2 and V3.
To switch to using the V3 version of the /menus
endpoint, your integration must replace V2 with
V3 in the URL it uses to call the endpoint. It must also
remove any logic that filters out menu entities whose
visibility array did not include the
ORDERING_PARTNERS value. This logic is no longer
necessary because the /V3/menus endpoint filters the menu
entities it returns based on the ordering partner integration making
the request.
Toast support is making V3 of the menus API available to ordering partners before the corresponding UI settings are available in Toast Web that allow restaurants to define the specific ordering partners a menu entity is visible to. This staggered release allows ordering partners to prepare their integrations for the new ordering partner-specific visibility settings before restaurants start using them.
That said, menus API V3 still provides immediate value to online ordering partners because it filters what it returns to include only menu entities that should be visible to any online ordering partner (that is, menu entities whose Online ordering partners setting in the menu builder, or Online orders: Ordering partners setting in the classic menu details pages, is enabled). Also, the updates required to make your integration compatible with menus API V3 now will continue to work when the more granular ordering channel visibility settings are introduced, meaning you will not have to make additional code changes when those settings become available.
To test your integration now, mark a menu entity as visible to Online ordering partners (in the menu builder) or Online orders: Ordering partners (in the classic menu details pages). Menu entities with these settings enabled will be included in the menu JSON your integration receives from menus API V3. Menu entities with these settings disabled will be filtered out of the menu JSON your integration receives.
Toast will make the more granular visibility settings available to online ordering partners in the sandbox environment in November, 2022, allowing you to do final testing on your re-factored integration with the new settings before the changes go live in the Production environment.
Previously, if you attempted to log in to an environment with credentials that belong to a different environment, you would get a 403 error message.
Now, a 400 error message is returned indicating that the domain
tenant and tenant associated with the client_id or
connection_id are not the same.
The Toast API reference documentation now includes detailed information about the values in data objects in a new Data definitions section for each API. You can browse through the data objects used by each Toast API and easily find information about the objects you are working with.
For example, the Data definitions sections include the following reference documentation for data objects:
In the reference documentation entries for data objects, you can expand the entries for values that hold array and object data types by clicking the caret icon. For example, the entry shown in the following image is expanded to show information about a value that holds an array of objects.
The labor API Employee object now includes a
chosenName value. The chosenName value is an
optional, preferred name that employees set for themselves. The chosen
name is used instead of the employee's first name in some Toast platform
functionality. For example, the employee's chosen name is shown
in:
-
Kitchen display system (KDS) tickets
-
Printed kitchen tickets
-
The Toast POS app order activity screen
-
Payment receipts
Employees set the chosen name in the Personal Info section of the Employees configuration page of Toast Web.
You can set the chosen name when you create an employee using a
POST request and you can update an employee's
chosen name using a PATCH request.
The following example shows an Employee object with
the new chosenName value.
{
"guid": "4d7651d2-0ea8-4496-97fd-558cfd3514f1",
"entityType": "RestaurantUser",
"externalId": "MYORG:20220804232724",
"v2EmployeeGuid": "a59b2b0b-f9f2-44ed-be49-6d1dac49a419",
"lastName": "Gauthier",
"wageOverrides": [],
"firstName": "Josephine",
"chosenName": "Jo",
"createdDate": "2022-08-05T03:27:25.799+0000",
"deleted": false,
"deletedDate": null,
"jobReferences": [],
"modifiedDate": "2022-08-05T03:30:27.609+0000",
"disabled": false,
"externalEmployeeId": "",
"email": "jgauthier@example.com"
}
The setting for returning information about whether a menu item or modifier contains alcohol and would benefit from additional handling is available for restaurants to use in Toast Web. For more information about the underlying menus API for this setting, see Determining if a menu item or modifier contains alcohol.
The orders API has been updated to return an HTTP status code 400 response when a client integration attempts to:
-
Post an order with more than 1,000 top-level selections.
-
Post an item to an order that causes the order to have more than 1,000 top-level selections. For example, if an order has 995 top-level selections and your integration posts six items to that order in a single request, that request will be rejected.
A top-level selection is defined as a selection that is not the child of another selection in the order.
To avoid exceeding the 1,000 top-level selection limit, Toast support encourages the grouping of identical items together, so:
-
1 soda
-
1 lemonade
-
1 energy drink
-
1 soda
-
1 lemonade
-
1 soda
Can be combined into:
-
3 sodas
-
2 lemonades
-
1 energy drink
This reduces the number of top-level selections in the request from six to three while providing the same order data.
Previously, if the Amazon S3 service was unavailable, the
GET /menus endpoint of the menus API would return a 404
HTTP error code with the message:
No published data found for restaurant GUID: [restaurant-guid]. Make sure restaurant GUID is correct and that data has been published.
This message was misleading because it provided the wrong cause and resolution for the problem.
Now, when the Amazon S3 service is unavailable, the GET
/menus endpoint returns a 503 HTTP error code with the following
message:
Unable to retrieve menus for restaurant due to a service outage.
The menus API has been updated to return information about whether a menu item or modifier contains alcohol and may require, or benefit from, additional handling. Examples for why a restaurant would identify a menu item or modifier as containing alcohol include the following:
-
A menu item or modifier that contains alcohol may require delivery drivers to request identification before giving the items to a guest.
-
Under some local laws and regulations, guests may not accrue discount or loyalty points on purchases of items that contain alcohol.
Note that not all menu items or modifiers that contain alcohol require, or benefit from, additional handling. For example, a drink containing rum would require an ID check before it is delivered, while a piece of rum cake would not. The alcohol identification feature is designed for menu items and modifiers that need some type of additional handling after they are ordered, such as an ID check or the prevention of loyalty point accruals.
To support the identification of items that contain alcohol, the
MenuItem and ModifierOption objects of the
menus API have a new contentAdvisories value. The
following code sample shows the contentAdvisories value
on a MenuItem object:
"menuItems": [
{
"name": "Rum Punch",
"guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
"multiLocationId": "100000000100009153",
[contents omitted]
"contentAdvisories": {
"alcohol": {
"containsAlcohol": "YES"
}
}
}
]The contentAdvisories value holds a single object
of type ContentAdvisories. The purpose of the
ContentAdvisories object is to encapsulate important
information about a menu item or modifier's contents. Currently, this
object only has information about whether a menu item or modifier
contains alcohol. In the future, it could be used for other content
information, such as whether the menu item or modifier contains common
allergens or is compatible with various dietary restrictions.
The ContentAdvisories object has an
alcohol value that holds a single object of type
Alcohol. The Alcohol object encapsulates
information related to the alcoholic aspects of the menu item or
modifier. Currently, the Alcohol object has one value,
containsAlcohol. The containsAlcohol value
is a string and may be one of the following:
-
YES- The menu item or modifier contains alcohol. -
NO- The menu item or modifier does not contain alcohol.
The containsAlcohol value may also be
null. A null value indicates that the
corresponding user interface option in Toast Web has not been set for
this menu item or modifier.
The following code samples show the different ways the
containsAlcohol value may appear in the menus response
data.
A MenuItem object for an item that contains
alcohol:
"menuItems": [
{
"name": "Rum Punch",
"guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
"multiLocationId": "100000000100003519",
[contents omitted]
"contentAdvisories": {
"alcohol": {
"containsAlcohol": "YES"
}
}
}
]A MenuItem object for an item that does not
contain alcohol:
"menuItems": [
{
"name": "Rum Cake",
"guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
"multiLocationId": "100000000100009153",
[contents omitted]
"contentAdvisories": {
"alcohol": {
"containsAlcohol": "NO"
}
}
}
]A MenuItem object for an item whose
containsAlcohol option has not been set in Toast
Web:
"menuItems": [
{
"name": "Grilled Cheese",
"guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
"multiLocationId": "100000000100009153",
[contents omitted]
"contentAdvisories": {
"alcohol": {
"containsAlcohol": null
}
}
}
]A ModifierOption object for a modifier that
contains alcohol:
"modifierOptionReferences": {
"1": {
"referenceId": 1,
"name": "Rum Shot",
"guid": "429f9045-74a1-81bc-4c48-86ce51c2f6ae",
"multiLocationId": "100000000100008684",
[contents omitted]
"contentAdvisories": {
"alcohol": {
"containsAlcohol": "YES"
}
}
}
}A ModifierOption object for a modifier that does
not contain alcohol:
"modifierOptionReferences": {
"2": {
"referenceId": 2,
"name": "Lettuce",
"guid": "429f9045-74a1-81bc-4c48-86ce51c2f6ae",
"multiLocationId": "100000000100008684",
[contents omitted]
"contentAdvisories": {
"alcohol": {
"containsAlcohol": "NO"
}
}
}
}A ModifierOption object for a modifier that has
not had its containsAlcohol option set in Toast
Web:
"modifierOptionReferences": {
"3": {
"referenceId": 3,
"name": "Cheese",
"guid": "429f9045-74a1-81bc-4c48-86ce51c2f6ae",
"multiLocationId": "100000000100008684",
[contents omitted]
"contentAdvisories": {
"alcohol": {
"containsAlcohol": null
}
}
}
}The ModifierOption value has been included in the
menus API payload now, before the corresponding user interface option
has been added to Toast Web, to allow you to prepare your integration
to consume the new value before restaurants start using it in their
configurations. This means that, until the UI option is available, the
containsAlcohol value for menu items and modifiers will
always be null. A subsequent release note will inform you when the UI
option is available in Toast Web and restaurants may begin using it to
identify menu items and modifiers that contain alcohol.
When it becomes available, the UI option to indicate that a modifier contains alcohol will exist on the details page for the modifier’s underlying menu item reference, not on the details page for the modifier itself.
Several improvements and updates have been made to the stock API and the stock webhook.
The stock API and stock webhook payloads include two additional identifiers:
-
multiLocationIdis a consistent identifier that applies to all versions of a menu item that is shared across locations. Toast support recommends using themultiLocationIdinstead of a menu itemguid, when submitting requests to Toast APIs. For more information, see Toast identifiers. -
versionIdhas been added for future use.
When making a request to the /inventory/search
endpoint, the message body you submit can now contain either
multi-location IDs or GUIDs to identify the menu items you want to
retrieve inventory information for. For more information, see Getting stock information using the stock API.
The stock API has a new /inventory/update endpoint
that you can use to update inventory information for menu items or
modifiers. You can set one of the following status values for a menu
item or modifier:
-
IN_STOCK -
OUT_OF_STOCK -
QUANTITY- If you set an item status toQUANTITY, you must also provide aquantityvalue with double data type. For example, you can set thequantityto0.5,7.0, or10.75.
For more information, see Updating stock.
The new restaurant availability API retrieves information about a
restaurant's availability to accept online orders. The restaurant
availability API is a fallback API service for the
restaurant_availability webhook, which is the most
efficient way for you to get availability information about
restaurants.
The restaurant availability API returns a status
value that can be either ONLINE or OFFLINE.
You can use information about whether a restaurant is available for
online ordering to avoid sending guest orders that will not be fulfilled
or that will overwhelm the restaurant when it becomes available
again.
For more information, see Getting a restaurant's online ordering availability.
The Postman™ collection of API requests that you can use to test Toast API functionality has been updated. The updated collection includes requests for all current APIs, a pre-request script that auto-requests a new authentication token when the old one expires, and example responses for all APIs. For more information, see Example API requests.
Toast APIs now return an HTTP 400 (bad request) response if you
submit a request with a Toast-Restaurant-External-ID header
parameter value that is not a valid GUID. Previously, Toast APIs
returned an HTTP 500 response in this situation.
The Toast platform now retries sending webhook messages after a receiving endpoint returns an HTTP 429 (too many requests) response. Previously, the Toast platform did not attempt to resend a webhook messages after receiving an HTTP 429 response. For information about the way the Toast platform retries sending webhook messages, see Retry support.
A new Order object summary section has been added to
the Toast API Developer
Guide. The new section contains an overview diagram of the
Order object. It also provides explanations of related
fields in the object, including identifiers, status values, dates and
times, and order amounts. The order amount information uses an example
order to demonstrate the relationships among the amount values.
A new enumerated value has been added to the source
value of the orders API Order object. The new value is
Toast Pickup App which represents the Toast Takeout app.
Additionally, the OPT value has been corrected to
Order-and-Pay-at-Table.
The following list describes the new rules for pausing and stopping webhook subscriptions that are experiencing errors:
-
If a webhook endpoint returns fifty or more errors during a five-minute interval, the subscription is paused for one minute.
-
If a webhook endpoint is paused nine times during a ten-minute interval, then the subscription is stopped and you must contact Toast support to restart it.
Previously, the Toast platform followed these rules for pausing and stopping webhook subscriptions that were experiencing errors:
-
If a webhook endpoint returned three or more errors during a one-minute interval, the subscription is paused for one minute.
-
If a webhook endpoint is paused three times during a three-minute-and-20-second interval, then the subscription is stopped and you must contact Toast support to restart it.
For more information, see Back-off support.
Loyalty API requests for restaurants using an upcoming release of
the Toast POS app will always include a null
externalId value for menu entities. This change will take
effect when a restaurant starts using version 2.55 of the Toast POS app.
The date that a restaurant begins using version 2.55 depends on the
upgrade policy of the restaurant location. Your integration might
receive loyalty API requests with null externalId values on
2022-02-23.
Currently, the externalId value for menu entities in
a loyalty API request includes a numeric string that is not an external
identifier for the menu entity.
The source value enumeration in the orders API
Order object will include a new Invoice value
on 2022-02-07. The value Invoice indicates that the order
was created by upcoming Toast platform functionality that is in limited
release.
The menus API includes a new multiLocationId identifier for menu
entities. The multiLocationId identifier is equivalent
to the masterId identifier and is used to
identify and consolidate menu entities that are versions of each other.
The name of the new multiLocationId value is more
consistent with Toast API terminology standards. The
masterId value is now deprecated and will remain in the
menus API for backwards compatibility. If your integration uses
masterId, you should update the value name to use
multiLocationId. For more information, see Understanding GUIDs, referenceIds, and multiLocationIds.
You can now designate an email address for Toast webhook start and stop notification messages. These messages indicate that a webhook subscription has paused, stopped, or restarted.
Previously, the Toast platform sent all start and stop notification messages to your support email address. In some cases, teams who handle technical support email messages are different from the teams who would can update your webhook configuration and resolve webhook processing errors. For example, a software development team might handle webhook configuration and processing.
You now designate both a support email address and a dedicated start and stop message email address for a new webhook subscription. For existing webhook subscriptions, the Toast integrations team will configure the new start and stop message email address that you want to use.
You can use this web form to enter the start and stop message email address. Only use this form if you already use a webhook subscription. You cannot use this form to request a new webhook subscription.
The email addresses you designate for your webhook subscriptions can be different for each subscription you use. For example, you can designate different email addresses for a menus webhook subscription and a stock webhook subscription.
For more information about webhook start and stop email messages, see Back-off support.
The Toast platform now limits gift card add value transactions to $500. If you use the Toast gift card integration, your integration will no longer receive add value transactions for amounts over that limit. This new transaction value limit does not make any functional or technical changes to the Toast gift card API.
The Toast loyalty API will change the behavior of the
loyaltyIdentifier value in the
TransactionInformationReverse object for reversal
transaction requests on 2022-03-14. The loyaltyIdentifier
value for a reversal transaction will always match
the loyaltyIdentifier of the transaction that is being
reversed.
By 2022-03-14, your loyalty API integration must handle a
null loyaltyIdentifier for a
LOYALTY_REVERSE transaction. If you receive a
LOYALTY_REVERSE transaction with a null
loyaltyIdentifier, your integration must return an HTTP 200
response code and the transactionStatus ACCEPT
if the transaction is structured correctly.
The reversal transaction account identifier will match the account identifier of the original transaction:
-
When the loyalty account identifier of the original transaction is
null.In this situation, the loyalty account identifier of the reversal transaction will be
null. This is a change from current API behavior. -
When the loyalty account identifier value of the original transaction includes the account identifier string.
In this situation, the loyalty account identifier of the reversal transaction will also include the identifier value.
Currently, the Toast loyalty API sends a non-null
loyaltyIdentifier value for some reversal transactions that
apply to a transaction that contained a null
loyaltyIdentifier value.
The following procedure describes one situation that can result in
a non-null loyaltyIdentifier value in a
reversal transaction for a transaction that included a null
loyaltyIdentifier value.
-
A restaurant guest does not provide loyalty account information when paying for a check. The Toast loyalty API sends your loyalty service an accrual transaction request. The
loyaltyIdentifiervalue in theTransactionInformationCheckobject isnull. The Toast loyalty API sends an accrual request transaction for all check payments, even when the guest has not presented loyalty account information.When your service receives a transaction request with no loyalty account identifier, your integration might discard the transaction information. The action your service takes with this request depends on the design of your integration.
-
After completing the payment transaction, the guest presents loyalty account information and wants to apply the check payment to the loyalty program.
The Toast loyalty API sends your service a reversal transaction for the check payment. The transaction identifier of the reversal request matches the transaction identifier of the accrual request.
Currently, the Toast loyalty API includes the loyalty account identifier that the guest provided in the
loyaltyIdentifiervalue of theTransactionInformationReverseobject for the reversal request. This behavior will change on 2022-03-14 and theloyaltyIdentifieron this transaction will benull.-
If your loyalty program service did not store the original transaction (which did not include a loyalty program account identifier), the correct method for handling the reversal request for that transaction might not be clear. The way that your service handles this situation depends on the design of your integration.
On 2022-03-14, the Toast loyalty API will include a
null loyaltyIdentifier value for the reversal
request described in Step 3.
By 2022-03-14, your loyalty API integration must handle a
null loyaltyIdentifier for a
LOYALTY_REVERSE transaction. If the you receive a
LOYALTY_REVERSE transaction with a null
loyaltyIdentifier, your integration must return an HTTP 200
response code and the transactionStatus ACCEPT
if the transaction is structured correctly.
The MenuItem object returned by the menus API now has
a taxInclusion value that you can use to determine if the
taxes on a menu item are included in the item price.
|
Important |
|
The |
The taxInclusion value is a string that represents
the tax inclusion setting for the menu item. Values include:
-
TAX_INCLUDED: The menu item's price includes taxes. You should not display additional tax (added to the menu item price) in an ordering interface. -
TAX_NOT_INCLUDED: The menu item's price does not include taxes. You should display the tax amount in addition to the menu item price in your ordering interface. -
SMART_TAX: The menu item is using smart tax, a feature that allows restaurant employees to configure menu item prices to include or not include taxes, depending on the section of the restaurant that the item is ordered in (for example, the bar or the dining room). For example, a restaurant might have service areas in which a guest can order an item at either the bar or in the main dining room. To prevent bartenders from having to handle coins, which can slow down service, and to make tipping easier, the restaurant wants the price of the item to be a whole number that includes tax when it is ordered at the bar. In the main dining room, where speed of service is less of a concern, the restaurant does not want the item's price to include tax, so that it does not lose the extra revenue.
Typically, the smart tax setting is used for on-site ordering
where the efficiency of money handling is a priority and is less
frequently used for online ordering integrations. If the
taxInclusion value for a menu item is set to
SMART_TAX, your ordering integration should treat the menu
item as if tax is not included. For more information on the smart tax
feature, see Smart tax.
|
Note |
|
The tax inclusion setting for a menu item is inherited by any modifiers that are applied to that menu item. For more information, see Tax functionality interaction. |
The new order management configuration API provides information about the online ordering schedule for a restaurant. The ordering schedule indicates the hours when a guest can place an order for takeout or delivery. For more information, see the order management configuration API reference documentation.
It is possible that a restaurant will change its configuration
while your integration client is in the process of retrieving paginated
data for that restaurant. For example, a restaurant may create a new
menu item while you are retrieving menu items using the
/menuItems endpoint of the configuration API. If a
restaurant your client is retrieving paginated data for publishes any
changes to its configuration during the data retrieval, the Toast
platform now sends a 409 HTTP error (previously, it sent a 500 error in
this situation). If your integration client receives a 409 error, it
should re-submit the request it is making, without the
pageToken query parameter, so that the response restarts
from the first page. For more information, see Paginating response data.
A new Menu hierarchy section has been added to the Toast platform guide that provides detailed information about the menu hierarchy and its menu entities. This section also includes information about the rules for menu entity sharing and re-use. To illustrate the concepts discussed in the section, a diagram is provided that shows the menu hierarchy structure along with examples of the entity sharing and re-use rules.
The new menus webhook sends a message when a restaurant that uses your integration publishes a change to its menus. The message payload includes the GUID of the affected restaurant and a timestamp, in the UTC time zone, for when the restaurant last published its menus. For more information, see Menus webhook.
The new menus webhook is now the best way to determine when the
menu data for a restaurant becomes stale. Toast support recommends that
you use the menus webhook as a primary indicator and use the
/metadata endpoint of the menus API as a fallback method.
For example, your integration could check the /metadata
endpoint every 30 minutes, to make sure that you have not missed a
webhook message. For more information, see Determining if a restaurant's menu data has gone stale.
On 2022-01-17, the Toast platform will allow cash-out transactions
through gift card provider integrations. If your gift card provider
service uses the Toast gift card integration, your integration may
receive GIFTCARD_REDEEM type transactions with the
isCashOut value of the
TransactionInformationRedeem object set to
true. The value true indicates that the
restaurant redeemed gift card funds as cash paid out to the restaurant
guest. Currently, the Toast platform does not allow cash-out
transactions for gift card program integrations and the
isCashOut value is always false.
Toast cash drawer reports present cash-out gift card transactions separately from gift card purchase transactions. If your gift card provider service includes reporting information about gift card transactions, your integration should be prepared to present cash-out redeem transaction information by 2022-01-17.
The item and itemGroup values for menu
item selections in orders API response data now conform to a new
ConfigReference object type. The
ConfigReference object includes a new
multiLocationId value in addition to the guid
value for the item or item group. The ConfigReference
object and the multiLocationId value are components of
upcoming orders API functionality.
Currently, orders API response data includes
the new multiLocationId value. You can use the
multiLocationId value to associate menu entities that are
versions of a shared menu entity within a multi-location restaurant
group. Restaurant groups with multiple locations use menu entity
versions to customize shared menu entities for use at specific
locations. The multiLocationId value is a consistent
identifier that applies to all versions of a shared menu entity at all
locations in the restaurant group. The multiLocationId
value in the orders API corresponds to the masterId value
for menu configuration entities in the menus API (future Toast API
improvements will make the value names consistent). For more information
about the menus API masterId value, see multiLocationId values. For
more information about menu item versions, see Creating a version of a configuration entity.
The rate limit for the menus API has been increased from one request per minute per location to one request per second per location. For more information, see Toast rate limit values.
The orders API includes a new endpoint that you can use to add
menu item selections to an existing check. The
POST method of the new
/orders/
endpoint takes an array of {orderGuid}/checks/{checkGuid}/selectionsSelection objects and adds those
menu item selections to the order and check that you indicate in path
parameters. For more information, see Adding items to an existing check.
The orders API includes a new endpoint that you can use to update
delivery information for an existing order. The
PATCH method of the
/orders/
endpoint updates the following delivery information:
{orderGuid}/deliveryInfo
-
Delivery time
-
Dispatch time
-
Delivery state
-
Delivery employee
For more information, see Updating delivery information for an order.
The menus API now correctly returns modifier groups in the same order that the Toast POS app displays. The order of modifier groups is affected by the option a restaurant chooses in the Modifier ordering priority setting. Previously, the menus API always used Display Ordering Priority numbers when it calculated the order in which to return modifier groups, even if the Modifier ordering priority setting was Off. The Toast POS app was not affected by this problem and correctly ordered modifier groups according to the configuration of the Modifier ordering priority setting. This resulted in inconsistent modifier group ordering in the POS app and menus API.
Several settings and conditions affect the order that modifier groups are displayed in on Toast platform ordering channels, or returned by the menus API. For information about ordering modifier groups, see Modifier group display order overview. The incorrect modifier group ordering problem occurred in the following situation:
-
The Modifier ordering priority setting was Off.
-
The Display Ordering Priority number field for one or more modifier groups contained a number.
The menus API now orders modifier groups in the same way as the Toast POS app. For restaurant locations that use the modifier group configuration described above, the order in which modifier groups are returned by the menus API will change to match the order used by the Toast POS app.
The configuration API and the kitchen API use a new query parameter and response header field to control the pagination of endpoint requests. The existing pagination query parameters for configuration API endpoints are deprecated and will be removed from the API on 2021-12-06. You can test the new pagination parameter in the production environment immediately.
The new pagination query parameter and response header field are:
-
pageToken- A string that identifies the set of data objects that the endpoint will return in its response data. You can use this parameter to control the pagination of response data. You get the value that you supply in thepageTokenparameter from theToast-Next-Page-Tokenheader field value of a previous request to the endpoint. -
Toast-Next-Page-Token- A string that identifies the following set of objects that the endpoint will return. You can use this value to control the pagination of response data. To return the next page of objects you supply this value in thepageTokenparameter of the next request to the endpoint.
For more information, see Paginating response data.
The email message you receive when a restaurant location adds your integration partner service has changed. This change applies only to restaurant groups that use partner credentials, and does not affect groups that use restaurant management credentials.
-
The email message now contains only the restaurant location GUID for all new restaurant locations.
-
Previously, the email message for new restaurant locations that are not part of a multiple-location restaurant management group contained additional detail about the new location.
-
Previously, the email message contained information from the Toast restaurants API.
You should use this email as a secondary source of information only. We recommend using the partners webhook for the most up-to-date information about the list of restaurants that are connected to you integration.
You can get additional information about new restaurant locations from the restaurants API. For more information, see the restaurants API reference documentation.
Toast webhook HTTP messages now specify the Unicode character
encoding of the JSON message body in the HTTP Content-Type
header field.
-
Previously, the Toast webhook message
Content-Typeheader field specifiedapplication/json. -
Now, the
Content-Typeheader field specifiesapplication/json; charset=utf-8.
This change makes it easier for some webhook listening software to
interpret strings that include characters that require Unicode support.
For example, the string Café might be interpreted correctly
after this change when it was truncated or otherwise incorrectly
interpreted before.
This Toast API update fixes a problem that occasionally caused the
restaurantTimeZone value in the menus API
Restaurant object to be null. If the menus API
response data for a restaurant still includes a null
restaurantTimeZone value, it will be resolved when the
restaurant publishes again.
This Toast API update fixes a problem that caused the menus API to incorrectly calculate the price of modifier options that are reused in multiple menus and that also use menu-specific pricing. The corrected API behavior will result in a change to the pricing information that the menus API returns in this situation. This change will occur in the production environment on 2021-06-21.
|
Note |
|
You can use the orders API |
The type enumeration of the configuration API
TaxRate object includes a new EXTERNAL value
that indicates that the tax is for a marketplace facilitator order and
that the marketplace facilitator organization calculated the tax
amount.
For more information about getting orders with marketplace facilitator information, see Marketplace facilitator tax information.
The Order object used in the orders API and loyalty
API will handle information about refunds differently for restaurant
locations that use version 2.46 of the Toast POS mobile application.
Version 2.46 of the Toast POS application is expected to be available in
Toast platform restaurant locations starting on 2021-01-27.
Refund information for Toast platform orders is available in:
-
The
refundvalue of aPaymentobject. Therefundvalue is aRefundobject that describes a currency amount removed from a guest payment. -
The
refundDetailsvalue of theSelectionandAppliedServiceChargeobjects. TherefundDetailsvalue is aRefundDetailsobject that provides information about refunded currency amounts for an item selection, modifier option, or service charge
The new refund functionality in version 2.46 of the Toast POS
application no longer changes the totalAmount value for
checks.
Previously, restaurant employees voided items from checks to
give refunds to restaurant guests on POS devices. The void transaction
updated the totalAmount value. Now, the new refund
functionality on a Toast POS device is separate from the item void
function in the Toast POS application. The amount of the refund is
available in the RefundDetails object.
For example, if a restaurant employee gives a guest a $7 refund
for a $20 check using a Toast POS device, previously the
totalAmount would have been $13. Now, the
totalAmount remains $20.
In restaurants using versions of the Toast POS application
earlier than 2.46, you can perform refunds from Toast Web that
do not require voiding items and do
not update the totalAmount value for checks.
Before version 2.46, this behavior was different from POS device
refunds. Now Toast Web refunds and POS device refunds affect check
amounts consistently. No refunds will change the check amount.
This change might affect the way that you implement a Toast
loyalty API integration. Because previous refund transactions used the
void function of the POS app, some refund transactions caused the
Toast platform to update the totalAmount value for a
check. It was possible to adjust loyalty rewards accrual amounts based
on the updated totalAmount value. This is no longer
possible.
If your integration needs to determine whether an employee
issued a refund, the integration can determine that by examining the
refund value of the Payment object and the
refundDetails value of the Selection and
AppliedServiceCharge objects.
The RefundDetails object that includes information
about refunded currency amounts for an item selection, modifier
option, or service charge no longer returns null values.
The RefundDetails object is part of the new refund
functionality of the Toast platform.
The externalRestaurantRef value in partners webhook
payloads for a restaurant location now reports restaurant location
identifiers correctly. Previously, partners webhook payloads sometimes
included the incorrect location identifier for a restaurant
location.