Externally-priced orders and discounts

Overview

With external pricing, your system calculates order prices, including discounts, instead of relying on the Toast platform's pricing engine. You must send discount and item pricing information to the Toast platform to ensure accurate reporting and consistency across platforms. When orders are priced outside of the Toast platform, such as those originating from third-party ordering platforms, it's essential to have a way to accurately reflect discounts.

Item-level and check-level discounts are currently supported for externally-priced orders. An item-level discount is a discount that affects a single menu item, whereas a check-level discount affects the entire order.

You must ensure the accuracy of all discount data, as the Toast platform will not validate or manipulate this data. The Toast platform will store your discount data and use it to populate relevant reports.

For information about how check-level discounts are applied, see Calculating check-level discounts for externally-priced orders.

Integrating with the orders API

To send discount data to the Toast platform, use the POST /orders endpoint of the orders API. To authorize these requests, you'll need the orders.selection_price_tax_override:write and orders.orders:write Scopes.

The orders API /void endpoint supports canceling orders that include externally applied discounts.

Note

Externally-priced orders are only accepted using the /orders endpoint.

For more information about the orders API, see the orders API reference documentation.

Requirements

To properly integrate with the orders API and send externally priced orders, you must include specific discount data fields in your API requests. These fields provide the Toast platform with the necessary information to accurately represent discounts. The required fields are defined in the table below.

Parent object	Value	Description
`selection`	`discount`	Discount amount applied to individual items, excluding check-level discounts.
`selection`	`preDiscountPrice`	Price of the item before any discounts are applied, excluding tax.
`selection`	`price`	Price of the item after discounts are applied, including modifiers, and excluding tax.
`selection`	`menuItemPrice`	The price of the menu item before any calculations, such as quantity adjustments, modifiers, discounts, or taxes.
`selection`	`externalPriceAmount`	The price of the menu item calculated outside the Toast platform.
`appliedDiscount`	`name`	Name of the discount. The name of the discount will show to the restaurants in reporting. Restaurant teams find it helpful if the name of the discount includes the partner's name + name of the promotion such as “{Partner name} $1 off promo.”
`appliedDiscount`	`discountAmount`	Total discount amount, inclusive of tax.
`appliedDiscount`	`nonTaxDiscountAmount`	Discount amount, excluding tax.
`check`	`discountAmount`	Discount amount applied at the check level.
`check`	`totalDiscountAmount`	Sum of all discount amounts applied to the check and its items.
`check`	`preDiscountAmount`	Sum of all pre-discount prices for all items on the check.
`check`	`netAmount`	Sum of all item prices, including modifiers and discounts, but excluding tax.
`check`	`totalAmount`	Sum of the net amount, tax, tip, and gratuities.
`order`	`discountAmount`	Sum of all check-level discounts only, excluding tax.
`order`	`totalDiscountAmount`	Sum of all discount amounts applied to the order and its items.
`order`	`preDiscountAmount`	Sum of all pre-discount prices for all items on the order.
`order`	`netAmount`	Sum of an order’s item prices, including modifiers and discounts, but excluding tax.
`order`	`totalAmount`	Sum of the net amount, tax, tip, and gratuities.

The following sections provide additional details about what fields are required when submitting an order to the orders API with external pricing.

When any order is submitted to the /orders endpoint with external pricing

Order
- totalAmount
- netAmount
Check
- totalAmount
- netAmount
Selection
- externalPriceAmount
- price
- menuItemPrice
MarketplaceFacilitatorTaxInfo
- taxes

When a discount is included in an order with external pricing

Order
- discountAmount
- totalDiscountAmount
- preDiscountAmount
- totalAmount
- netAmount
Check
- discountAmount
- totalDiscountAmount
- preDiscountAmount
- totalAmount
- netAmount
Selection
- discount
- preDiscountPrice
- externalPriceAmount
- price
- menuItemPrice
MarketplaceFacilitatorTaxInfo
- taxes
AppliedDiscount
- name
- discountAmount
- nonTaxDiscountAmount

Sample request

The following example shows a request to the /orders endpoint that uses externally-priced discounts.

