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 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 (3POs), 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.

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

Note: Externally priced orders are only accepted using the /orders endpoint.

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": 2,
          "appliedDiscounts": [
            {
              "name": "$1 off promo",
              "discountAmount": 1.0,
              "nonTaxDiscountAmount": 1.0
            }
          ],
          "discount": 1.0,
          "menuItemPrice": 5.0,
          "externalPriceAmount": 10.0,
          "preDiscountPrice": 10.0,
          "price": 9.0
        }
      ],
      "appliedDiscounts": [
        {
          "name": "$2 off promo", 
          "discountAmount": 2.0,
          "nonTaxDiscountAmount": 2.0
        }
      ],
      "discountAmount": 2.0,
      "totalDiscountAmount": 3.0,
      "preDiscountAmount": 10.0,
      "netAmount": 7.0,
      "totalAmount": 9.0
    }
  ],
  "marketplaceFacilitatorTaxInfo": {
    "taxes": [
      {
        "name": "External Tax",
        "taxAmount": 2.0,
        "facilitatorCollectAndRemitTax": true
      }
    ]
  },
  "discountAmount": 2.0,
  "totalDiscountAmount": 3.0,
  "preDiscountAmount": 10.0,
  "netAmount": 7.0,
  "totalAmount": 9.0
}

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

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.

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.