This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Toast API Release Notes

This document describes the changes in Toast API releases.

See more information about using Toast APIs in the Toast API Developer Guide and the reference documentation for each API.

Ongoing API release notes at new Toast technical documentation site

All new Toast API changes will be announced in the API release notes section of the new Toast technical documentation site.

This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site.

rel20220311

Webhooks retry messages after HTTP 429 response

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.

rel20220302

Summary of the `Order` object now available

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.

Orders API includes a new order source enumeration value and an updated source value name

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.

Updated error rate limits for Toast webhook subscriptions

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.

rel20220209

Loyalty API `externalId` value for menu entities will be null

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.

rel20220131

Orders API includes new `Invoice` order source enumeration value

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.

New `multiLocationId` identifier for menus API menu entities

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.

rel20220121

New email subscription for webhook notifications

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.

Gift card add value transactions limited to $500

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.

Loyalty account identifier on reversal can be null

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 loyaltyIdentifier value in the TransactionInformationCheck object is null. 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 loyaltyIdentifier value of the TransactionInformationReverse object for the reversal request. This behavior will change on 2022-03-14 and the loyaltyIdentifier on this transaction will be null.

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 the procedure above.

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.

Menus API menu item includes taxInclusion value

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 taxInclusion value will not appear in the menus API response data until restaurant employees make a menu-related change and publish that change. For more information, see API updates may require publishes.

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

rel20211216

New order management configuration API

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 and or delivery. For more information about the order management configuration API, see Order Management Configuration API.

409 error indicates a restaurant published new data during retrieval of a paginated response

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.

Detailed menu hierarchy description and diagram are available

A new Menu hierarchy section has been added to the Toast Administrator’s 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.

rel20211210

New menus webhook indicates changed menus

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.

rel20211117

Gift card integration will include cash-out redeem transactions

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. When you receive a GIFTCARD_REDEEM request with the isCashOut value set to true, your integration should reduce the gift card account balance to 0.00 and categorize the redeemed funds as a cash-out transaction. 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.

New `multiLocationId` value in orders API menu item selections

The item and itemGroup values for menu item selections in orders API response data now use 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 masterId values. For more information about menu item versions, see Managing versions.

Menus API rate limit increase

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

rel20211008

New orders API endpoint adds selections to a check

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

New orders API endpoint updates order delivery information

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:

Delivery time
Dispatch time
Delivery state
Delivery employee

For more information, see Updating delivery information for an order.

Menus API modifier group ordering correctly follows Modifier Ordering Priority setting

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 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. The incorrect modifier group ordering problem occurred in the following situation:

The Modifier Ordering Priority setting was No.
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.

rel20210903

New pagination parameter for the configuration and kitchen APIs, old pagination parameters deprecated

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 the pageToken parameter from the Toast-Next-Page-Token header 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 the pageToken parameter of the next request to the endpoint.

For more information, see Paginating response data.

New `guestOrderStatus` in the orders API

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.

rel20210702

New email format for new integrated restaurant locations

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 and the partners API 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.

Webhooks HTTP message `Content-Type` header field specifies JSON character encoding

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-Type header field specified application/json.
Now, the Content-Type header field specifies application/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.

New `Google` order source in the orders API

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.

rel20210611

Menus API `restaurantTimeZone` value is no longer `null`

A problem that occasionally caused the restaurantTimeZone value in the menus API Restaurant object to be null has been fixed. If the menus API response data for a restaurant still includes a null restaurantTimeZone value, it will be resolved when the restaurant publishes again.

Menus API will correctly support menu-specific pricing for reused modifier options

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 has been fixed. 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 /prices endpoint to return correct pricing information for the menu items and modifier options in an order.

New `EXTERNAL` tax rate type in configuration 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.

rel20210527

Orders API returns information about marketplace facilitator tax payments

The orders API now returns information about the tax payments for orders that are directly submitted by marketplace facilitators.

For Toast platform restaurants, a marketplace facilitator is a business that:

Takes guest orders, processes guest payments, and then directly submits those orders to a Toast platform restaurant for fulfillment.
Is required by a taxing authority to pay tax amounts for the orders they process on behalf of the restaurant location.

For example, a restaurant ordering service like Grubhub™, Doordash™, or Uber Eats® that accepts orders for a large number of restaurants might take guest orders and payments and then submit the order to the Toast platform for fulfillment at a Toast platform restaurant. The ordering service receives the guest payment and then remits the applicable tax amounts.

Orders API response data for restaurants that receive orders from a marketplace facilitator will include tax information that shows whether the marketplace facilitator calculated the tax amount separately from the Toast platform and whether the marketplace facilitator remitted the tax amounts on behalf of the restaurant location.

The AppliedTaxRate object of the orders API includes a new facilitatorCollectAndRemitTax value to indicate whether the marketplace facilitator that received a guest order remitted the tax amount on behalf of the Toast platform restaurant. You can use this information to identify tax amounts that have already been paid by a marketplace facilitator and do not need to be paid again.

The type value of the AppliedTaxRate object includes a new EXTERNAL enumeration 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.

Orders API `ordersBulk` endpoint rate limit will be reduced

On 2021-07-12, the ordersBulk endpoint of the orders API will reduce the rate limit for requests. The new rate limit will be five requests per client per location per second. For more information about Toast API rate limits, see Rate limiting.

Orders API returns server employee identifier for payments

The orders API Payment object includes a new server value. The server value is the Toast platform GUID of the restaurant employee, or server, who is assigned to the order that the payment is for.

New kitchens API

The new kitchens API provides information about the preparation (prep) stations configured for a restaurant location. For more information about the kitchens API, see the kitchens API reference documentation.

Menus API includes prep time and prep station information

The MenuItem object includes two new values to provide information about the preparation time and prep station configuration for a menu item.

prepTime - the amount of time, in seconds, that it takes to prepare the menu item. This value is null if a prep time has not been specified for the menu item.
prepStations - an array of GUIDs for the prep stations that have been assigned to this menu item. This value is null if no prep stations have been assigned.

New employee identifier values in cash management API

The cash management API CashEntry and Deposit objects include new values that will be used for future API functionality development. Do not use the new values in your Toast API integration.

New CashEntry object values:

creatorOrShiftReviewSubject - An alternative identifier for the employee represented by employee1.
approverOrShiftReviewSubject - An alternative identifier for the employee represented by employee2.

New Deposit object value:

creator - an alternative identifier for the employee who created the deposit.

rel20210428

Menus API returns correct `pricingRules` information for nested modifier groups

A problem that caused the pricingRules value of a nested modifier group to be empty if that modifier group used a size price, sequence price, or size/sequence price has been fixed. Now the JSON return data for a nested modifier group contains the correct pricing information.

A nested modifier group provides additional choices for a modifier option. For example, you can have an entrée that has a Sides modifier group that contains a Salad modifier option. The Salad modifier option has its own modifier group, Salad Dressing, that includes Ranch, Vinaigrette, and Blue Cheese modifier options. Salad Dressing is a nested modifier group and the individual salad dressings are nested modifier options.

For more information about pricing rules, see Using PricingRules and PricingStrategy to Calculate Prices.

Labor API `Employee` object includes new `v2EmployeeGuid` value

The Employee object includes a new v2EmployeeGuid value. The v2EmployeeGuid value is included for future use. The value is an alternate Toast platform GUID for the employee that will be used in upcoming labor API functionality.

Credit cards API will not return `null` denial reasons

The denialReason value of the PaymentStatus object will no longer return null values on 2021-05-10. Currently the denialReason value is null for some credit card authorization attempts. Starting on 2021-05-10, the credit cards API will always return a string that describes the denial reason for all credit card authorization attempts.

New order information in the orders API

The orders API returns new information in the return information for orders:

New receiptLinePrice and optionGroupPricingMode values in the Selection object. The receiptLinePrice value indicates the price of the menu item selection before any taxes, discounts, and modifier option adjustments are applied. The optionGroupPricingMode value describes how the modifier group affects the pricing of its parent item. For example, INCLUDED, FIXED_PRICE, or ADJUSTS_PRICE.
New 'discountType' and 'discountPercent' values in the AppliedDiscount object. The discountType value describes the type of the discount. For example, FIXED, BOGO, or PERCENT. The discountPercent indicates the percent value (0-100) of the discount when the type is PERCENT.

rel20210331

Menus API v1 sunset

Version one of the menus API has been removed from all Toast API environments. Your integration can use version two of the menus API.

rel20210201

Orders API returns HTTP 503 service unavailable responses more quickly

The orders API now returns HTTP 503 Service Unavailable response messages more quickly when Toast platform components are not available to perform order operations. Previously, the orders API responded to service unavailability after a longer period of time, and with an HTTP 500, Internal Server Error message.

rel20210113

Refund information changes in `Order` object changes to support new refund functionality

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 refund value of a Payment object. The refund value is a Refund object that describes a currency amount removed from a guest payment.
The refundDetails value of the Selection and AppliedServiceCharge objects. The refundDetails value is a RefundDetails object that provides information about refunded currency amounts for an item selection, modifier option, or service charge

Behavior of `totalAmount` value consistent for all refunds

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 the Toast administration back-end 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 administration back-end 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.

Refund details object values include refund information

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 RefundDetails object was announced on 2020-08-28.

For examples of refund information JSON, see Refund information in Order objects.

Restaurant employees can refund more payment types

Restaurant employees can use the new refund functionality to refund:

Credit card payments
Cash payments
Toast gift card payments

Previously, employees could only refund credit card payments.

Partners webhook reports location identifier correctly for restaurants

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.

rel20201218

Deprecated authentication endpoint sunset on 2021-01-15

The deprecated /usermgmt/v1/oauth/token endpoint for API authentication will be sunset on 2021-01-15. After this date, the /usermgmt/v1/oauth/token endpoint will no longer be available for API authentication.

As described in the deprecation announcement, the REST web service that you use to get a Toast API authentication token has been replaced. The new authentication service REST path is:

https://[toast-api-hostname]/authentication/v1/authentication/login

Important: After 2020-01-15, any integrations that depend on authentication tokens from the /usermgmt endpoint will fail. Your integration will not function correctly if you do not switch to the new authentication endpoint before 2020-01-15.

`Order` object `source` value contains `OPT`

The source value of the orders API Order object can now contain the value OPT. OPT indicates that the order was created by the Toast order and pay feature.

rel20201103

Tax rate `type` value correctly reports `PERCENT`

The configuration API now reports the type value for PERCENT-type tax rates correctly. Previously, the type value of the TaxRate object was null for PERCENT-type tax rates in some situations. The problem is now fixed.

rel20201022

Authentication tokens now valid for 24 hours

Toast API authentication tokens are now valid for 24 hours after the authentication service issues them. Previously, authentication tokens were valid for one hour.

Your integration no longer needs to get new authentication tokens every hour. Limit requests for new authentication tokens to two each day. Using two tokens in a day provides a period of time in which both tokens are valid and your integration can request a new authentication token.

For more information about getting and using authentication tokens, see Authentication and Restaurant Access.

rel20201001

Orders API orders will apply automatic service charges

Service charges that you apply when you create a dine-in order using the orders API will persist on the order correctly starting on 2020-10-05. This change affects orders that:

Are created for a dine-in dining option, at a table in a restaurant service area that is configured to apply an automatic service charge.
Include a service charge, applied to a check.
Are created with no menu item selections in a check.

Currently, if you create an orders API order in this situation, the Toast platform removes the initial service charge when a restaurant employee adds a menu item to the check. This behavior will change starting on 2020-10-05.

For information about creating an order at a restaurant location table, see Creating an Order at a Restaurant Table.

For information about applying service charges to orders API orders, see Service Charges for Checks.

For information about configuring service areas, see this Toast Central article.

rel20200918

Revenue center information included in configuration API ServiceArea and Table objects

The configuration API ServiceArea and Table objects now include a revenueCenter value to indicate the restaurant revenue center that the service area or table is assigned to. If a service area or table is not assigned to a revenue center, the revenueCenter value is null.

You can use revenue centers to identify areas within a restaurant in financial reporting. For more information about including revenue centers in orders API orders, see Creating an Order at a Restaurant Table. For more information about using revenue centers in reporting, see Revenue Centers.

rel20200828

Orders API includes values for information about refund transactions

The orders API includes a new RefundDetails object that includes information about refunded currency amounts for an item selection, modifier option, or service charge. The refund information includes separate values for the pre-tax value being refunded and the tax amount being refunded.

The RefundDetails object is used as the data type for the following new values:

The Selection object includes a new refundDetails value to provide refund information for menu item selections and modifier options.
The AppliedServiceCharge object includes a new refundDetails value to provide refund information for service charges.

The new refundDetails values and the RefundDetails object have been added to support upcoming Toast platform refund functionality. Until that functionality is complete, the refundDetails values for items and service charges will be null.

The existing Refund object includes a new refundTransaction value. The Refund object includes information about refunded amounts in a Payment object. The new refundTransaction value for payments includes an identifier for the refund transaction. You can match the refundTransaction identifier value in the Refund object to the refundTransaction identifier value in the new RefundDetails object and associate items and service charges that were refunded in the same transaction.

Payment object includes order and check identifiers

The orders API Payment object now includes an orderGuid value and a checkGuid value to indicate the Toast POS system identifiers of the order and check that the payment applies to. You can use the order and check identifiers to match payment information with specific orders that you retrieve from the /orders/{guid} endpoint.

Authentication service improvements in test environment, scheduled for production environment

The Toast API authentication service has been upgraded to improve performance and reliability. The upgrade changes have been deployed to the sandbox environment and are available for testing. The upgrade changes will be deployed to the production environment on 2020-09-17.