{
  "diningOption": {
    "guid": "59de65f0-a868-43e7-8441-189d2f95e696"
  },
  "checks": [
    {
      "selections": [
        {
          "item": {
            "guid": "0b5aec4b-1388-40fb-9714-e42480809111"
          },
          "itemGroup": {
            "guid": "009e0dd4-263d-4847-9c83-9df896d81ab2"
          },
          "quantity": 1,
          "appliedDiscounts": [
            {
              "name": "$1 off promo",
              "discountAmount": 1.0,
              "nonTaxDiscountAmount": 1.0
            }
          ],
          "discount": 1.0, 
          "menuItemPrice": 5.0,
          "externalPriceAmount": 5.0,
          "preDiscountPrice": 5.0,
          "price": 4.0
        }
      ],
      "appliedDiscounts": [
        {
          "name": "$2 off promo", 
          "discountAmount": 2.0,
          "nonTaxDiscountAmount": 2.0
        }
      ],
      "discountAmount": 2.0, 
      "totalDiscountAmount": 3.0,
      "preDiscountAmount": 5.0,
      "netAmount": 2.0,
      "totalAmount": 2.0
    }
  ],
  "marketplaceFacilitatorTaxInfo": {
    "taxes": [
      {
        "name": "External Tax",
        "taxAmount": 2.0,
        "facilitatorCollectAndRemitTax": true
      }
    ]
  },
  "discountAmount": 2.0,
  "totalDiscountAmount": 3.0,
  "preDiscountAmount": 5.0,
  "netAmount": 2.0,
  "totalAmount": 2.0
}

The discount field of the Selection object represents the value of a discount applied to an item, not including the entire check discount amount. For example, a “$2 off a slice of pizza” discount could apply to a single pizza slice menu item, but would not include a total check-level discount.

The discountAmount field of the Check object represents the value of a discount applied to the entire order. For example, a “$2.00 off your total order” discount could apply to an entire order and include the percentage discounts calculated from the items of the check. For more information about how check-level discounts are calculated, see Calculating check-level discounts for externally-priced orders.

Calculating check-level discounts for externally-priced orders

When a check-level discount is applied to an externally-priced order, the discount is distributed among all menu items using a percentage-based method. The procedure below describes the process to calculate check-level discounts.

To calculate a check-level discount

Total the pre-discount amounts of all the menu items in a check.
Calculate what percentage each menu item represents of the check total.
Apply the discount to the check total based on calculated percentages.

The example below further describes how check-level discounts are applied to a check.

Example check-level discount

For this example, there is a check with two menu items, one that is $15.00 and one that is $5.00, and there is a check discount of $4.00.

1. Total the pre-discount amounts of all the menu items in a check.

Menu item 1: $15.00 (pre-discount price)
Menu item 2: $5.00 (pre-discount price)
Pre-discount check total: $20.00

2. Calculate what percentage each menu item represents of the check total.

Menu item 1: $15.00 / $20.00 = 75%
Menu item 2: $5.00 / $20.00 = 25%

3. Apply the discount to the check total based on calculated percentages.

Menu item 1: $4.00 x 75% = $3.00

Since Menu item 1 makes up 75% of the check total, it receives 75% of the check discount.
Menu item 2: $4.00 x 25% = $1.00

Since Menu item 2 makes up 25% of the check total, it receives 25% of the check discount.

Discount application process

Using the same example listed above, if we have an order with two menu items ($15.00 and $5.00) and a check-level discount ($4.00) the below sections describe how the discount logic applies to each menu item.

Note

Check-level discounts are only applied to top-level menu items and not to modifiers.

Menu item 1

Original price: $15.00 (75% of the check total)
Check discount (75%): $3.00 ($4.00 x 75%)
Price after discount: $12.00 ($15.00 - $3.00)

Menu item 2

Original price: $5.00 (25% of the check total)
Check discount (25%): $1.00 ($4.00 x 25%)
Final price: $4.00 ($5.00 - $1.00)

Toast reporting

The external discount data you provide will be displayed across various Toast reports. The following sections describe what details can be displayed in Toast reporting.

Discounts Summary Report

The Discounts Summary Report can include the following details when they are provided:

Discount name
Check discount amount
Item discount amount
Check and item discount amount totals

