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:

For more information about the new orders webhook, see Orders webhook.

The Premodifier object of the menus API has been updated with the following values:

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.

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.

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.

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"
    }
]

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:

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.

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.

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.

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:

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.

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:

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:

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 Toast loyalty integration now supports guest telephone number formats for countries other than the United States. Previously, the loyalty integration did not accept international phone number formats.

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.

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.

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:

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:

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.

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:

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.

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.

{
        "guid": "e3c23dd7-7e01-4388-b6a4-65efa53d4ccf",
        "entityType": "TimeEntry",

        [contents omitted]        

        "deleted": true,
        "deletedDate": "2023-05-23T23:42:53.671+0000",

        [contents omitted]

    }

The Location object in the restaurants API includes two new values:

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.

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.

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.

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.

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.

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:

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:

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:

Can be combined into:

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:

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.

"menuItems": [
  {
    "name": "Rum Punch",
    "guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
    "multiLocationId": "100000000100009153",

    [contents omitted]

    "contentAdvisories": {
      "alcohol": {
        "containsAlcohol": "YES"
      }
    }
  }                       
]

"menuItems": [
  {
    "name": "Rum Punch",
    "guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
    "multiLocationId": "100000000100003519",

    [contents omitted]

    "contentAdvisories": {
      "alcohol": {
        "containsAlcohol": "YES"
      }
    }
  }                       
]

"menuItems": [
  {
    "name": "Rum Cake",
    "guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
    "multiLocationId": "100000000100009153",

    [contents omitted]

    "contentAdvisories": {
      "alcohol": {
        "containsAlcohol": "NO"
      }
    }
  }                       
]

"menuItems": [
  {
    "name": "Grilled Cheese",
    "guid": "0a6e4999-cfl1-4dd6-bf4d-f4d2b65f7d88",
    "multiLocationId": "100000000100009153",

    [contents omitted]

    "contentAdvisories": {
      "alcohol": {
        "containsAlcohol": null
      }
    }
  }                       
]

"modifierOptionReferences": {
  "1": {
    "referenceId": 1,
    "name": "Rum Shot",
    "guid": "429f9045-74a1-81bc-4c48-86ce51c2f6ae",
    "multiLocationId": "100000000100008684",

    [contents omitted]

    "contentAdvisories": {
      "alcohol": {
        "containsAlcohol": "YES"
      }
    }
  }
}

"modifierOptionReferences": {
  "2": {
    "referenceId": 2,
    "name": "Lettuce",
    "guid": "429f9045-74a1-81bc-4c48-86ce51c2f6ae",
    "multiLocationId": "100000000100008684",

    [contents omitted]

    "contentAdvisories": {
      "alcohol": {
        "containsAlcohol": "NO"
      }
    }
  }
}

"modifierOptionReferences": {
  "3": {
    "referenceId": 3,
    "name": "Cheese",
    "guid": "429f9045-74a1-81bc-4c48-86ce51c2f6ae",
    "multiLocationId": "100000000100008684",

    [contents omitted]

    "contentAdvisories": {
      "alcohol": {
        "containsAlcohol": null
      }
    }
  }
}

The labor API TimeEntryBreak object now includes a guid value. The GUID value is the Toast platform identifier for an individual break entry.

Several improvements and updates have been made to the stock API and the stock webhook.

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:

Previously, the Toast platform followed these rules for pausing and stopping webhook subscriptions that were experiencing errors:

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:

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.

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.

The taxInclusion value is a string that represents the tax inclusion setting for the menu item. Values include:

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.

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/{orderGuid}/checks/{checkGuid}/selections endpoint takes an array of Selection 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/{orderGuid}/deliveryInfo endpoint updates the following delivery information:

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 setting 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 No. 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 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:

For more information, see Paginating response data.

The orders API Order object includes a new guestOrderStatus value. This value is reserved for future use in the orders API. Do not use the new value in your Toast API integration.

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.

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.

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.

The source value of the orders API Order object contains a new Google value. When the source value in an order object is Google, it indicates that the order originated from a Google™ food ordering application.

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.

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 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.