The authentication service changes affect the way that you perform authentication as a client, using Toast API server resources. The following APIs are made up of server resources that you use as a client:

Cash management
Configuration
Credit cards
Labor
Menus
Orders
Partners
Restaurants
Stock
Partner

Make sure that you confirm that your integration can use the upgraded authentication service by performing at least one test authentication and API request to a server resource in the sandbox environment before 2020-09-18. If you experience an HTTP 403 or 500 error, please contact the Toast technical partnership team.

rel20200810

Stock API verifies that menu items exist

The stock API has begun verifying that menu items exist and are not archived when returning information about inventory status.

The /inventory/search endpoint of the stock API returns inventory status information for a list of menu item GUIDs. Currently, the endpoint returns the IN_STOCK status value for menu item GUIDs that do not exist or are archived in the menu configuration for a restaurant. After this change, these GUIDs will be considered invalid and the endpoint will return additional data to help you identify them. Specifically, the endpoint will include an itemGuidValidity value for all menu items and it will set this value to VALID, if the menu item GUID is valid, or INVALID, if the menu item GUID is invalid. If a menu item GUID is invalid, the status for that menu item is set to OUT_OF_STOCK. The example below shows both a valid menu item GUID and an invalid one.

  [
    {
      "guid": "0007a427-467c-499b-9f8e-f103c7e29591",
      "itemGuidValidity": "INVALID", 
      "status": "OUT_OF_STOCK", 
      "quantity": null
    },
    {
      "guid": "ee28b1ba-6d3b-415a-b37b-b28786f119ea", 
      "itemGuidValidity": "VALID", 
      "status": "IN_STOCK", 
      "quantity": null
    }
  ]

Note: This release note supersedes the release note from 2020-07-20. The approach described in this earlier note has been replaced by the approach described here.

Stock API verifies that menu items exist

The stock API will begin verifying that menu items exist and are not archived when returning information about inventory status on 2020-07-20. The /inventory/search endpoint of the stock API returns inventory status information for a list of menu item GUIDs. Currently, the endpoint returns the IN_STOCK status value for menu item GUIDs that do not exist or are archived in the menu configuration for a restaurant. After this change, the endpoint will return an HTTP 404 response to a request if that request includes a menu item GUID that is not present in the restaurant configuration or is archived.

You can use the menus API and the configuration API to determine whether a menu item exists at a restaurant location and whether it is archived.

The response message body will include each GUID that was not found at the restaurant. The following example shows the response body when GUIDs are not found.

{
    "status": 404,
    "code": 10003,
    "message": "Could not find menu item guids: [
      87308b32-7987-4fca-b7d2-d01a9bbe8a98, 
      a243694a-5bbb-4e46-a935-e9d0224dbdb3, 
      1415f2a2-f06c-4ed1-9c23-5c6e4f27e492]",

    [contents omitted]

}

New takeout value for service charge criteria in the configuration API

The ServiceChargeCriteria object in the configuration API now includes a takeout value. You get information about service charges, including the criteria that the Toast platform uses to apply service charges from the /serviceCharges endpoint of the configuration API. The takeout value indicates whether the service charge is automatically applied to orders that have the takeout dining option behavior. For more information about dining options and dining option behaviors, see Dining Options.

rel20200619

New `curbside` value in the `DiningOption` object in the configuration API

When you use the /diningOptions endpoint of the configuration API to GET the list of a restaurant’s dining options, each DiningOption object now contains a curbside value that is set to true or false.

A limited number of Toast restaurants are able to configure a dining option to have curbside behavior. If a dining option is configured to have curbside behavior, the curbside value in its corresponding DiningOptions object is set to true. For more information, see Dining Options for Orders.

Orders API supports curbside pickup information in order creation requests

You can now include the CurbsidePickupInfo object in a POST request to the orders API when you are using a dining option that is configured to have curbside behavior.

A limited number of Toast restaurants are able to configure a dining option to have curbside behavior. If you are POSTing an order using a dining option with curbside behavior, you can choose to include the CurbsidePickupInfo object in the request body. If you include the object, it must contain the transportDescription field that provides information such as the make or model of the guest’s vehicle. This information is used by the restaurant to identify the guest when they arrive outside the premises to pick up their order. For more information, see Creating Curbside Pickup Orders.

Note that a restaurant’s Toast POS devices must use at least version 2.41 of the Toast POS app to process orders that have curbside dining option behavior.

rel20200612

Menu Item Visibility Configuration Changes Beginning Rollout

Configuration changes for the menu visibility updates that were previously announced will begin to affect restaurants in the production environment on 2020-06-17. These configuration changes may change the visibility and orderableOnline values for a menu item in the configuration API. Your integration should use the menus API to get information about menu items and should not be affected by this change to menu item information in the configuration API. The configuration changes will affect a limited number of restaurants on 2020-06-17 and will roll out to all Toast platform restaurants over several weeks. For more information about the changes to visibility and orderableOnline values in the configuration API, see Understanding the New Visibility Behavior.

rel20200529

New `createdDate` Values in `Order` and `Check` Objects in the Orders API

The Order and Check objects in the orders API now include a createdDate value. The createdDate value indicates the date and time that the cloud components of the Toast platform initially received information about the order or check.

The date and time that the cloud components of the Toast platform receive order and check information depends on the way a restaurant creates the order or check. For example, a period of time might pass between the date and time a restaurant employee creates an order using a Toast POS device and the date and time that the POS device uploads the order to the cloud components of the Toast platform. Orders created using the orders API are immediately created in the cloud components of the Toast platform.

The createdDate value can be different from the openedDate value. The openedDate value indicates the business day for an order or check. You can set the openedDate explicitly to control the business date of a check or order. You can use the new createdDate value to distinguish orders that are expected to be fulfilled at a later date and time (future orders). For more information, see Scheduling Future Orders.

rel20200514

Menus API Changes for Improved Menu Visibility Settings Are Now Available in the Production Environment

The API changes for the menu visibility updates that were previously announced are now available in the production environment and online ordering partners can deploy updated menu visibility code to production at any time before the deadline of 2020-05-25.

For any entity that should be visible on an ordering partner’s website, the menus API will include the ORDERING_PARTNERS enum in the visibility array for that entity. The TOAST_ONLINE_ORDERING enum will still be present; however, you should use the ORDERING_PARTNERS enum, not the TOAST_ONLINE_ORDERING enum to determine if a menu entity should be displayed on your site. Note that the user interface for these new visibility settings is still on hold until 2020-05-25, meaning that restaurants will not be able to select the corresponding Ordering Partners configuration option until after that date.

Note that the ORDERING_PARTNERS enum is added to a menu entity’s visibility array in the menus API when, in the configuration API, the following two conditions are true:

The visibility value is set to ALL.
the orderableOnline value is set to YES.

rel20200501

New Authentication Endpoint Available, Existing Authentication Endpoint Deprecated

The REST web service that you use to get a Toast API authentication token has been replaced. The new authentication service REST path is:

https://[toast-api-hostname]/authentication/v1/authentication/login

You use the authentication service to get an authentication token string that you present when you make other Toast API requests. For more information about using the Toast API authentication service, see Authentication and Restaurant Access.

The previous Toast API authentication service endpoint (/usermgmt/v1/oauth/token) is deprecated and will remain available until 2020-06-30. Your integration must use the new authentication endpoint before that date.

New Credit Card Metadata Values Will Be Required For Enhanced Fraud Prevention

The PaymentRequestMetadata object for a credit cards API authorization request now accepts additional values that describe the credit card payment being made by a restaurant guest. These values improve the fraud detection capability of the API and protect against credit card payment chargebacks.

The new values for a PaymentRequestMetadata object are:

cardFirst6 - The first six digits of the credit card number.
cardLast4 - The last four digits of the credit card number.
billingAddress - A BillingAddress object containing the geographic credit card billing address entered by the restaurant guest making the payment.
deliveryAddress - A DeliveryAddress object containing the geographic delivery address entered by the restaurant guest making the payment.
userAgent - For payments taken through a browser, the browser's user agent string.
guestIdentifier - A stable identifier for the guest making the payment. For example, an email address or UUID. The guestIdentifier is used to establish history that can be used to identify fraudulent activity. This value does not need to be unique.
guestEmail - The email address of the restaurant guest making the payment.
appName - A company-specific name for the mobile app (if any) the payment is made through.
appVersion - The version of the mobile app (if any) the payment is made through.

The new values are currently optional for all authorization requests. On 2020-06-30, a subset of the new values will be required for authorization requests using credit card information supplied directly by a restaurant guest (not stored information). For authorization requests that use credit card information supplied directly by a restaurant guest, the cardNumberOrigin value of a PaymentAuthorization object is set to END_USER.

The subset of new values that will be required for authorization requests using END_USER credit card information is:

cardFirst6
cardLast4
billingAddress
guestIdentifier

rel20200417

Menu Entity Visibility and API Changes

The way that Toast POS system restaurants configure whether menu entities (menus, menu groups, menu items, modifier groups, and modifier option item references) should be displayed on integrated online ordering web sites (visibility) is changing. This change also affects the way that Toast APIs return information about whether menu entities should be displayed on integrated online ordering web sites. The changes will affect the production environment of the Toast POS system on 2020-05-25. Your integration must use the new Toast API values for menu entity visibility before that date in order for the menus displayed in your system to reflect the menu display preferences configured by the restaurant. The changes are available for testing in the sandbox environment now.

IMPORTANT: The updated API behavior that corresponds to the new restaurant configuration is available in version 2 of the menus API.

To accommodate these changes, your integration must transition from using the orderableOnline and visibility values in the configuration API to using the visibility array that version 2 of the menus API returns for each menu entity. Also, if your integration uses the TOAST_ONLINE_ORDERING enum in the visibility array that the menus API returns for each menu entity, you must switch to using the new ORDERING_PARTNERS enum instead. For detailed information about these changes, see Menu Entity Visibility Enhancements in the Toast API Developer's Guide for details.

rel20200403

Webhook Type Renamed Event Category

The concept of “webhook type” for Toast webhooks is now named “event category.” An event category, which was previously named webhook type, is a Toast-defined classification for the types of events a webhooks sends. For example, the partners event category sends webhook events related to the addition or removal of partner integrations for a restaurant location. As a result of this change, the webhookType JSON value that was returned for all webhook updates has been renamed eventCategory and the Toast-Webhook-Type HTTP header field has been renamed Toast-Event-Category.

`lastModified` Query Parameter for Partners API `restaurants` Endpoint

The /restaurants endpoint of the partners API includes a new lastModified query parameter. You can use the lastModified parameter to limit the restaurants returned by the endpoint to restaurants that added or updated the configuration for your partner integration after a specific date and time. For more information, see the partners API reference.

Loyalty API Will Include Transaction Identifier Header Parameter for Search Requests

The Toast POS system will begin sending the Toast-Transaction-GUID header field for loyalty account search transactions in an upcoming release. The Toast-Transaction-GUID header field value is a unique identifier for the transaction requests that the Toast POS system sends to loyalty program providers. Currently, the Toast POS system does not include the Toast-Transaction-GUID header field for search transactions. The Toast POS does include the Toast-Transaction-GUID header field for all other loyalty API transaction types. This change makes the Toast-Transaction-GUID header field behavior for search transactions consistent with the other transaction types.

Orders API No Longer Checks Dining Option Configuration, API Configuration Option Will Be Removed

The orders API no longer verifies that a dining option is configured to be available using the API when processing orders. On 2020-04-20, the API configuration option for dining options will be removed from the Toast administration back-end Dining Options page. Previously, using the orders API for a dining option required restaurant employees to enable API for that dining option. If your integration onboarding or training information refers to enabling the API configuration option for a dining option, you can remove those references now.

rel20200320

Header Field, Payload Value Name, and Message Signing Changes for Webhooks

The following sections describe changes to Toast webhook behavior.

toast-restaurant-guid HTTP Header Will Be Renamed Toast-Restaurant-External-ID

To be consistent with other Toast APIs, the toast-restaurant-guid HTTP header that is included with some webhook updates will be renamed to Toast-Restaurant-External-ID on 2020-03-16.

The Toast-Restaurant-External-ID HTTP header is defined, along with all the other HTTP headers that are included in webhook updates, in the HTTP Headers section of the Toast API Developer's Guide.

`payload` Value in Webhook Updates Has Been Renamed to `details`

The payload value in webhook updates has been renamed to details. This value contains the JSON data that is specific to the type of webhook that triggered the update. See Message Data Schema in the Toast API Developer's Guide for details.

Message Signing for Webhook Updates Is Now Available

The Toast POS system now implements message signing that allows you to validate the source of data sent to your webhook endpoint. While using message signing is optional, it is highly recommended. For information on using message signing, see Message Signing in the Toast API Developer's Guide.

Pagination Link URL to Next Page of Results Will Be Corrected in Configuration API

The configuration API will correct the content of pagination links on 2020-04-20. Currently, pagination links sometimes include:

Query parameter timestamps without URL encoding
Connection port numbers

This problem has been corrected in the sandbox environment. The problem will be corrected in the production environment on 2020-04-20. For more information about API pagination, see Response Data Pagination.

rel20200306

New `modifierOptionTaxInfo` Value for Modifier Options in the Menus API, `taxInfo` Deprecated for Modifier Options

New Toast POS system functionality allows restaurants to choose additional taxation behaviors for modifier options.