The image below shows an example of a Discounts Summary Report with the above fields.

Screenshot of the Discounts Summary Report.

Orders report

The Orders report can show the total discount applied when this amount is provided externally. The image below shows the Discount Amount as it appears in the Orders report.

Single order view

The single order view can include the following fields when they are provided:

Total Discount Amount
Pre-Discount Price
External Price Amount
Discount Name
Check Discount Amount
Item Discount Amount

The image below shows an example of the single order view with these fields.

Screenshot of the single order view highlighting the described discount fields.

Discounts report

The Discounts report can show the following information when it is provided:

Discount Summary
Discount Reasons
Discounts by Server
Discounts by Approver
Discount Name
Check Discount Amount
Item Discount Amount
Pre-Discount Amount
Pre-Discount Price

The images below show examples of the Discounts report with the above information.

Screenshot of the Discount report's Discount Reasons, Discounts by Server, and Discounts by Approver sections.

Screenshot of the Discounts report's All Discounted Orders section.

Error handling

The table below describes the different errors you may see when submitting an externally-priced order with the orders API.

Error code	Error message
10025	`name` in `AppliedDiscount` is response only.
10025	`nonTaxDiscountAmount` in `AppliedDiscount` is response only.
10025	`Applied discount` name is longer than 1000 characters.
10025	`externalPriceAmount` in `Selection` is not permitted.
10025	`totalAmount` in `Check` is response only.
10025	`netAmount` in `Check` is response only.
10025	`totalDiscountAmount` in `Check` is response only.
23066	Service charges are not supported on orders with taxes and `externalPriceAmount`.
23070	Externally-priced discounts are not allowed.
23071	Invalid externally-priced discount.
23072	Applied discount transactions are not supported on orders with taxes and `externalPriceAmount`.
23073	Applied discounts are not supported on modifiers.
23074	`AppliedDiscount.discountAmount` value should be greater than zero.
23074	`AppliedDiscount.nonTaxDiscountAmount` value should be greater than zero.
23074	`Selection.externalPriceAmount` value should be greater than zero.
23074	`Selection.discount` value should be greater than zero.
23074	`Selection.preDiscountPrice` value should be greater than zero.
23074	`Check.totalDiscountAmount` value should be greater than zero.
23074	`Check.preDiscountAmount` value should be greater than zero.
23074	`Check.discountAmount` value should be greater than zero.
23074	`Modifier.price` value should be greater than zero.
23074	`Order.totalDiscountAmount` value should be greater than zero.
23074	`Order.preDiscountAmount` value should be greater than zero.
23074	`Order.discountAmount` value should be greater than zero.
23075	`Selection.externalPriceAmount` value should be greater than or equal to zero.
23075	`Selection.menuItemPrice` value should be greater than or equal to zero.
23075	`Selection.price` value should be greater than or equal to zero.
23075	`Selection.preDiscountPrice` value should be greater than or equal to zero.
23075	`Modifier.externalPriceAmount` value should be greater than or equal to zero.
23075	`Modifier.menuItemPrice` value should be greater than or equal to zero.
23075	`Modifier.preDiscountPrice` value should be greater than or equal to zero.
23075	`Check.netAmount` value should be greater than or equal to zero.
23075	`Check.totalAmount` value should be greater than or equal to zero.
23075	`Check.preDiscountAmount` value should be greater than or equal to zero.
23075	`Order.netAmount` value should be greater than or equal to zero.
23075	`Order.totalAmount` value should be greater than or equal to zero.
23075	`Order.preDiscountAmount` value should be greater than or equal to zero.
23076	`Selection.discount` value should be zero. Selection does not have any discounts.
23076	`Modifier.discount` value should be zero. Modifier does not contain any discounts.
23076	`Check.discountAmount` value should be zero. Check does not have any discounts.
23076	`Check.totalDiscountAmount` value should be zero. Check does not have any discounts.
23076	`Order.discountAmount` value should be zero. Order does not have any discounts.
23076	`Order.totalDiscountAmount` value should be zero. Order does not have any discounts.
23077	`Discount.name` value is required.
23077	`AppliedDiscount.discountAmount` value is required.
23077	`AppliedDiscount.nonTaxDiscountAmount` value is required.
23077	`Selection.externalPriceAmount` value is required.
23077	`Selection.menuItemPrice` value is required.
23077	`Selection.price` value is required.
23077	`Selection.preDiscountPrice` value is required.
23077	`Modifier.externalPriceAmount` value is required.
23077	`Modifier.menuItemPrice` value is required.
23077	`Modifier.price` value is required.
23077	`Check.netAmount` value is required.
23077	`Check.totalAmount` value is required.
23077	`Check.discountAmount` value is required.
23077	`Check.totalDiscountAmount` value is required.
23077	`Check.preDiscountAmount` value is required.
23077	`Order.netAmount` value is required.
23077	`Order.totalAmount` value is required.
23077	`Order.discountAmount` value is required.
23077	`Order.totalDiscountAmount` value is required.
23077	`Order.preDiscountAmount` value is required.
23077	`Order.discountAmount` value is required.
23078	Multiple discounts are not supported on selection level.
23078	Multiple discounts are not supported on check level.
23079	Externally-priced order values are inconsistent: `AppliedDiscount.nonTaxDiscountAmount` `{{AMOUNT}}` should be less than or equal to `AppliedDiscount.discountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Selection.discount` `{{AMOUNT}}` should be equal to `AppliedDiscount.nonTaxDiscountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Selection.discount` `{{AMOUNT}}` should be less than or equal to `Selection.preDiscountPrice` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Selection.preDiscountPrice` `{{AMOUNT}}` should be equal to `Selection.externalPriceAmount` `{{AMOUNT}}` plus sum of all `Modifier.preDiscountPrice` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Selection.price` `{{AMOUNT}}` should be equal to `Selection.preDiscountPrice` `{{AMOUNT}}` minus `Selection.discount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Selection.price` `{{AMOUNT}}` should be less than `Selection.preDiscountPrice` `{{AMOUNT}}` minus `Selection.discount` `{{AMOUNT}}`. Check level discount should be distributed among selections.
23079	Externally-priced order values are inconsistent: `Modifier.preDiscountPrice` `{{AMOUNT}}` should be equal to `Modifier.externalPriceAmount` `{{AMOUNT}}` plus sum of all `Modifier.preDiscountPrice` `{{AMOUNT}}`.
23079	`Modifier.preDiscountPrice` `{{AMOUNT}}` should be equal to `Modifier.price` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Check.discountAmount` `{{AMOUNT}}` should be equal to `AppliedDiscount.nonTaxDiscountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Check.totalDiscountAmount` `{{AMOUNT}}` should be equal to `Check.discountAmount` `{{AMOUNT}}` plus sum of all `Selection.discount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Check.totalDiscountAmount` `{{AMOUNT}}` should be less than or equal to `Check.preDiscountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Check.preDiscountAmount` `{{AMOUNT}}` should be equal to sum of all `Selection.preDiscountPrice` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Check.netAmount` `{{AMOUNT}}` should be equal to `Check.preDiscountAmount` `{{AMOUNT}}` minus `Check.totalDiscountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Check.netAmount` `{{AMOUNT}}` should be equal to `Selection.price` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Check.totalAmount` `{{AMOUNT}}` should be equal to `Check.netAmount` `{{AMOUNT}}` plus `Check.taxAmount` `{{AMOUNT}}` plus `Check.tipAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Order.discountAmount` `{{AMOUNT}}` should be equal to sum of all `Check.discountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Order.totalDiscountAmount` `{{AMOUNT}}` should be equal to sum of all `Check.totalDiscountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Order.preDiscountAmount` `{{AMOUNT}}` should be equal to sum of all `Check.preDiscountAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Order.netAmount` `{{AMOUNT}}` should be equal to sum of all `Check.netAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Order.totalAmount` `{{AMOUNT}}` should be equal to sum of all `Check.totalAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Order.taxAmount` `{{AMOUNT}}` should be equal to sum of all `Check.taxAmount` `{{AMOUNT}}`.
23079	Externally-priced order values are inconsistent: `Order.tipAmount` `{{AMOUNT}}` should be equal to sum of all `Check.tipAmount` `{{AMOUNT}}`.