The menus API ModifierOption object includes a new modifierOptionTaxInfo value. The modifierOptionTaxInfo value supports the new tax configuration options for modifier options.
The existing menus API taxInfo value for ModifierOption objects does not support the new tax configuration options for modifier options.
The existing taxInfo value for ModifierOption objects is deprecated. Your integration must use the new modifierOptionTaxInfo value instead of the taxInfo value for modifier options before the new configuration options for modifier option tax are available in the production environment on 2020-05-04.

For more information about using the new modifierOptionTaxInfo value and working with the new tax configuration settings for modifier options, see Using taxInfo and modifierOptionTaxInfo to Calculate Taxes for Menu Items and Modifier Options in the Toast API Developer's Guide.

The new tax configuration settings for modifier options are available for testing your integration in the sandbox environment now.

Note: You can use the new modifierOptionTaxInfo value to make it easier to display check prices to restaurant guests. Using the /prices endpoint is the only reliable and supported way to determine the payment amount for a check. If you POST an order with an inaccurate payment amount, the Toast POS system will require restaurant employees to handle the underpayment or overpayment during order fulfillment. For more information, see Getting Check Prices.

Note: The new modifierOptionTaxInfo value of the ModifierOption object is only available in version two of the menus API.

rel20200214

Menus API v1 Sunset on 2020-05-25

Version one of the menus API will be removed from Toast API environments on 2020-05-25. Your integration must use version two of the menus API before that date. You can use the menus API v2 in the sandbox environment for testing immediately and you can use v2 in production when your integration is ready. Contact the Toast integrations team if you need assistance making plans to transition your integration from menus API v1 to menus API v2.

Menus API v2 uses a more efficient structure for representing modifier groups, modifier options, and premodifier groups. The new structure dramatically reduces the size of the JSON response payload by creating a single instance of each unique modifier group, modifier option, and premodifier group, and using reference IDs to refer to those instances. For detailed information about the new structure and the values and objects that support it, see referenceId Values and <menu-entity>References Objects.

Stock Webhook Available

You can use the stock webhook to receive updates when the inventory status of a menu item or a modifier option changes. For more information, see the stock webhook reference. To enable the stock webhook for your integration, contact the Toast integrations team.

rel20200117

Menus API v2 Available

Version two of the menus API is now available in the production environment. Menus API v2 uses a more efficient structure for representing modifier groups, modifier options, and premodifier groups. The new structure dramatically reduces the size of the JSON response payload by creating a single instance of each unique modifier group, modifier option, and premodifier group, and using reference IDs to refer to those instances. For detailed information about the new structure and the values and objects that support it, see referenceId Values and <menu-entity>References Objects.

rel20200110

`TimeEntry` Object Returns Rounded Hour Values for Some Restaurant Locations

If the Time Entry Rounding Scheme configuration option for a restaurant is set to Each time entry is rounded, then added together for total hours, the regularHours and overtimeHours values in the labor API TimeEntry object will return hour amounts rounded to the nearest hundredth of an hour (0.01 precision). Currently, the regularHours and overtimeHours values always return the full, unrounded hour amounts. This change will occur on 2020-02-24.

The regularHours and overtimeHours values will continue to return full, unrounded hour amounts for restaurants that set the Time Entry Rounding Scheme configuration option to All time entries are added together, then rounded for total hours.

For more information about the Time Entry Rounding Scheme configuration option, see Time Clock.

Labor API Handles Error Conditions More Correctly

The labor API now returns an HTTP 400 error response instead of a 500 server error response when you include a JobWageOverride object with a null wage or jobReference value in a request to the /employees/{employeeId}/wageOverrides endpoint.

CVV No Longer Required For Credit Card Authorization Using Stored Card Information

The credit cards API no longer requires the card verification value (cvv) value when you request a credit card payment authorization using stored credit card information. When you request a credit card payment authorization using stored card information, you set the cardNumberOrigin of the PaymentAuthorization object to PARTNER_VAULT. If cardNumberOrigin is set to PARTNER_VAULT, the cvv value in the encrypted credit card information you send is optional.

If you set the cardNumberOrigin value to END_USER, the cvv value in the encrypted credit card information you send is still required.

If you include the cvv value with credit card information and set the cardNumberOrigin value to PARTNER_VAULT, the credit cards API will verify that the CVV value is correct. If the CVV value is not correct, the credit cards API will reject the payment authorization request.

For more information about the cardNumberOrigin value of the PaymentAuthorization object, see Authorizing a Credit Card Payment.

rel20191213

New Stock API Provides Inventory Information

You can use the new stock API to get inventory information about the menu items and modifier options at a restaurant. For example, you can use the stock API to determine whether a menu item is in stock, out of stock, or the quantity of the menu item that is available. For more information about using the stock API, see Toast Stock API and Inventory.

To use the stock API, your Toast API client needs the stock scope. If you need the stock scope, contact the Toast integrations team.

New `PROCESSING_VOID` Payment Status Enumeration Value in the Orders API

The paymentStatus value of the orders API Payment object will include a new enumeration value, PROCESSING_VOID on 2020-01-27. The PROCESSING_VOID value indicates that a restaurant employee voided the payment and the Toast POS system is waiting for a payment processing service to confirm that the payment is reversed.

rel20191122

Kiosks Allow Loyalty Integration Account Transactions

Toast POS system kiosk devices now allow restaurant guests to look up their own loyalty/rewards accounts at restaurants that use a loyalty program integration. The kiosk interface includes a Rewards button that guests can use to look up their accounts, accrue rewards, and redeem rewards. Kiosk device using the device camera to scan account identifiers encoded as 2D bar codes (QR codes).

Loyalty Integration Check Information Includes Order GUID

The TransactionInformationCheck object that includes information about a Toast POS system check (menu items ordered by a restaurant guest) now includes an orderGuid value. The orderGuid value includes the unique Toast POS system identifier for the order that the check is a part of. You can use the order GUID to GET information about the order from the orders API. For more information, see Getting Order Information.

rel20191115

New Orders API Endpoints for Updating Checks

The orders API includes new endpoints that you can use to update existing checks in orders. You can update existing checks in the following ways:

Add payments to a check - You can add credit card payments to an existing check using the orders API. The /orders/{orderGuid}/checks/{checkGuid}/payments endpoint of the Toast orders API creates new payments in an existing order and check that you specify. For more information, see Adding Payments to a Check.

To add payments to a check, your Toast API client must have the orders-update-payments scope. If you need the orders-update-payments scope, contact the Toast integrations team for assistance. You can determine which scopes your Toast API client has in the return data for an authentication request. For more information, see Getting an Authentication Token.
Update tip amount for a payment - You can update a tip amount for an existing check payment using the orders API. The /orders/{orderGuid}/checks/{checkGuid}/payments/{paymentGuid} endpoint of the Toast orders API replaces the existing tip amount in the payment that you specify. For more information, see Updating Tip Amount for a Payment.

To update tip amounts, your Toast API client must have the orders-update-payments scope. If you need the orders-update-payments scope, contact the Toast integrations team for assistance. You can determine which scopes your Toast API client has in the return data for an authentication request. For more information, see Getting an Authentication Token.
Add discounts to checks - You can add a discount to an existing check or a menu item selection in an existing check using the orders API. The following orders API endpoints add discounts to an existing check.
- /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts adds a discount to a check.
- /orders/{orderGuid}/checks/{checkGuid}/selections/{selectionGuid}/appliedDiscounts adds a discount to a menu item selection.
For more information, see Adding Discounts to Checks.

Partners Webhook Available

The partners webhook is now available for production use. You can use the partners webhook to receive notifications when restaurants give your partner API client integration access to their restaurant information in the Toast POS system. For more information about webhooks in general and the partners webhook, see Using Webhooks and Partners Webhook Type.

The partners webhook is only available for partner API accounts. The information that the partners webhook provides about restaurant access only applies to partner API accounts. For more information about Toast API account types, see Toast API Accounts.

rel20191101

Partners API Reports Restaurant Connection Created and Modified Time Stamps in ISO8601 Format

The partners API now includes isoCreatedDate and isoModifiedDate values in the PartnerAccessExternalRep object. The PartnerAccessExternalRep object provides information about a restaurant that your partner API client account has access to using Toast APIs. For information about partner API accounts and access to restaurants, see Partner API Accounts.

The new values indicate:

isoCreatedDate - the date and time that a restaurant administrator gave your partner API client account access to the restaurant. The date and time are represented in ISO 8601 format.
isoModifiedDate - the most recent date and time that a restaurant administrator altered the configuration of your partner API client account access to the restaurant. The date and time are represented in ISO 8601 format.

The PartnerAccessExternalRep object also includes createdDate and modifiedDate values that provide the same information, in UNIX epoch format. The createdDate and modifiedDate values are not new.

`Toast-Rate-Limit-Limit` and `Toast-Rate-Limit-Remaining` Rate Limiting Header Fields Sunset

The following deprecated rate limiting header fields have been removed from Toast API responses.

Toast-Rate-Limit-Limit
Toast-Rate-Limit-Remaining

For information about Toast API rate limiting and using rate limiting header fields, see Rate Limiting.

rel20191018

Gift Card API Indicates Card Identifier Input Method

The gift card integration API includes a new identifierSource value in the TransactionInformationActivate object to indicate the way that the Toast POS system received a gift card identifier string. The gift card identifier string is the giftCardIdentifier value in the TransactionInformationActivate object.

Values are:

KEYED - A restaurant employee or guest manually entered the identifier string.
SCANNED - A restaurant employee or guest used a barcode scanner or other scanning device to enter the identifier string.
SWIPED - A restaurant employee or guest used a magnetic card strip reader to enter the identifier string.
UNKNOWN - The Toast POS system received the identifier string using a method other than KEYED, SCANNED, or SWIPED, or the method is not known. During normal gift card transaction processing, this value will not occur. The UNKNOWN value is intended to handle unexpected situations and your integration must be prepared to accept it.

Loyalty API Discounts Available in General Ledger Configuration

You can map loyalty integration API discounts to general ledger (GL) codes for your restaurant. Mapping loyalty integration discounts to GL codes includes entries for those discounts in the Toast POS system accounting report. For more information about using a loyalty program integration at a Toast POS system restaurant, see this Toast central article.

rel20191011

New Menus API

The new menus API provides detailed information about all menus configured for a restaurant. The return data from the menus API includes:

A fully-resolved menu structure including menus, menu groups, selections, modifier option groups, modifier options, and other menu components.
Metadata about the menu configuration information that you can use to determine the last time the menu information was updated and whether your integration needs to request the updated menu information.

For more information, see Getting Menu Information from the Menus API. For information about access to the menus API, contact the Toast integrations team.

Menu JSON Data Export Files Deprecated

The menu JSON data export file in the set of daily data export files for Toast restaurants will not be available to new Toast POS system restaurants after 2020-01-20. After 2020-01-20, not all Toast POS system restaurants will have access to menu JSON data export files. The new menus API provides an equivalent, fully-resolved menu structure. You can start using the menus API to get menu information now.

For information about this and all other scheduled Toast API changes, see the Integration Update Schedule.

For more information about using the menus API, see Getting Menu Information from the Menus API. For information about access to the menus API, contact the Toast integrations team.

Orders API Sets Check `openedDate` to Order `openedDate` if `null`

The orders API now sets the openedDate value for a check to the openedDate value of its parent Order object if you do not specify an openedDate in the Check object.

This change primarily affects future orders. If you POST an order for immediate fulfillment, you do not need to set an openedDate value. For future orders, you set the openedDate of the order to the same day and time as the promisedDate. This change applies the openedDate for the future order to the checks in that order.

Orders API No Longer Applies Tax to Service Charges in Tax-Exempt Checks

The orders API no longer applies tax to service charges applied to tax-exempt checks. The orders API prices endpoint includes this pricing behavior change. Previously, a problem with tax-exempt checks incorrectly applied tax amounts for taxed service charges.

Restaurants API No Longer Includes Off-premise Dining Option Offset Times

The following values in the PrepTimes object no longer return information about off-premise (takeout and delivery) dining option availability in a restaurant's configuration:

deliveryTimeAfterOpen
deliveryTimeBeforeClose
takeoutTimeAfterOpen
takeoutTimeBeforeClose

Each of these values is always 0. The off-premise dining option availability schedule information that was previously provided by these restaurants API values is included in upcoming Toast POS system product development.

rel20190927

Authentication Response `scope` Value Includes `orders` String

The scope value in the return data for a successful authentication token request now includes the string orders if your Toast API client uses the orders API. Previously, the scope value did not include the string orders even if your client uses the orders API.

rel20190920

Orders API applicableDiscounts Endpoint Returns Correct Discounts

The /applicableDiscounts endpoint of the orders API will return the correct list of discounts that you can apply to checks in an order on 2019-09-25. Currently, the endpoint returns discounts based on the discount applicability rules that were in place before discount functionality changes that were released on 2019-04-01.

rel20190830

Labor API Rejects PUT Requests for Deleted Shifts

The labor API now rejects PUT requests for deleted shifts. If you attempt to update a deleted shift, the labor API returns an HTTP 400 (bad request) response. Previously, the API updated shifts even if they were deleted.

Labor API Handles Error Conditions More Correctly

The labor API now returns HTTP 4xx error responses instead of 500 server error responses in the following situations:

The labor API returns an HTTP 400 (bad request) response when you send a PUT request to the /employees/{employeeId}/jobs endpoint with a duplicate job ID in the body parameter. Previously the API returned an HTTP 500 (server error) response.
The labor API returns an HTTP 404 (not found) response when you send a request to an endpoint that includes an employee GUID as a path parameter and the employee record does not exist. For example, if you sent a GET request to the /employees/{employeeId} endpoint and the GUID in the {employeeId} parameter is not found, the API returns an HTTP 404 (not found) response. Previously, the API returned an HTTP 500 (server error) response.

rel20190816

/partner/restaurants Endpoint of the User Management Service Removed

The deprecated /usermgmt/v1/partner/restaurants endpoint of the user management API has been removed. You can use the new partners API /partners/v1/restaurants endpoint to get information about the restaurants your integration has access to:

https://[hostname]/partners/v1/restaurants

Service Charges Can Be Calculated Before or After Discounts

On 2019-09-23 restaurants will be able to choose whether fixed percent service charges are calculated before or after discounts.

The configuration API ServiceCharge object now includes a new serviceChargeCalculation value to indicate whether a service charge is calulated before (PRE_DISCOUNT) or after (POST_DISCOUNT) discounts.

The orders API AppliedServiceCharge object now includes a new serviceChargeCalculation object to indicate whether a service charge is calulated before (PRE_DISCOUNT) or after (POST_DISCOUNT) discounts. This value is read only.

The configuration option that controls whether fixed percent services charges are calculated before or after discountsis available in the sandbox environment now. You can test your integration to verify that it is ready to support the new configuration option in the sandbox environment.

New Values Present in Loyalty API JSON

The Redemption object used in loyalty API integrations now includes multiItemDiscountGuid and itemApplication values. These values are intended for future use and are currently always null. These values are expected to include non-null information in the future.

rel20190712

Orders API Only Accepts Positive Tip Amounts

The orders API now validates the tipAmount value in Payment objects. The tipAmount value must be a positive amount or zero. The tipAmount value is the tip that is included with a payment.

Labor API Will Return Success Response When Deleting Resources That Are Already Deleted

On 2019-07-22, the labor API will return a 200 HTTP status code in response to a DELETE request for a shift or employee that has already been deleted. Currently, the labor API returns a 400 HTTP status code in response to an attempt to delete a resource that is already deleted. The labor API will continue to return a 400 status code response if you attempt to delete a resource that does not exist.

Credit Cards API Will Validate Card Zip Codes and CVV

On 2019-07-29, the credit cards API will begin verifying that the zip or postal code in the billing address for a credit card is correct and that the card verification value (CVV) is valid. The API will not authorize payments unless the zip code is correct and CVV is valid.

Changes to Rate Limits

On 2019-08-26, new rate limiting functionality will go into effect in the production environment that controls the number of requests your API client can make. This new functionality will be available for testing in the sandbox environment on 2019-07-22.

With this new functionality, Toast APIs will begin using fixed time slices, instead of sliding time slices, when calculating rate limits. With fixed time slices, each time slice has a fixed start and end time and the number of requests you can make within a time slice is determined by your rate limits. In addition, the Toast APIs now use two different types of rate limit:

Global rate limit: This rate limit is applied to requests made across all Toast APIs collectively. For example, assuming a global rate limit of 20 requests/second, your API client can make a total of 20 requests per second, regardless of which API those requests are sent to. So, sending 15 requests to the orders API and 5 requests to the labor API in the same second is acceptable but sending 20 requests to the orders API and 20 requests to the labor API in the same second is not.
API rate limits: API rate limits are applied to requests made against individual APIs, for example, the orders API or the labor API. Toast APIs have a default API rate limit and custom API rate limits. An API uses its custom API rate limit, if one has been specified for it, or the default API rate limit if no custom rate limit has been defined.

Note: Currently, there are no Toast APIs that use a custom rate limit. This functionality is being put in place to support future API rate limit customization.

Toast APIs track the number of requests a client application has made against each rate limit type. Toast API response headers include a new set of fields that tell you which rate limit type the client is closest to exceeding, how many requests are left, and when requests can be resumed if the client has been rate limited. The existing rate limit header fields will continue to function but they are deprecated and will be removed in a future release.

These rate limiting changes do not alter the overall volume of requests that you can make. The changes are completely backwards compatible if you are currently adhering to existing Toast API rate limits. The rate limits are still 20 requests per second and 10,000 requests per 900 seconds.

For more information on this updated rate limiting functionality, see Rate Limiting in the Toast API Developer's Guide.

Previously, the Toast APIs used sliding time slices when calculating rate limits. To understand the sliding approach, consider this example. A client application is rate limited to 5 requests every ten seconds. For every request this client makes, the Toast POS system looks back ten seconds. If the client has already made 5 requests in those ten seconds, the client is rate limited; if not, the request is allowed to proceed. The ten second time slice is always relative to the time of the current request. So, if a client made a request 12 seconds ago, that request is no longer part of the ten second time slice and does not apply to the rate limit. Using this approach allows a client to regain requests on a rolling basis, however, it makes it much more difficult to know how many requests you have at any given point in time. For this reason, the new rate limiting functionality uses fixed time slices instead.

rel20190614

Labor API Will Reject Employee Names and External Identifiers With Special Characters

On 2019-07-22, the labor API will begin rejecting new or updated restaurant employee names and external identifiers that include special characters. The Employee object values that will reject special characters are firstName, lastName, and externalEmployeeId. Special characters that are not allowed are {}<>$=\;%%.

Restaurants API Will Not Return Archived Restaurants

On 2019-07-22, the /groups/{managementGroupGUID}/restaurants endpoint of the restaurants API will no longer return GUIDs for archived objects. Currently, that endpoint returns Restaurant objects for all restaurants in a management group, including archived restaurants.

rel20190607

Restaurants API No Longer Returns Deleted Services

The restaurants API no longer returns restaurant service information for services that are deleted. Previously, if you deleted a restaurant service, the restaurants API would continue to return information about that service. Examples of services at a restaurant might be brunch, lunch, and dinner. Service information returned by the restaurants API includes the hours that service is provided during specific day schedules.

This change is currently deployed in the sandbox environment for testing. The change will be deployed in the production environment on 2019-06-24.

If a restaurant configured and deleted at least one service, it is possible that your integration is using restaurant service information that will no longer be present in the restaurants API return data when this change is deployed in production. Make sure that restaurant employees verify that services are configured correctly on the Restaurant Hours / Services page of the Toast administration back-end.

rel20190530

The layout and workflow of the My Integrations configuration page for Toast POS system restaurants will change on Thursday, June 6, 2019. The new workflow reduces user confusion and makes it easier for restaurants to find, enable, and configure integrations with other restaurant services.

If your organization provides information about configuring integrations in the Toast POS system to your restaurant customers you might need to update that information. You can experiment with the new functionality on the My Integrations page in the sandbox environment to make sure that you understand what your restaurant customers will experience and to update materials such as screenshots if necessary.

Changes to the My Integrations page include:

Restaurant customers no longer add partner external identifiers, Partner Location ID and Partner Group ID, for your integration service on the Add Partner Integration screen during the workflow to add your integration. Restaurant customers configure partner external identifiers for your service after they add the integration.
The configuration controls for partner external identifiers are on a separate page from the catalog of integration services. The My Integrations page only includes partner external identifiers and other configuration controls for the integration services that a restaurant has enabled. Restaurants can open the catalog of integration services by selecting Add Integrations from the My Integrations page.
All integration services are always available in the same catalog page. Previously integrations were divided into two tabs if a restaurant does not have a Toast Partner Connect subscription. One tab held integrations that require a Toast Partner Connect subscription and the other tab held integrations that do not require a Toast Partner Connect subscription.
For restaurants that do not have a Toast Partner Connect subscription, the catalog tiles for integration services that require that module display a padlock icon. Restaurants that do have a Toast Partner Connect subscription do not see the padlock icon.
If a restaurant has not enabled any integrations, restaurant employees see the Add Integrations page that contains the catalog of integration services when they select My Integrations from the Toast administration back-end. After a restaurant enables at least one integration service, restaurant employees see the My Integrations page that contains the identifiers and other configuration controls for enabled integrations.

rel20190517

Orders API Allows Open-Price Menu Items in `POST` Requests

The orders API now supports open-price menu items in POST requests. To set an open price for a menu item, you include a currency amount in the new openPriceAmount value in the Selection object for an order. The menu item must be configured to use the Open Price pricing strategy. If you do not supply an openPriceAmount value for an open price menu item, the orders API will set the price to 0.00.

If a menu item is configured to use tax-inclusive pricing, the orders API calculates the base price and tax amount based on the open price that you specify. The open-price amount includes both the base price and the inclusive tax amount.

The openPriceAmount value is write-only and is not present in orders API return data.

The configuration API and menu data export files do not indicate whether a menu item uses open pricing. To determine which menu items use open pricing, you (or an employee of the restaurant you are integrating with) check the Pricing Strategy configuration option for the menu item in the Toast administration back-end. The Open Price strategy indicates that the menu item uses open pricing.

Note: Open-price menu items are different from open menu items. Open-price menu items allow restaurant employees or your integration client software to set the price of a pre-configured menu item. Open menu items allow restaurant employees to process item sales that are not on a restaurant's pre-configured menus.

Orders API Returns Seat Numbers for Menu Item Selections

The orders API return data now includes a seatNumber value in the Selection object. The seatNumber value indicates which guest seat at a restaurant table ordered a menu item selection. Restaurant employees can choose the seat number when they add a menu item to a guest check.

A positive integer value indicates the seat number for the menu item.
0 - indicates that the menu item is being shared by multiple guests.
-1 - indicates that the restaurant employee did not select a seat for the menu item.

API Rate Limiting Changes

The way that Toast APIs limit the rate of requests will change in an upcoming release. The new rate limit measurement is based on a fixed period of time. Fixed time periods begin at specific times during a day, such as 00:00, 00:15, and 00:30.

Currently, rate limiting is based on a sliding period of time. For more information, see Rate Limiting.

The number of requests that you can make is not changing. Your Toast API client can send up to 20 requests per second and 10,000 requests per 900 seconds (15 minutes), enforced at the location level.

The new rate limiting behavior will be available for testing in the sandbox environment in an upcoming release. The date of that release will be announced at a later time. Documentation describing the new rate limiting behavior will be available at that time. 90 days after the testing period begins, the new rate limiting behavior will apply to all Toast API clients in the production environment.

rel20190426

Orders API Sets Restaurant Employee Server in POST Requests

You can specify the server (restaurant employee responsible for an order) when you POST an order in the orders API. Specify the Toast POS GUID or external identifier of the employee in the server value of the Order object. The server value is an ExternalReference object as shown in the following example.

"server": {"guid": "dc9b7cd6-4389-4a6d-83c3-2fde7f033567"},

You can get the GUID and external identifier of an employee from the /employees endpoint of the labor API.

The orders API validates that the employee you specify in the server value exists and that the employee has access to the current restaurant. The API will allow you to specify a deleted employee in the server value.

New `isCashOut` Value in the Gift Card Integration API

The TransactionInformationRedeem object in the gift card integration API now includes an isCashOut value. The new value will be used to support future gift card functionality.

rel20190412

Orders API Will Use Updated Tax Calculation Algorithms

On 2019-06-15, the orders API will begin using updated tax calculation algorithms in the production environment. These algorithm changes affect the way the orders API calculates tax amounts for:

Changes to tax calculation algorithms should not require changes in your integration software. Information about the way the Toast POS system calculates taxes and other aspects of check prices is not intended to allow integration partners to independently calculate check prices. The /prices endpoint is the only reliable and supported way to determine the payment amount for a check. If you POST an order with an inaccurate payment amount, the Toast POS system will require restaurant employees to handle the underpayment or overpayment during order fulfillment. For more information, see Getting Check Prices.

The updated tax calculation algorithms will go into effect immediately in the sandbox environment for testing. You can verify that your orders API integration is compatible with the new algorithms before they go into effect in the production environment on 2019-06-15.

Orders API Sets Revenue Center in POST Requests

You can specify the revenue center when you POST an order in the orders API. Specify the Toast POS GUID of the revenue center in the revenueCenter value of the Order object. You can get the GUID of a revenue center from the /revenueCenters endpoint of the configuration API. A revenue center is a division or section of a restaurant that you fulfill an order in. You can analyze financial reporting information using revenue centers.

The revenue center that you specify in a POST request to the orders API will always set the revenue center for the order. Orders API orders are not affected by the revenue centers that you configure for a restaurant. If you do not specify a revenue center when you POST an order, the revenue center for the order is null.

New Partners API and Restaurant Access Endpoint

The new Toast partners API (base URL /partners/v1) includes functionality intended for restaurant services that are integrated with the Toast POS system. The partners API includes one endpoint, /restaurants, that returns a list of restaurants that a partner organization has access to. For more information about partner organization API client accounts, see Partner API Accounts. For more information about partners' restaurant access, see Getting the Restaurants You Have Access To.

The existing user management API currently includes a /partner/restaurants endpoint that provides the same information about partners' access to restaurants. The existing /partner/restaurants in the user management API is deprecated and will be replaced by the new endpoint in the partners API. You can use the new partners API /restaurants endpoint in the same way that you use the endpoint in the user management API. The existing /partner/restaurants is deprecated and will be removed on 2019-07-16. Make sure you update the URL for your integration before that date.

https://[hostname]/partners/v1/restaurants - new, supported endpoint for getting restaurant access information.
https://[hostname]/usermgmt/v1/partner/restaurants - deprecated, this endpoint will not be available after 2019-07-16.

You can use the partners API /restaurants endpoint to determine when new Toast POS restaurants give your organization access and also to determine when restaurants revoke that access. Make sure that you refresh the list of restaurants that you have access to regularly. In particular, determining when a restaurant has revoked access helps you avoid sending unecessary API requests for that restaurant.

rel20190329

Clarified Error Messages in the Orders API

The error codes returned by the orders API have been updated to provide better categorization of the problems that occur in an API requests. You receive error codes in the code value of an ErrorMessage object in the response data for an unsuccessful API request. Many of the updated error messages are for problems that can occur during discount validation.

Labor API Time Entry Requests By Modified Date Include Time Entries Modified By An Internal Data Update

Time entries from approximately 2019-01-01 to approximately 2019-02-13 have been updated to support new Toast POS system functionality. The update adds internal data to the records for the time entries. The change to the internal data is a modification that will cause a time entry to be included by a GET request to the /timeEntries endpoint of the labor API that uses the modifiedStartDate and modifiedEndDate query parameters.

If the time period you select using the modifiedStartDate and modifiedEndDate query parameters includes the date that the internal data for time entries was updated, your response data will include all time entries from approximately 2019-01-01 to approximately 2019-02-13.

The date that the internal data update occurs is different for each Toast POS system restaurant. Beginning on 2019-03-14, time entries for a small number of restaurants were updated. After this initial trial, the data updates have been paused until 2019-04-10. Beginning on 2019-04-10, time entries for all remaining restaurants will be updated.

If you have questions about the effect of this data update on /timeEntries endpoint requests using the modifiedStartDate and modifiedEndDate query parameters, contact the Toast technical partnership team.

rel20190322

New Discount Configuration Values

The configuration API includes three new values in the Discount object:

nonExclusive - Indicates whether you can apply the discount with other discounts. This value is always false for item and combo discounts.
itemPickingPriority - Indicates which menu item selections are discounted when you apply a BOGO discount. An item that is discounted by a BOGO discount is a "get" item. Values are:
- FIRST - the BOGO discount applies to the first matching item selection in the check or the discount is not a BOGO discount. The itemPickingPriority is always FIRST for discounts that are not BOGO discounts.
- LEAST_EXPENSIVE - the BOGO discount applies to the least expensive matching item selection in the check.
- MOST_EXPENSIVE - the BOGO discount applies to the most expensive matching item selection in the check.
fixedTotal - The total price of items discounted by a combo discount. This value is null for discounts that are not combo discounts.

For more information about working with discounts in the Toast POS system, see Discounts in the Toast Administrator's Guide.

Menu Data Export Files Include `orderableOnline` Values for Modifier Options

The JSON menu data export file now includes an orderableOnline value for modifier options. This value indicates whether restaurant employees have chosen to offer the modifier option for orders in the orders API. The value does not prevent your orders API integration from including a modifier option in an order. The orderableOnline value was already included in the JSON objects for menus, menu groups, and menu items.

Menu Data Export Files Will Correct Configuration Data for Modifier Options

The JSON menu data export files will include the correct price value for modifier options that use menu-specific prices on 2019-04-03. Currently, a problem causes the price value to report the base price for modifier options that have menu-specific prices and that occur within a menu that applies a menu-specific price. The new behavior for menu data export files will take effect on 2019-04-03.

rel20190301

Orders API Accepts Masked Loyalty Account ID String

The AppliedLoyaltyInfo object includes a new maskedLoyaltyIdentifier value that holds a representation of the identifier of the loyalty program account that can be displayed securely. For example: ************1234. The Toast POS displays this string to restaurant employees and guests. You can include this optional value when you POST an order and it will be available in response data when you GET the order. If you do not provide a maskedLoyaltyIdentifier when you POST an order, this value is null in response data and the Toast POS displays a masked representation of the loyaltyIdentifier (all characters except the last four are hidden).

Orders API Does Not Enforce Minimum Modifier Selections For Optional Modifiers

The orders API no longer enforces minimum modifier selections for optional modifiers. Previously, if you configured a required modifier with a minimum number of selections, and then made the modifier optional or optional force show, the orders API would continue to enforce the minimum selection number. This problem has been corrected.

rel20190221

Orders API Includes More Information in Discount Error Messages

The orders API now includes more information about problems that occur while applying discounts. For example, some error messages now include discount names in addition to the discount GUID and some error messages include more information about correcting problems.

rel20190215

New Discount Behavior in the Orders API

On 2019-04-01, the orders API will be adding support for, and enforcing the requirements of, multiple discount features that are already supported and enforced on Toast POS devices. Make sure that you understand the way discount behavior will change and update your integration client software before that date.

The following lists describes the ways that the orders API will enforce discount behavior differently.

New behavior

Support for Allow with other discounts
Support for Multiple Check Level Discounts
Support for Open Fixed Value Item Level Discounts
Combo Applies to Least Expensive Modifiers
Support for Discounts Date/Time Availability
Support for Menus, Menu Groups & Menu Items Configured on Check-Level Discounts

Corrections to orders API behavior

Support for Min/Max Check Configuration Discounts
Fix for Discounted Modifiers on Combos
BOGO BUY Items are No Longer Eligible for Additional Discounts
Combo discounts apply to the correct Number of Like Items

For detailed information about the changes to discount behavior in the orders API, see Discount Behavior Changes in 2019. For general information about discounts in the Toast POS system, see Discounts.

You can download a comma-separated value (CSV) spreadsheet of discount behavior changes to use as an integration update checklist.

New GL Code for American Express Optblue Credit Card Payments

The Toast POS system includes a new general ledger (GL) code to report credit card fees for American Express credit card payments that are processed using American Express Optblue. The new GL code is named Amex Optblue Fees. You can map the Amex Optblue Fees GL code to one (or none) of your GL categories to control the way American Express credit card sales appear in the Accounting report for your restaurant. The information in the accounting report is available in the accounting data export file.

If you use information in the accounting report data export file, make sure that you understand the way that restaurants have configured the new GL code.

rel20190125

New Tax Configuration Options Enabled at All Production Restaurants

The Toast POS system includes new tax rate configuration options that are currently available for use at many restaurants in the production environment. The new tax options will be enabled for use at all restaurants in the production environment on 2019-01-30.

The new configuration options allow restaurants to:

Use tax tables. You can get information about the tax table for a tax rate from the configuration API.
Choose new rounding options for percent tax rates. You can get information about the rounding option for a tax rate from the roundingType value of the TaxRate object in the configuration API.
Configure conditional tax rates that override the percent amount of a tax rate in specific situation. Currently, the only conditional tax rate applies to menu items that are fulfilled in a take out dining option. You can get information about the conditional rates for a tax rate from the configuration API.

You can determine which tax rates are configured for a restaurant by using the configuration API. For information about the new tax configuration options, see documentation about taxes in the Toast Administrator's Guide.

Credit Cards API Enforces Required Values and ISO 8601 Date/Time Format

Beginning on 2019-04-01, the credit cards API will enforce additional required values in credit card authorization requests. The API will also validate date and time formats, which must be ISO 8601. For example, 2019-01-25 is supported and 2019-1-25 is not a valid ISO 8601 date.

The API will enforce the following required values in an authorization request:

partnerServiceInfo - The partnerServiceInfo value in a PaymentRequestMetadata object holds information about the client software that transmitted the credit card information for an authorization request. The PartnerServiceInfo information must include an instanceId value to identify the client software system.
originIPAddr - The originIPAddr value in a PaymentRequestMetadata object holds the IP address of the client software that transmitted the credit card information for an authorization request.
keyId - The keyId value in a PaymentAuthorization holds the identifier of the encryption key and algorithm used to encrypt the credit card data for an authorization request. If you do not know the identifier of your encryption key, contact the Toast technical partnership team.

The partnerServiceInfo, originIPAddr, and keyId values, and the ISO 8601 date and time format, are currently described as required in the Toast API reference documentation. Make sure your client implementation includes those values and submits date/time values in ISO 8601 format before 2019-04-01.

rel20190118

New Pricing Information for Menu Option Groups in Menu Export Files

The JSON menu data export file includes new values to provide information about pricing for menu option groups. For detailed information about the new pricing values, see Menu Data Export Values in the Toast API Developer's Guide. The following list summarizes the new values:

pricingMode - Indicates how the options in the menu option group affect the price of the menu items they are applied to. Values are:
- ADJUSTS_PRICE - Choosing an option from the menu option group affects the price of the menu item it applies to. The amount of the adjustment depends on the price of the option applied.
- FIXED_PRICE - Choosing an item from the menu option group affects the price of the item it applies to. The amount of the adjustment is set at the menu option group level and applies to all options in the group. Note that this does not necessarily mean that all options in the group have an identical price. It means that all options in the group are treated the same way with respect to pricing. For example, if the menu option group uses sequence pricing, and the first two options are free while the third is $1, the specific modifier that costs $1 is arbitrary. Fixed refers to the fact that the pricing is fixed at the modifier group level, not that the price of each option in the group is constant.
- INCLUDED - Choosing an option from the menu option group does not affect the price of the menu item it applies to (the price of the option is included in the price of the menu item it applies to).
pricingStrategy - Indicates the way prices are set for options in the menu option group. Values are:
- NONE - Indicates that no pricing strategy is defined for this menu option group. pricingStrategy is set to NONE if the pricingMode is set to ADJUSTS_PRICE (prices are set on individual items in the menu option group, not on the menu option group itself, so there is no pricing strategy for the menu option group as a whole) or INCLUDED (no additional cost is charged for the options in the menu option group).
- BASE_PRICE - The pricing strategy for the menu option group is a constant price that does not change based on other conditions (such as size or sequence of ordering). For example, all of the items in the menu option group cost $1 at all times.
- SEQUENCE_PRICE - The order in which options are specified determines the cost of each option, for example, the first option costs $1.00, the second costs $1.50, and the third costs $1.75.
- UNSUPPORTED_STRATEGY - The pricing strategy for the menu option group is one that is supported internally in the Toast POS system but is not supported by the orders API.
pricingStrategyRules - A PricingStrategyRules object that contains the pricing rules for the chosen pricingStrategy. If pricingStrategy is NONE or UNSUPPORTED_STRATEGY, this value is set to the string NONE.
defaultOptionsChargePrice - Indicates whether the prices associated with the menu option group's default options are added to the cost of the menu items they modify. Values are:
- NO - The option price is ignored. No change is made to the cost of the menu item.
- YES - The option price is added to the cost of the menu item.
defaultOptionsSubstitutionPricing - Indicates whether substitution pricing is enabled for the menu options group. Values are:
- NO - Substitution pricing is not enabled. Removing a default option from a menu item has no impact on the price of the menu item.
- YES - Substitution pricing is enabled. Substitution pricing allows a guest to remove one or more default options from a menu item and apply the value of those options toward the purchase of one or more different options. For example, a guest orders a salad that comes with chicken by default but asks to substitute salmon for the chicken. The price of the chicken option is $7. The price of the salmon option is $9. In this case, the Toast POS system calculates the difference and charges the substitution price of $2 for the salmon (not the regular price of $9).
  
  There are two scenarios that can occur with substitution pricing:
  1. If the substitution options cost the same as or less than the default options, then no price adjustments occur. The menu item costs the same as it does with the default options.
  2. If the substitution options cost more than the default options, then the Toast POS system calculates the difference in price and reprices the substitution options accordingly. For example, if you remove a default option that costs $10 and replace it with two options that cost $8 and $7, then the cost of the replacement options is $5 ($8 + $7 - $10 = $5).

The values in a PricingStategyRules object are:

basePrice - Used when the pricingStrategy is set to BASE_PRICE. Defines a constant price for all of the options in the menu options group.
numberOfLevels - Used when the pricingStrategy is set to SEQUENCE_PRICE. Defines the number of levels for the sequence price.
sequencePrices - Sets the price for each level defined in the numberOfLevels value.

rel20190104

Dining Option Value for Menu Item Selections

The orders API now includes a diningOption JSON value in the Selection object for menu item selections in orders. The diningOption value includes the GUID of the dining option used to fulfill the menu item selection. For example, the dining option for a menu item selection might be dine-in or takeout. Restaurant administrators configure the specific dining options that their restaurants provide.

When restaurant employees create orders using a Toast POS device, they can select a dining option for a menu item that is different from the dining option for the order. The new diningOption value in the Selection object indicates the dining option for individual menu items. If the dining option for a menu item selection is the same as the dining option for the order, the diningOption value for the Selection is the same as the diningOption of the Order. The Selection object always includes a diningOption value.

The diningOption value for a menu item selection is present in return data only. You cannot specify a dining option for a menu item selection when you POST a new order using the orders API.

rel20181226

New Validation of Credit Card Information

Beginning on 2019-01-31, the credit cards API will perform additional validation of encrypted credit card information for payment authorization.

The API will validate the length of ZIP/postal codes. The API requires that ZIP/postal codes have either 5 or 9 digits, with no hyphens.
The API will validate credit card numbers using an ISO standard algorithm commonly known as a "Luhn algorithm" validation.

The credit cards API already validates credit card expiration dates and card verification values (CVV).

Change to Credit Cards Response for Invalid Card Information

Beginning on 2019-01-31, the credit cards API will return an HTTP 400 Bad Request response to credit card payment authorization requests that include invalid credit card information. Previously the Toast credit cards API returned an HTTP 200 OK response and included a DENIED paymentState in the PaymentStatus object if a credit card provider rejected invalid credit card information. Make sure that your integration submits valid credit card information when you submit payment authorization requests and that it can handle the upcoming HTTP 400 response.

The following example shows the JSON response to an authorization request that includes invalid credit card information.

{
  "status": 400,
  "code": 0,
  "message": "Invalid card data",
  "messageKey": null,
  "fieldName": null,
  "link": null,
  "requestId": null,
  "developerMessage": "Invalid card data",
  "errors": [],
  "canRetry": null
}

rel20181214

The orders API now includes an updated version of an internal software component. The updated component improves performance and reliability. The update will not change the interface or behavior of the orders API.

rel20181207

Tip Withholding Rate Available in the Configuration API

The configuration API includes a new tipWithholding endpoint that you can use to get information about the tip withholding percentage configured for a restaurant. Tip withholding is the percentage of employees' tips that is kept by a restaurant to cover credit card processing fees. Tip withholding applies to:

Credit card tips
Service charges that are paid to employees as a gratuity

New Tax Rounding Behavior at All Production Restaurants

The updated tax rounding behavior described in a release note from 2018-06-01 will become the default rounding behavior for all restaurants in the production environment when version 2.29 of the Toast POS system app becomes required. Version 2.29 is expected to become required before 2018-12-14.

rel20181116

Sales Totals Included in Time Entries

The TimeEntry object in the labor API now includes a nonCashSales value and a cashSales value. The new values indicate the total sales amounts for all checks in the orders assigned to the restaurant employee.

nonCashSales - includes the total non-cash sales in the orders opened by the employee during the time entry period. For example, nonCashSales includes credit card payments, gift card payments, and payments using options that you configure in the Other Payment Options screen of the Toast adminstration back-end.
cashSales - includes the total cash sales in the orders opened by the employee during the time entry period.

The sales totals in the nonCashSales and cashSales values include tax amounts.

The sales totals in the nonCashSales and cashSales values do not include tip or gratuity amounts.

If the outDate value for the time entry is null (the time entry period is not complete), the sales totals are 0. If the outDate value for the time entry is set, the sales totals are final and will not change. If you make changes to an order after the time entry is complete, the sales totals for the time entry do not change.

You can transfer a Toast POS system order from one restaurant employee to another. The sales totals in the nonCashSales and cashSales values are based on the sales added while the order is assigned an employee. For example:

Employee X adds $20.00 of cash sales to an order.
Employee X's shift ends and the time entry for the shift is complete.
A manager transfers the order to Employee Y.
Employee Y adds $40.00 of cash sales to the order.
Employee Y's shift ends and the time entry for the shift is complete.

In this example:

The cashSales value for employee X's time entry is $20.00.
The cashSales value for employee Y's time entry is $40.00.

rel20181109

The restaurants API now accurately reports the delivery order minimum charge for a restaurant. Previously, the minimum value of the Delivery object reported an inaccurate, $5.00, minimum charge for delivery orders.

rel20181102

Tracking and Acknowledging Employee Breaks

The labor and configuration APIs include new features for tracking and acknowledging employee break periods. For more information about Toast POS system functionality for tracking missed breaks and acknowledging breaks, see the Toast Administrator's Guide.

The following sections describe the new employee break API features: * New Break Information in Time Entries * New Query Parameter for the timeEntries Endpoint in the Labor API * New breakTypes Endpoints in the Configuration API

New Break Information in Time Entries

The TimeEntryBreak object in the labor API includes new values that provide information about whether employees missed break periods during their shifts and whether employees were asked to take break periods.

The new values in the TimeEntryBreak object are:

breakType - the Toast POS system GUID of the type of employee break period. You configure types of employee break periods for your restaurant.
missed - A Boolean value that indicates whether the employee took the break. If the value is true, the employee did not take the break. If the value is false, the employee did take the break.
auditResponse - A Boolean value that indicates whether the employee was asked to take the break. If the value is true, the employee was asked to take the break. If the value is false, the employee was not asked to take the break. If the value is null, the break type is not configured to use break acknowledgement or the employee did not respond to the break acknowledgement prompt on the Toast POS device.

New Query Parameter for the `timeEntries` Endpoint in the Labor API

The timeEntries endpoint of the labor API now accepts the includeMissedBreaks query parameter. If you set the value of includeMissedBreaks to true, the timeEntries endpoint will return TimeEntryBreak objects for scheduled break periods even if an employee did not take them. The includeMissedBreaks parameter is optional. If you do not include the parameter, the endpoint returns only breaks that were taken, not breaks that were missed.

New `breakTypes` Endpoints in the Configuration API

The configuration API now includes a breakTypes endpoint that returns information about the types of employee break period that you have configured for your restaurant. You can use the return information from the breakTypes endpoint to get the Toast POS system GUIDs for the break types you configure. New values in the TimeEntryBreak object refer to break types using the GUIDs.

The API also includes a breakTypes/{guid} endpoint that returns information about a specific break type that you identify using its Toast POS GUID.

`undoes` Value in `CashEntry` Object

The CashEntry object in the cash management API now contains an undoes value. If a cash entry reverses a previous cash entry, the undoes value includes the Toast POS system GUID of that previous cash entry. If a cash entry does not reverse a previous cash entry, the undoes value is null.

Business Date for Time Entries After Midnight Corrected

Time entries that started after midnight but before the restaurant's closeout hour now include the correct business date in the businessDate value. Previously, the businessDate value included the calendar date for time entries that started after midnight but before the business day cutoff hour. Time entries that start during that period are considered part of the business day that corresponds to the previous calendar date.

rel20181026

Employee Information for Cash Entries and Deposits in Cash Management API

The CashEntry and Deposit objects in the cash management API now include information about the restaurant employees who performed cash management actions.

The CashEntry object returned by the /entries endpoint includes new employee1 and employee2 values. These values provide the identifiers of the restaurant employees who initiated and approved a cash entry transaction. The employee who initiated or approved a transaction is indicated by the employee1 and employee2 values differently depending on the cash entry type. Not all cash entry types include employee1 and employee2 references. For information about the employees indicated by the employee1 and employee2 values for specific cash entry types, see the cash entry API reference.

The Deposit object returned by the /deposits endpoint now includes a new employee value. The employee value provides the identifier of the employee who performed the deposit transaction.

rel20181019

Orders API Enforces `minSelections`

The orders API now enforces the minSelections configuration for MenuOptionGroups. The minSelections configuration indicates the minimum number of selections that you must make from the modifier group. For example, if a menu item is a package of four beverages, a "flavor" modifier group might have a minSelections value of 4 to ensure that guests make a flavor selection for each beverage.

This orders API change will not have a functional effect in the production environment until the configuration controls that allow restaurants to use the minSelections for modifier groups are enabled in the production environment, which is currently planned for 2018-11-12. Before the planned date for enabling minimum selections in the production environment, make sure you configure minSelections for a modifier group in a test restaurant in the sandbox environment and verify that your orders API implementation includes the required number of modifier selections.

For a list of upcoming Toast API changes that might require implementation changes, see the Integration Update Schedule.

Credit Cards API Will Require `willSaveCard` and `cardNumberOrigin` Values

The credit cards API now includes a willSaveCard value. This value and the existing cardNumberOrigin value are used for reporting information about stored credit card numbers to credit card provider networks. The credit cards API will require these values in the production environment on 2018-11-30. Both values are optional in the production environment now. In an upcoming release before 2018-11-30, the credit cards API will require willSaveCard and cardNumberOrigin in the sandbox environment for integration testing.

Note: An earlier API release note described default values for the upcoming willSaveCard and cardNumberOrigin values. The current version of the credit cards API does not assign default values to willSaveCard and cardNumberOrigin.

For a list of upcoming Toast API changes that might require implementation changes, see the Integration Update Schedule.

The willSaveCard value indicates whether or not organizations store restaurant guests' credit card information for future use. Toast will report information about stored credit card information to some credit card providers. This "card on file" or "stored credentials" reporting is a new requirement from some credit card provider networks. These networks may impose fees for non-compliance with "card on file" reporting requirements.

The values of the new willSaveCard value are true and false.

true indicates that your organization will store credit card information used in a credit card authorization.
false indicates that your organization is not storing the credit card information used in a credit card authorization.

The existing cardNumberOrigin value is also used for "card on file" reporting. If your organization is using stored credit card information for a credit card authorization, you must set the value of cardNumberOrigin to PARTNER_VAULT. The default value for cardNumberOrigin is END_USER.

Integration partners are responsible for any and all fees incurred, and must comply with all applicable law and rules relevant to, "Card-on-File" consent, storage, use and reporting requirements in accordance with card brand regulations and the integration partner agreement.

Credit Cards API Returns an HTTP 400 Response For Invalid PUT Data

The credit cards API now returns an HTTP 400 response if you include invalid JSON message body data in a PUT request. Previously, the credit cards API returned an HTTP 500 response for invalid message body data.

rel20181005

The orders API now supports POSTing an order with the identifier of a specific restaurant table and no menu item selections. You can include restaurant guest information in the Check object. For information about creating orders at a restaurant table, see Creating an Order at a Restaurant Table.

rel20180928

The orders API includes a new mcaRepaymentAmount value in the Payment object that indicates the currency amount that is withheld from a restaurant guest credit card payment as repayment for a Toast Capital merchant cash advance (MCA). The MCA repayment amount is set at the time the payment is captured, which is typically hours after the actual restaurant guest payment. Until the mcaRepaymentAmount is set, this value is null. The mcaRepaymentAmount might be updated when the payment is settled, which is typically one or more days after the actual guest payment. The mcaRepaymentAmount is updated when a payment is settled if the payment amount is different from the original amount captured. Response only.

rel20180914

The configuration API includes new values to specify the units of measure used for weight-based pricing. The unitOfMeasure value in the Menu, MenuGroup, and MenuItem objects holds the following enumerated values:

NONE - items are not priced by weight
LB - pounds
OZ - ounces
KG - kilograms
G - grams

The MenuGroup and MenuItem objects also include a new inheritUnitOfMeasure value that indicates whether they inherit the weight-based pricing units from their parent menu groups or menus. The Boolean values of inheritUnitOfMeasure are:

true - the menu group or menu item uses the unit of measure that is configured for (or inherited by) its parent menu group or menu.
false - the menu group or menu item has its own unit of measure configuration.

The configuration option for setting the unit of measure for a menu item is not enabled in the production environment. Currently, no restaurants can set the unit of measure for a menu item. This configuration option will be enabled in the production environment in an upcoming release.

rel20180831

Configuration Value for Minimum Selections in Modifier Group

The configuration API includes a new minSelections value in the MenuOptionGroup that indicates the minimum number of selections that you must make from the modifier group. For example, if a menu item is a package of four beverages, a "flavor" modifier group might have a minSelections value of 4 to ensure that guests make a flavor selection for each beverage.

The Toast administration back-end configuration option for minimum selections in modifier groups is not enabled in the production environment. Currently, no restaurants can set a minimum number of selections for a modifier group, except by making the modifier group required (existing functionality). This configuration option will be enabled in the production environment in an upcoming release.

The configuration option for minimum selections in modifier groups is enabled in the sandbox environment. You can configure a modifier group with a minimum number of selections in a test restaurant and ensure that your integration implementation supports working with modifier groups that have minimum selections. An upcoming release of the orders API will require that new orders include the minimum number of selections for a modifier group.

Unit of Measure Value for Menu Item Selections

The orders API includes a new unitOfMeasure value in the Selection object. The unitOfMeasure value indicates the type of weight measurement used for an item. For example, a salad bar menu item might be sold by ounces or grams. The enumerated values for unitOfMeasure are NONE (the item is not measured by weight), LB (pounds), OZ (ounces), KG (kilograms), and G (grams).

The unitOfMeasure value is used in response data only. If you include the value in a POST request, the orders API will ignore it.

Modifiers With Missing Item Information Handled With 400 Response

If you include a modifier for a selection in a check and do not include the item value to provide an identifier for the modifier item, the orders API will now return a 400 error. Previously, the orders API returned a 500 error because of a software failure.

rel20180824

New tax configuration options

The Toast POS system now includes new tax rate configuration options for restaurants. The new configuration options allow restaurants to use tax tables and to choose new rounding options for percent tax rates.

The new tax configuration options are not enabled in the production environment of the Toast POS system. The new tax options are enabled in the sandbox environment for testing now and will become available for restaurants in the production environment starting on 2018-10-03.

The new tax configuration options are not enabled at all restaurants in the sandbox environment. To enable the new tax options in specific restaurants for testing, contact the Toast technical partnership team.

New reporting requirements for stored credit card information

Note on 2018-10-19: This release note described default values for the upcoming willSaveCard and cardNumberOrigin values. The current version of the credit cards API does not assign default values to willSaveCard and cardNumberOrigin. For more information, see the API release note for 2018-10-19.

The credit cards API will include a new willSaveCard value in the PaymentAuthorization object in an upcoming release. This value indicates whether the organization that received credit card information from a restaurant guest is storing that information for future use. In addition to the new value, Toast will begin reporting information about stored credit card information to some credit card providers. This "card on file" or "stored credentials" reporting is a new requirement from some credit card provider networks. These networks may impose fees for non-compliance with "card on file" reporting requirements.

In an upcoming release, the credit cards API will include the new willSaveCard value, and assign it a default value of false. False indicates that your organization is not storing the credit card information used in a credit card authorization. If your organization will store credit card information, you must include the willSaveCard value and set it to true.

The existing cardNumberOrigin value will also be used for "card on file" reporting. If your organization is using stored credit card information for a credit card authorization, you must set the value of cardNumberOrigin to PARTNER_VAULT. The default value for cardNumberOrigin is END_USER.

Improved error handling in the applicableDiscounts endpoint

The orders API applicableDiscounts endpoint is now more resilient to errors it encounters when evaluating whether discounts apply to an order. Previously, the applicableDiscounts endpoint returned a 500 HTTP status error when it encountered a problem while evaluating discounts.

For example, in rare situations, discounts are configured in a way that makes them unusable at a restaurant. When the applicableDiscounts endpoint evaluated whether a misconfigured discount applies to an order, it would cause a software error. The endpoint now ignores misconfigured discounts and will return valid discounts that apply to the order that you submit.

rel20180817

The orders API now requires that item and modifier quantity values are equal. For example, if you attempt to create a check that includes a menu item with "quantity": 1 and that item includes a modifier with "quantity": 2 the orders API will return an error. To add the same modifier to an item more than one time you can include the modifier menu item object more than once in the "modifiers": [] array for the menu item selection. You can set the quantity for a modifier to any amount that matches the quantity of the menu item selection it applies to. For example, you can create a check that includes a menu item with "quantity": 5 and apply a modifier to that item with "quantity": 5. Each of the five items will include the modifier you specify.

rel20180810

The orders API includes a new approvalStatus value in the Orders object. The approvalStatus value is in response data only. It indicates the current state of the order in the restaurant order fulfillment process. For example, the approvalStatus can indicate that an order is waiting for a restaurant employee to approve it or that the order is in a restaurant kitchen being fulfilled. The approvalStatus value can be:

NEEDS_APPROVAL - the order has been created but will not be fulfilled by the restaurant until an employee approves it.
APPROVED - the order is being fulfilled by the restaurant or it has been fulfilled in the past. Orders remain in this state indefinitely after they are fulfilled.
FUTURE - the order is expected to be fulfilled by the restaurant at a future date and time. Restaurant employees will receive information about the order at the date and time that it is ready to be fulfilled.
NOT_APPROVED - restaurant employees received information about the order and did not approve it for fulfillment. An order enters this state after a period of time passes without a restaurant employee approving it.

rel20180731

The orders API now applies fixed amount check-level discounts before it applies percentage check-level discounts for restaurants that use version 2.27 of the Toast POS mobile app. Applying check discounts in this order decreases the chance that a combination of discounts will reduce the price of a check to zero. Previously, the orders API applied check-level discounts in the reverse order (percent before fixed amount). This change does not affect existing, historical check pricing or restaurants that use a version of the Toast POS mobile app earlier than 2.27. This change affects the sandbox environment immediately and will affect the production environment on 2018-08-06.

rel20180713

The orders API now returns an HTTP 400 response (bad request) for a "Discount not applicable" error on the prices endpoint. Previously, an HTTP 500 response was returned.

rel20180706

The orders API now includes two new values in the Order, Check, and Payment objects. These values are:

createdDevice - the identifier of the Toast POS device that created the order, check, or payment. The value is null if the order, check, or payment was not created using a Toast POS device.
lastModifiedDevice - the identifier of the Toast POS device that most recently modified the order, check, or payment. The value is null if the order, check, or payment was not most recently modified using a Toast POS device. If the order, check, or payment is modified but the modification is not made using a Toast POS device, this value does not change.

rel20180629

The configuration API now includes a calories value in the MenuItem object. The calories value indicates the number of Calories (units of food energy) that you configure for a menu item in the Toast administration back-end.

rel20180622

The orders API includes a new taxInclusion value in the Selection object for menu item selections in a check. The taxInclusion value indicates whether the menu item price includes one or more tax amounts. The enumerated values of the taxInclusion value are:

INCLUDED - the menu item price includes one or more tax amounts.
NOT_INCLUDED - the menu item price does not include any tax amounts.
INHERITED - the menu item is a modifier for another menu item selection in the check. The taxInclusion value of the parent menu item selection applies to the modifier. If a menu item selection that is not a modifier inherits tax inclusion behavior from a menu or menu group, the taxInclusion value will be either INCLUDED or NOT_INCLUDED.

rel20180615

The labor API now supports updating restaurant employee passcodes. You can include a new passcode value in the JSON object that you send in the message body for a PATCH request to the /employees/{employeeId} endpoint of the labor API. To update an employee passcode you must also include a currentPasscode value containing the current Toast POS passcode for the employee.

rel20180608

The orders API now includes a nonTaxDiscountAmount value in the AppliedDiscount object. The nonTaxDiscountAmount value is the amount that a discount reduces a menu item price, excluding any discount amount applied to taxes. In most cases, this is the same as the full discount amount. For menu items that include tax, the nonTaxDiscountAmount value makes it easier to determine the distribution of the discount amount between the tax and the menu item price.

rel20180601

The JSON menu data export file now includes a calories value for menu items and modifiers. This value holds the caloric content of the menu item or modifier that you configure in the Toast administration back-end.

The orders API includes a new pricingFeatures value in the Order object and a new tax rounding behavior for fractional cents. The pricingFeatures value indicates the rounding behavior that the orders API used for historical orders. Orders created before and after this tax rounding change may have slight differences in pricing.

The new pricingFeatures value and the new tax rounding behavior became available for testing in the sandbox environment on 2018-04-13. The new tax rounding behavior will be the default in all environments, including production, starting on 2018-06-11. The change will be deployed incrementally to restaurants over a period of days after that date.

If you do not include the pricingFeatures value for an order, the orders API will use the new tax rounding behavior. See more information about the new tax rounding behavior.
If you include the string TAXESV2 in the string array value for pricingFeatures, the orders API will also use the new tax rounding behavior.
When you GET an order, the pricingFeatures string array will include TAXESV2 for orders that used the new tax rounding behavior. If the pricingFeatures string array does not include TAXESV2, the order used the previous tax rounding behavior.

rel20180511

The timeEntries endpoint of the labor API includes a new, optional, set of query parameters that you can use to get information about time entries that were modified during a period of time. You can include the modifiedStartDate and modifiedEndDate query parameters with a GET request to set the period of time, up to one month.

rel20180413

The credit cards API has improved data input validation for expiration dates and card verification values (CVV). For example, the credit cards API will verify that the length of a CVV string matches the length of CVVs for the credit card issuer. In most cases, credit cards API clients validate credit card information before sending it to the API and this change will not affect credit card denial rates. The credit cards API returns an HTTP 400 response (bad request) when it receives invalid credit card information. This change will affect the production environment on 2018-04-16.

The orders API includes a new pricingFeatures value in the Order object and a new tax rounding behavior for fractional cents in the sandbox environment. This change is intended to allow orders API client developers to experiment with pricing behavior that will become the default in all environments, including production, on 2018-06-04. The pricingFeatures value indicates the rounding behavior that the orders API will use, or the method that it did use for historical orders.

If you do not include the pricingFeatures value for an order, the orders API will use the current, or legacy, tax rounding behavior.
If you include the string TAXESV2 in the string array value for pricingFeatures, the orders API will use the new tax rounding behavior. See more information about the new tax rounding behavior.
When you GET an order, the pricingFeatures string array will include TAXESV2 for orders that used the new tax rounding behavior. If the pricingFeatures string array does not include TAXESV2, the order used the previous tax rounding behavior.
During the testing period, orders API orders that use the new tax rounding behavior may not display the correct price in the sales report information in the Toast administration back-end. After the new tax rounding behavior is the default behavior for orders, the sales report prices will be consistent with the prices shown in the orders API.

rel20180405

The orders API now assigns check numbers (the displayNumber) for future orders using the check numbering sequence for the opened date of the order. On the opened date of the order, the check number will be unique in the set of check numbers that the Toast POS system generates for that business day. For example, if you include a openedDate value for an order and you do not include a displayNumber for the check in the order, the Toast POS system will generate a check number in the sequence of check numbers for the openedDate business date. The POS system will not automatically assign that check number to any other orders on that day.

rel20180330

Nearly simultaneous requests to alter or delete a labor API resource now returns an HTTP 409 (conflict) response for each request that fails because the resource is not available for updates. For example, if you submit multiple, simultaneous requests to delete a resource, one request will succeed and each other request will return an HTTP 409 response code. Previously, the labor API returned an HTTP 500 response for requests that were blocked by simultaneous requests to update the same resource.

rel20180323

The cash management API now reports information about three new cash entry types. The new cash entry types occur when an employee closes a cash drawer, for example at the end of a shift. The new cash entry types are:

CLOSE_OUT_EXACT - an employee closes a cash drawer and the actual balance matches the expected balance.
CLOSE_OUT_OVERAGE - an employee closes a cash drawer and the actual balance is greater than the expected balance.
CLOSE_OUT_SHORTAGE - an employee closes a cash drawer and the actual balance is less than the expected balance.

The orders API now sets the paymentStatus value for a check that is paid with a credit card and with a credit card tip to PAID until the order is fired in the kitchen for fulfillment. Previously, the orders API set the paymentStatus to CLOSED for checks with a credit card payment and a credit card tip. This change only affects orders that are not fired to the kitchen immediately, or future orders.

rel20180316

The labor API now includes a tipsWithheld value in the TimeEntry object. The tipsWithheld value indicates the currency amount withheld from an employee's credit card tips during the time entry period. The amount withheld is calculated as a percentage of the tip amounts added to credit card payments.

rel20180209

The orders API now accepts the two-letter, ISO 3166-2 abbreviations for American Samoa, Guam, the Northern Mariana Islands, and the U.S. Virgin Islands in the state value of the DeliveryInfo object for a delivery order. For example, the state value accepts the abbreviation GU for deliveries in Guam.

The credit cards API has improved its card verification value (CVV) and address verification system (AVS) verification against credit card networks for all credit card authorization requests. This change prevents fraud and makes credit card processing more reliable. It may also increase the number of credit card denials when restaurant guests enter their own credit card information by as much as 5% due to information entry errors and the very small number of actual fraud attempts. The change only affects the Toast production API environment.

rel20180126

The labor API now undeletes employee shifts instead of creating a new shift if the details of the POSTed shift match a deleted (or archived) shift. If the restaurant ID, employee ID, job ID, start time, and end time of a POSTed shift match a deleted shift, the labor API will undelete the shift. If you supply a new externalId value, the labor API will apply the updated externalId value to the undeleted shift.

The orders API handles string input differently in two ways.

If string values exceed the maximum character limits for their value data types, the orders API will return a 400 error with descriptive error messages. Previously, input data with string values exceeding value limits failed without an explanation error message.
The orders API now ignores null Unicode characters in string input.

rel20180105

The orders API now includes an applicableDiscounts endpoint that returns information about the discounts that you can apply to an order. You include the order in the message body parameter in a POST request. The orders API determines which discounts apply to the order based on the item selections in the order checks. You can include an optional body parameter to specify a promotional code. If you include a promotional code, the applicableDiscounts endpoint returns only the discounts that apply to the order and that are also associated with that promotional code.

rel20171215

The orders API now returns the GUIDs of tax rates applied to menu item selections in the return data for an order.

The orders API now matches the quantity of a modifier to the quantity of its menu item selection, or parent modifier, if you do not specify the modifier quantity. If you do specify the quantity of a modifier, the orders API will not alter the quantity of that modifier. Previously, if you did not specify a modifier quantity, the orders API assigned 1 as a default quantity.

The cash management API now returns information about a new cash entry type. The UNDO_PAY_OUT type describes cash entries that return cash that was paid out for restaurant expenses to a cash drawer.

The cash management API now includes an undoes value for cash entries. The value is the GUID of a another cash entry if the current entry reverses a previous entry.

rel20171207

The orders API now supports negatively priced menu items and modifiers. If you configure a modifier that removes an ingredient from a menu item, you might configure a negative price for that modifier because it reduces the cost of that menu item. For example, a sandwich menu item might have a "no cheese" modifier with the price -$1.00.

rel20171110

You can now set the amount of time that it will take to prepare an order in the orders API. The amount of time that you specify in the new requiredPrepTime value for an order will override the default preparation time for delivery or takeout orders. The Toast POS will auto-fire future orders using the preparation time that you specify in the requiredPrepTime value. For example, if you are creating an unusually large order for future fulfillment, you can use the requiredPrepTime value to make sure that a restaurant kitchen has enough time to prepare the order.

The orders API now supports modifiers with prices that are different from their fixed-price modifier groups.

The orders API now rounds fractional cents for taxes in the same way that Toast POS devices do.

The JSON menu data export file now includes an orderableOnline value for menus, menu groups, and menu items. This value indicates whether the menu component is available for orders in the orders API. Possible values are YES and NO.

The JSON menu data export file now includes an visibility value for menus, menu groups, menu items, and modifier groups. This value indicates whether the menu component should be shown to customers, only to restaurant employees, or to no one. Possible values are ALL (visible to customers and employees), POS_ONLY (visible to employees), and NONE (visible to no one).

rel20171103

The orders API now correctly applies service charges that have a zero currency amount. For example, the orders API can now apply a service charge with a $0.00 amount.

The orders API no longer rejects menu items when a required modifier is missing, if the required modifier group is not visible when using the orders API. If the Visibility configuration for a modifier group is set to Only visible to servers or Hidden from everyone, the modifier group is not visible to the orders API.

The configuration API now includes orderableOnline and visibility values for menu objects. The configuration API previously returned orderableOnline and visibility values for menu groups and menu items only.

rel20171006

The orders API now supports ordering menu items that use menu-specific pricing.

The configuration API includes a new value in the type enumeration for menu items. The new value, PORTION, indicates that a menu item is configured as a portion for applying modifiers to part of another menu item.

rel20170929

The configuration API includes new preModifierGroups and preModifiers endpoints that return information about the premodifiers that you have configured for your restaurant. You can get an array containing information about each premodifier group and each premodifier that you have configured or you can get information about one specific premodifier group or premodifier. Premodifiers provide instructions for kitchen employees about menu item modifiers. For example, a premodifier group named "salad dressing" might include premodifiers "light" or "on the side."

rel20170922

The orders API now correctly applies time-specific prices for menu items. The orders API applies the time-specific price that corresponds to the time that the API receives the order, in the time zone that you configure for the restaurant location. The orders API does not adjust time-specific pricing for future orders. It applies prices for future orders based on the time that it receives and processes the order.

rel20170908

The orders API now supports ordering menu items that use time-specific pricing. The orders API will always apply the base price for an item. It will not apply a time-specific price at any time. The orders API does not support ordering items that use menu-specific pricing or open pricing.

The orders API now supports applying bulk discounts. Bulk discounts reduce the price of multiple menu items in a check.

The menu data export files now include information about the premodifiers configured for your restaurant and images for menu items.

rel20170901

The configuration API includes a new noSaleReasons endpoint that returns information about the reasons for no sale cash entries that are configured for a restaurant.

The configuration API includes new orderableOnline and visibility values for menu items and menu groups. The new values report the status of the corresponding configuration settings in a restaurant menu. The orderableOnline and visibility values do not affect the way that you can order items using the orders API.

The cash management API returns information about a new UNDO_PAY_OUT cash entry type. The UNDO_PAY_OUT cash entry type occurs when restaurant employees add cash to a cash drawer to undo a previous pay out cash entry.

rel20170818

The orders API includes a new enumeration value in the return data for orders. The vendor value in AppliedLoyaltyInfo and LoyaltyDetails objects for orders now includes an additional value to indicate a specific loyalty program provider. The new value only occurs in return data.

Your Toast API client software must be able to consume unexpected enumeration values and new values in return data. Make sure that you develop Toast API client software that is compatible with unexpected new data.

rel20170728

Toast APIs will not support TLS (transport layer security) versions 1.0 and 1.1 after October 30, 2017. If your API client software does not support TLS 1.2, you must upgrade that software before October 30, 2017.

rel20170623

The labor API now reports credit card tips and automatic gratuity service charges in the TimeEntry object for employees' work shifts. The TimeEntry object now includes the following values, in addition to the existing declaredCashTips value.

nonCashTips
cashGratuityServiceCharges
nonCashGratuityServiceCharges

rel20170324

The labor API creates employees and gets employee information more resiliently.

Nearly simultaneous POST requests to create employees with the same email address at different restaurants will now succeed. Previously, nearly simultaneous POST requests to create the same employee at separate restaurants would create the employee at one restaurant and fail at each of the other restaurants.
Nearly simultaneous POST requests to create employees with the same email address at the same restaurant will now result in a HTTP 400 error and provide an explanation error message. Previously, nearly simultaneous POST requests to create the same employee at one restaurant would create the employee for the first request and return HTTP 500 unexpected error messages for each subsequent request.
GET requests for employee information now return most employee information when Toast POS user management services are unavailable. When those user management services are unavailable, the Employee objects in labor API response data include all employee information except the users' names and email addresses. Previously, when user management services were unavailable, GET requests for employee information would fail.

rel20170310

The orders API now supports open amount discounts for checks. You can include a discountAmount value in an AppliedDiscount object in a POST request to create an order. The orders API does not support open percent discounts or open amount discounts for individual item selections.

The orders API now validates the payment amounts of checks. A POST request to the orders endpoint will fail if any of its checks have a payment amount greater than the calculated price for that check. The orders endpoint does accept payment amounts that are less than the calculated price of the check.

rel20170303

Cash Management API

The cash management API now returns information about cash removed from a restaurant to be deposited in a bank or other financial institution. You can GET information about deposits during one business day from the new /deposits endpoint.

Orders API

The orders API now returns more information about pickup and delivery orders in its return data.

The Order object now includes an estimatedFulfillmentDate value that indicates the date and time that an order is expected to be ready for pickup or to be delivered.

The DeliveryInfo object now includes the following values.

deliveredDate - The date and time that a delivery employee indicates that an order is delivered.
dispatchedDate - The date and time that a restaurant indicates that an order is available for delivery and assigned to a delivery employee.
deliveryEmployee - The Toast GUID or external identifier of the restaurant employee delivering an order.

rel20170217

Orders API

You can now apply open type service charges to checks when you create an order in the orders API.

rel20170203

Orders API

You can now apply item-level discounts and buy-one-get-one (BOGO) discounts when you create an order in the orders API.

You can now apply pre-modifiers to menu item modifiers when you create an order in the orders API. To do this, you include the GUID for a pre-modifier in the new preModifier value in the Selection object.

The Customer object now includes the Toast POS GUID for a customer. The guid value is only present in response data.

Config API

The Menu, MenuGroup, and MenuItem objects now include an images value that contains the URLs of any images that are configured for the corresponding menu, menu group, or menu items. The images value is only present in response data.

rel20170113

Orders API

The orders API now includes values that hold information about customers' loyalty program accounts. The orders API loyalty program functionality is not active in the Toast POS. The new values have been added to prepare for future loyalty program support. You can include a customer's loyalty program identifier when you POST an order and you can apply loyalty program discounts to checks and item selections. Order objects in return data now include these values. See information about working with loyalty programs in the Toast API Developer's Guide.

Labor API

You can now update the external identifiers for employees and jobs in the labor API. The /employees/{employeeId}/externalId and /jobs/{employeeId}/externalId resources now support the PUT method, which will create or replace any existing external identifier value. The /employees/{employeeId}/externalId and /jobs/{employeeId}/externalId resources continue to support the POST method for adding a new external identifier.

Config API

The MenuItem object now includes the price look up (PLU) code for menu items. GET requests to the config API return the MenuItem object with the new PLU code value.

rel20170106

Orders API

You can now use an external reference identifier (externalId) to specify an order in a GET request to the /orders/{guid} resource.

rel20161223

Orders API

The Toast POS now sends notifications to restaurant POS terminals when the orders API creates a new order and the order is synced to the POS terminal. The orders API does not send notifications for orders that are promised more than six days in the future. You can enable notifications for new orders in the orders API by selecting New online orders from the Other Setup > Notification Setup in the Toast administration back-end.

rel20161209

Labor API

The labor API includes the following new resources. The labor API documentation has been updated with information about using the new resources.

/employees/{employeeId}/wageOverrides - Send a PUT request to replace the wage overrides for an employee. A wage override modifies the default wage for a job assigned to the employee.
/employees/{employeeId} - Send a PATCH request to update the first name, last name, or external employee identifier (externalEmployeeId) values for an employee.
/employees/{employeeId} - Send a DELETE request to mark an employee record as deleted.

Orders API

Version one of the orders API will be sunset on December 16, 2016. Use /orders/v2 for all orders API requests. After the sunset /orders/v1 will not be available.

rel20161202

Orders API

The AppliedDiscount object now includes an approver value that contains the GUID of the employee who approved the discount for an item or check. The approver value is only present in response data.

rel20161118

Labor API

The Employee object now includes a passcode value that you can use to set the Toast POS passcode for a new employee. The passcode is a numeric security code that the new employee can use to begin a session in a Toast POS device. You can only include the passcode value in the Employee object for POST requests to create a new employee. The API will return the passcode in clear text in the response data for a successful POST request. The labor API will not return the passcode value in the response data for GET requests.

Orders API

The /payments and /payments/{guid} resources no longer return information about deleted payments. In most cases, you will not delete payments. If you delete a payment, a GET request to the /payments resource will not include that payment in the list of GUIDs that it returns. A GET request to the /payments/{guid} resource for the deleted payment will return an HTTP 404 not found response.

rel20161111

Labor API

The Job object now includes a code value that returns the optional identifier entered in the Job Code field of the Toast administration back-end when you configure a job. For example, you can use the job code to match Toast POS jobs to jobs configured in external labor management systems.

Menu Data Export File

The data export files for Toast POS restaurants now include a file that represents menus in JSON format. The menu data export file includes detailed information about menus, menu groups, menu items, and menu option groups. The information includes prices, which are not currently available from the menu resources in the config API. See information about the menu data export file in the Toast Data Export Guide.

rel20161028

Orders API

GET requests to the orders/v2/orders resource now return information about each tax applied to individual menu selections. The new appliedTax value contains the name, amount, and type (for example, percent or fixed amount) of each tax applied to the items in a selection. Previously, the orders resource returned only the total amount of all taxes applied to the items in a selection.

Displaying GUIDs in the Toast Administration Back-End

Some parts of the Toast administration back-end can now show the globally unique identifiers (GUIDs) that the Toast system assigns to components of your restaurant configuration. You can use these GUIDs to compare the data returned by Toast APIs with the administration back-end or to more easily create API requests.

Displaying GUIDs may not be enabled for your restaurant.

The administration back-end can show GUIDs for configuration components including the following:

Alternate payment types
Discounts
Employee records
Jobs
Menus
Menu groups
Menu items
Service charges
Tax rates
Time entries

rel20161018

Labor API

The labor API includes the following new resources. The labor API documentation has been updated with information about the new resources.

/employees/{employeeId}/externalId - Send a POST request to assign an externalId value to an employee record. You can only assign one externalId value and you cannot change that value after assigning it.
/employees/{employeeId}/jobs - Send a PUT request to replace the list of jobs for an employee record.

The labor API now accepts externalId identifiers for employeeReference and jobReference objects in input data, in addition to Toast GUIDs. Previously, if a request included an employeeReference or jobReference object without a Toast GUID, the request was rejected.

Toast API Release Notes

Ongoing API release notes at new Toast technical documentation site

rel20220311

Webhooks retry messages after HTTP 429 response

rel20220302

Summary of the Order object now available

Orders API includes a new order source enumeration value and an updated source value name

Updated error rate limits for Toast webhook subscriptions

rel20220209

Loyalty API externalId value for menu entities will be null

rel20220131

Orders API includes new Invoice order source enumeration value

New multiLocationId identifier for menus API menu entities

rel20220121

New email subscription for webhook notifications

Gift card add value transactions limited to $500

Loyalty account identifier on reversal can be null

Menus API menu item includes taxInclusion value

rel20211216

New order management configuration API

409 error indicates a restaurant published new data during retrieval of a paginated response

Detailed menu hierarchy description and diagram are available

rel20211210

New menus webhook indicates changed menus

rel20211117

Gift card integration will include cash-out redeem transactions

New multiLocationId value in orders API menu item selections

Menus API rate limit increase

rel20211008

New orders API endpoint adds selections to a check

New orders API endpoint updates order delivery information

Menus API modifier group ordering correctly follows Modifier Ordering Priority setting

rel20210903

New pagination parameter for the configuration and kitchen APIs, old pagination parameters deprecated

New guestOrderStatus in the orders API

rel20210702

New email format for new integrated restaurant locations

Webhooks HTTP message Content-Type header field specifies JSON character encoding

New Google order source in the orders API

rel20210611

Menus API restaurantTimeZone value is no longer null

Menus API will correctly support menu-specific pricing for reused modifier options

New EXTERNAL tax rate type in configuration API

rel20210527

Orders API returns information about marketplace facilitator tax payments

Orders API ordersBulk endpoint rate limit will be reduced

Orders API returns server employee identifier for payments

New kitchens API

Menus API includes prep time and prep station information

New employee identifier values in cash management API

rel20210428

Menus API returns correct pricingRules information for nested modifier groups

Labor API Employee object includes new v2EmployeeGuid value

Credit cards API will not return null denial reasons

New order information in the orders API

rel20210331

Menus API v1 sunset

rel20210201

Orders API returns HTTP 503 service unavailable responses more quickly

rel20210113

Refund information changes in Order object changes to support new refund functionality

Behavior of totalAmount value consistent for all refunds

Refund details object values include refund information

Restaurant employees can refund more payment types

Partners webhook reports location identifier correctly for restaurants

rel20201218

Deprecated authentication endpoint sunset on 2021-01-15

Order object source value contains OPT

rel20201103

Tax rate type value correctly reports PERCENT

rel20201022

Authentication tokens now valid for 24 hours

rel20201001

Orders API orders will apply automatic service charges

rel20200918

Revenue center information included in configuration API ServiceArea and Table objects

rel20200828

Orders API includes values for information about refund transactions

Payment object includes order and check identifiers

Authentication service improvements in test environment, scheduled for production environment

Summary of the `Order` object now available

Loyalty API `externalId` value for menu entities will be null

Orders API includes new `Invoice` order source enumeration value

New `multiLocationId` identifier for menus API menu entities

New `multiLocationId` value in orders API menu item selections

New `guestOrderStatus` in the orders API

Webhooks HTTP message `Content-Type` header field specifies JSON character encoding

New `Google` order source in the orders API

Menus API `restaurantTimeZone` value is no longer `null`

New `EXTERNAL` tax rate type in configuration API

Orders API `ordersBulk` endpoint rate limit will be reduced

Menus API returns correct `pricingRules` information for nested modifier groups

Labor API `Employee` object includes new `v2EmployeeGuid` value

Credit cards API will not return `null` denial reasons

Refund information changes in `Order` object changes to support new refund functionality

Behavior of `totalAmount` value consistent for all refunds

`Order` object `source` value contains `OPT`

Tax rate `type` value correctly reports `PERCENT`

New `curbside` value in the `DiningOption` object in the configuration API

New `createdDate` Values in `Order` and `Check` Objects in the Orders API

`lastModified` Query Parameter for Partners API `restaurants` Endpoint

`payload` Value in Webhook Updates Has Been Renamed to `details`

New `modifierOptionTaxInfo` Value for Modifier Options in the Menus API, `taxInfo` Deprecated for Modifier Options

`TimeEntry` Object Returns Rounded Hour Values for Some Restaurant Locations

New `PROCESSING_VOID` Payment Status Enumeration Value in the Orders API

`Toast-Rate-Limit-Limit` and `Toast-Rate-Limit-Remaining` Rate Limiting Header Fields Sunset

Orders API Sets Check `openedDate` to Order `openedDate` if `null`

Authentication Response `scope` Value Includes `orders` String