swagger: '2.0'
info:
version: 1.0.0
title: Toast Authentication Discounts API
description: 'The authentication API returns an authentication token that you can present
when your integration client software uses other Toast APIs. For more
information about authentication, see [the Toast Developer
Guide](https://doc.toasttab.com/doc/devguide/authentication.html).
'
termsOfService: https://pos.toasttab.com/api-terms-of-use
contact:
name: Toast developer support
host: toast-api-server
basePath: /authentication/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Discounts
description: 'Related to price reduction applied to restaurant orders. For example, a
restaurant might apply a discount for a promotion.
'
paths:
/orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts:
post:
tags:
- Discounts
summary: Toast Add Check-level Discounts
description: 'Adds one or more check-level discounts to a check in an
existing order. Include an array of `Discount` objects in the
message body.
For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiDiscountingOrders.html#apiAddingDiscountsToChecks).
'
operationId: ordersChecksAppliedDiscountsPost
produces:
- application/json
parameters:
- name: orderGuid
description: 'The Toast platform identifier of the order that you are
adding a discount to.
'
in: path
required: true
type: string
- name: checkGuid
description: 'The Toast platform identifier of the check that you are
adding a discount to.
'
in: path
required: true
type: string
- name: body
description: 'A JSON array of `AppliedDiscount` objects that identify the discounts you are adding.
'
in: body
required: true
schema:
type: array
items:
$ref: '#/definitions/AppliedDiscount'
responses:
'200':
description: 'A JSON `Order` object that includes the discount you added.
'
schema:
$ref: '#/definitions/Order'
'400':
description: The API cannot process the request.
security:
- oauth2:
- orders.discounts:write
/orders/{orderGuid}/checks/{checkGuid}/selections/{selectionGuid}/appliedDiscounts:
post:
tags:
- Discounts
summary: Toast Add Item-level Discounts
description: 'Adds one or more item-level discounts to menu item selections
in a check in an existing order. Include an array of `Discount` objects in the
message body.
For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiDiscountingOrders.html#apiAddingDiscountsToChecks).
'
operationId: ordersChecksSelectionsAppliedDiscountsPost
produces:
- application/json
parameters:
- name: orderGuid
description: 'The Toast platform identifier of the order that you are
adding a discount to.
'
in: path
required: true
type: string
- name: checkGuid
description: 'The Toast platform identifier of the check that you are
adding a discount to.
'
in: path
required: true
type: string
- name: selectionGuid
description: 'The Toast platform identifier of the menu item selection
that you are adding a discount to.
'
in: path
required: true
type: string
- name: body
description: 'A JSON array of `AppliedDiscount` objects that identify the discounts you are adding.
'
in: body
required: true
schema:
type: array
items:
$ref: '#/definitions/AppliedDiscount'
responses:
'200':
description: 'A JSON `Order` object that includes the discount you added.
'
schema:
$ref: '#/definitions/Order'
'400':
description: The API cannot process the request.
security:
- oauth2:
- orders.discounts:write
/applicableDiscounts:
post:
tags:
- Discounts
summary: Toast Get Applicable Discounts
description: 'Returns an array of `ApplicableDiscount`
objects that contain information about the discounts that apply
to the checks and menu item selections in an order.
Each `ApplicableDiscount` object contains information that you can
use to determine which items and checks are eligible for the
discount.
If you include a `promoCode` value in the
`ApplicableDiscount` object, the `applicableDiscounts` endpoint
returns the only the discounts that are associated with that
promotional code.
'
operationId: applicableDiscountsPost
produces:
- application/json
parameters:
- name: Toast-Restaurant-External-ID
description: The identifier of the restaurant.
in: header
required: true
type: string
- name: body
description: 'A JSON `ApplicableDiscountsRequest` object containing
information about an order, and an optional `promoCode`.
'
in: body
required: true
schema:
$ref: '#/definitions/ApplicableDiscountsRequest'
responses:
'200':
description: A JSON array of `ApplicableDiscount` objects.
schema:
title: ApplicableDiscounts
type: array
items:
$ref: '#/definitions/ApplicableDiscount'
'400':
description: Invalid arguments
'500':
description: An unexpected internal error occurred. The `requestId` that is attached to this error can be referenced by Toast.
security:
- oauth2:
- orders.orders:write
definitions:
RefundTransaction:
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.
'
AppliedPackagingInfo:
type: object
description: 'Information describing the guest''s packaging preferences for this order, for example utensils, napkins, condiments.
For more information, see [Packaging preferences](https://doc.toasttab.com/doc/devguide/apiOrdersPackagingPreferences.html)
'
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
properties:
appliedPackagingItems:
type: array
minItems: 1
items:
$ref: '#/definitions/AppliedPackagingItem'
AppliedDiscountTrigger:
type: object
description: The Selection that triggered the application of this discount
properties:
selection:
$ref: '#/definitions/ExternalReference'
quantity:
type: number
format: double
description: The amount of the selection used to trigger the applied discount.
Refund:
type: object
description: A currency amount removed from a guest payment.
properties:
refundAmount:
type: number
format: double
description: The amount of the refund, excluding the tip.
tipRefundAmount:
type: number
format: double
description: The amount of the tip refund.
refundDate:
description: The date and time when the refund was made.
type: string
format: date-time
refundBusinessDate:
x-toast-read-only: true
description: The business date (yyyyMMdd) on which this refund was created. Response only.
type: integer
refundTransaction:
description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.
'
type: object
$ref: '#/definitions/RefundTransaction'
RefundDetails:
type: object
description: '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.
'
properties:
refundAmount:
description: 'The value of the menu item or service charge (excluding taxes) being
refunded. Includes the value of any nested modifier options that
increased the price of the item or modifier option (an upcharge for
the modifier option).
'
type: number
format: double
taxRefundAmount:
description: 'The tax amount being refunded.
'
type: number
format: double
refundTransaction:
description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.
'
type: object
$ref: '#/definitions/RefundTransaction'
AppliedServiceCharge:
type: object
description: 'A service charge that is added to a check. A service charge can represent an upcharge such as a gratuity or a delivery fee.
Whether the upcharge is taxable is defined in the restaurant-configured `serviceCharge`.
The fields on the `AppliedServiceCharge` are calculated based on the referenced `ServiceCharge` configuration.
'
allOf:
- $ref: '#/definitions/ExternalReference'
- type: object
required:
- serviceCharge
properties:
chargeAmount:
type: number
format: double
description: The final applied amount excluding tax. Required if `chargeType` is `OPEN`.
serviceCharge:
description: A reference to the restaurant-configured service charge. If a service charge is taxable, the tax amount is applied to the check.
$ref: '#/definitions/ExternalReference'
chargeType:
x-toast-read-only: true
description: 'The type of service charge. Response only.
Valid values:
* `FIXED` - The service charge is for a specific currency amount.
* `PERCENT` - The service charge is for a percentage of the check amount.
* `OPEN` - The service charge is not configured with an amount. The amount is specified by the restaurant employee.
'
type: string
enum:
- FIXED
- PERCENT
- OPEN
name:
x-toast-read-only: true
description: The configured human readable label for the service charge. Response only.
type: string
delivery:
x-toast-read-only: true
description: Whether this service charge is a delivery charge. Response only.
type: boolean
takeout:
x-toast-read-only: true
description: Whether this service charge is a takeout charge. Response only.
type: boolean
dineIn:
x-toast-read-only: true
description: Whether this service charge is a dine-in charge. Response only.
type: boolean
gratuity:
x-toast-read-only: true
description: Whether this service charge is a gratuity. Can be used to derive required tip amount on the check. Response only.
type: boolean
taxable:
x-toast-read-only: true
description: Whether this service charge is taxable. Response only.
type: boolean
appliedTaxes:
type: array
description: Taxes applied to the service charge.
items:
$ref: '#/definitions/AppliedTaxRate'
serviceChargeCalculation:
type: string
description: 'Defines whether a `PERCENT` service charge is applied before (`PRE_DISCOUNT`) or after (`POST_DISCOUNT`) discounts.
This field is `null` for `FIXED` and `OPEN` service charges.
'
enum:
- PRE_DISCOUNT
- POST_DISCOUNT
refundDetails:
description: 'A `RefundDetails` object that
contains information about refunded payment amounts for the item.
'
type: object
$ref: '#/definitions/RefundDetails'
serviceChargeCategory:
x-toast-read-only: true
description: 'The type of service charge. Default is `SERVICE_CHARGE`. Response only.
Valid values:
* `SERVICE_CHARGE` - The default type for a service charge.
* `CREDIT_CARD_SURCHARGE` - A fee assessed _only_ on payment transactions that use a credit card.
* `FUNDRAISING_CAMPAIGN` - Service charge associated with fundraising.
* `CASH_ROUNDING` - Adjustment to the check total to account for cash payments with minimum denominations greater than 0.01.
'
type: string
enum:
- SERVICE_CHARGE
- CREDIT_CARD_SURCHARGE
- FUNDRAISING_CAMPAIGN
- CASH_ROUNDING
paymentGuid:
x-toast-read-only: true
description: The Toast platform unique identifier for the payment the fee is linked to. The `paymentGuid` value is always `null` unless the `serviceChargeCategory` object value is `CREDIT_CARD_SURCHARGE` or `CASH_ROUNDING`. Response only.
type: string
AppliedLoyaltyInfo:
type: object
description: Information about the customer loyalty program account associated with a check.
required:
- loyaltyIdentifier
- vendor
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
properties:
loyaltyIdentifier:
type: string
description: An identifier for the loyalty program account. For `POST` orders, this identifier is transmitted to the loyalty program service provider to associate the check with the loyalty account.
maskedLoyaltyIdentifier:
type: string
description: '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 optionally include this
value when you `POST` an order. It is
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.
The Toast POS app displays a masked representation of the
`loyaltyIdentifier`. All characters except the last four
are hidden.
'
vendor:
type: string
description: The specific loyalty program service provider that supports the loyalty account.
enum:
- TOAST
- PUNCHH
- PUNCHH2
- PAYTRONIX
- APPFRONT
- INTEGRATION
accrualFamilyGuid:
x-toast-read-only: true
type: string
description: 'Response only. An internal Toast platform identifier for loyalty
program transactions.
This is not returned from the initial
`POST` order request and is available at a later time.
'
accrualText:
x-toast-read-only: true
type: string
description: 'Response only. A description of the loyalty program transaction
to print on the customer''s receipt. For example,
"Earned 27 points."
The maximum length of the description string
is 255 characters.
This is not returned from the initial
`POST` order request and is available at a later time.
'
ApplicableDiscountsRequest:
type: object
description: 'A wrapper object that contains an `Order` object and an optional
promotional code.
You include an `ApplicableDiscountsRequest`
object in the message body of a `POST` request to the
`applicableDiscounts` endpoint.
'
required:
- order
properties:
order:
type: object
$ref: '#/definitions/Order'
description: 'An `Order` object that
contains information about the order that you want to get discounts
for.
'
promoCode:
description: 'An optional promotional code. If you include a promotional
code, the `applicableDiscounts` endpoint returns only
discounts that are associated with that promotional code.
'
type: string
Device:
type: object
description: 'The *Device ID* value that the Toast platform assigns to a specific Toast POS device.
The `id` value is a unique identifier for a device.
To find the ID for a Toast POS device, from the overflow menu (⋮) select *Device Status* and then select the *Device* tab.
'
properties:
id:
type: string
description: The physical id of the device
Selection:
type: object
description: 'A `Selection` object can represent either a primary item (for example,
`Check.selections`) or a modifier (`Selection.modifiers`) selection.
Quantity defaults to `1`.
For a `POST` operation, all selections must have valid `item` and
`itemGroup` fields. The `item` and `itemGroup` values can be `null` for
`GET` requests. For example, they are `null` for gift cards and on special
requests.
To specify a modifier selection, add it to the `modifiers` list of
another selection. Each modifier selection must have its `optionGroup` field
set correctly, because a `MenuItem` can be included in multiple
`MenuOptionGroups`, potentially with different prices or sizing.
The `externalId` value for a selection must be unique. If you submit a
selection with an `externalId` that already exists for another selection,
the request will fail. You can use this behavior to implement idempotent
selection submission by always providing a consistent `externalId` for
each unique selection attempt.
'
allOf:
- $ref: '#/definitions/ExternalReference'
- type: object
required:
- item
- quantity
properties:
item:
type: object
description: A reference to the selected menu item.
$ref: '#/definitions/ConfigReference'
itemGroup:
type: object
description: A reference to the menu group from which the item was selected.
$ref: '#/definitions/ConfigReference'
optionGroup:
type: object
description: A reference to the modifier group from which the menu item was selected. Only applies if this is a modifier selection.
$ref: '#/definitions/ConfigReference'
preModifier:
type: object
description: A reference to the selected pre-modifier.
$ref: '#/definitions/ConfigReference'
quantity:
type: number
format: double
description: Quantity ordered. For items sold by weight, a decimal number. For discrete items, a counting number.
seatNumber:
x-toast-read-only: true
type: integer
description: "Indicates which guest seat at a restaurant table ordered\na menu item selection. Restaurant employees can choose the\nseat number when they add a menu item to a guest check.\n\n* A positive integer value indicates the seat number for\n the menu item.\n\n* `0` - Indicates that the menu item is shared by\n multiple guests.\n\n* `-1` - Indicates that the restaurant employee did not\n select a seat for the menu item.\n\nResponse only.\n"
unitOfMeasure:
type: string
description: 'The unit of measure used to weigh, determine size, or otherwise
quantify the item.
The default is `NONE`, which means that the item is not meant to
be measured during a sale.
Values are:
* `NONE` - The item is not meant to be measured.
* `LB` - Weighed in pounds.
* `OZ` - Weighed in ounces.
* `KG` - Weighed in kilograms.
* `G` - Weighed in grams.
* `GAL` - Measured in gallons.
* `L` - Measured in liters.
* `ML` - Measured in milliliters.
* `FL_OZ` - Measured in fluid ounces.
* `M` - Measured in meters.
* `CM` - Measured in centimeters.
* `FT` - Measured in feet.
* `IN` - Measured in inches.
* `YD` - Measured in yards.
'
enum:
- NONE
- LB
- OZ
- KG
- G
- GAL
- L
- ML
- FL_OZ
- M
- CM
- FT
- IN
- YD
selectionType:
type: string
description: 'Specifies whether this selection is a special request or other off-menu sale.
If `null` or `NONE`, describes a normal modifier or item selection.
`TOAST_CARD_SELL` and `TOAST_CARD_RELOAD` are currently response-only.
'
enum:
- NONE
- OPEN_ITEM
- SPECIAL_REQUEST
- PORTION
- HOUSE_ACCOUNT_PAY_BALANCE
- TOAST_CARD_SELL
- TOAST_CARD_RELOAD
salesCategory:
x-toast-read-only: true
type: object
description: A reference to the sales category of the item. Response only.
$ref: '#/definitions/ConfigReference'
appliedDiscounts:
x-toast-read-only: true
type: array
description: The itemized discounts that are applied to this item. Response only.
minItems: 0
items:
$ref: '#/definitions/AppliedDiscount'
deferred:
type: boolean
description: Whether this selection is a deferred revenue transaction, such as a gift card sale.
preDiscountPrice:
x-toast-read-only: true
type: number
description: Gross sale price for this selection. Excludes tax. Response only.
format: double
price:
x-toast-read-only: true
type: number
format: double
description: Net price for this selection. The final price of the item after considering discounts (including discounts at the check level), quantity adjustments, and modifier prices at the time the item was selected for purchase. Response only.
tax:
x-toast-read-only: true
type: number
format: double
description: The total tax amount for this selection. Response only.
voided:
x-toast-read-only: true
type: boolean
description: Set to `true` if this selection is voided. Response only.
voidDate:
x-toast-read-only: true
type: string
format: date-time
description: The date on which this selection was voided. Response only.
voidBusinessDate:
x-toast-read-only: true
type: integer
description: The business date (yyyyMMdd) on which this selection was voided. Response only.
voidReason:
x-toast-read-only: true
type: object
description: If `voided` is `true`, a reference to the void reason. Response only.
$ref: '#/definitions/ExternalReference'
refundDetails:
description: 'A `RefundDetails` object that
contains information about refunded payment amounts for the item.
'
type: object
$ref: '#/definitions/RefundDetails'
displayName:
type: string
description: 'The display name of the selection.
Can be used to set a special request value.
Otherwise, it is generated from this selection''s item property.
'
plu:
x-toast-read-only: true
type: string
description: The price look-up (PLU) code for the menu item selection used for pricing and inventory management.
premodifierPlu:
x-toast-read-only: true
type: string
description: The Price Look-Up (PLU) code for the premodifier associated with this menu item selection. This is a unique identifier used for pricing and inventory management purposes. Currently this field is read only.
createdDate:
type: string
format: date-time
description: The date on which this selection was created. If not specified, defaults to the current time.
modifiedDate:
type: string
format: date-time
description: The date on which this selection was last modified. If not specified, defaults to the current time.
modifiers:
type: array
description: A list of modifiers that apply to this selection.
items:
$ref: '#/definitions/Selection'
fulfillmentStatus:
x-toast-read-only: true
type: string
default: NEW
description: "Indicates the stage of the preparation workflow that the\nmenu item selection is in.\n\nThe `fulfillmentStatus` of a\nmenu item selection changes as restaurant employees move\nthe item through the functions of the Toast POS, for\nexample order entry and the kitchen display system (KDS).\nResponse only.\n\nValid values:\n\n* `NEW` - The menu item selection was added to a\n check but is not yet sent to the KDS for\n preparation.\n\n* `HOLD` - A restaurant employee paused the menu\n item selection so that it does not appear in the\n KDS for preparation.\n\n* `SENT` - The menu item selection was fired and\n appears in the KDS for preparation.\n\n* `READY` - Preparation is complete. The menu item\n selection is fulfilled and no longer appears in\n the KDS. If your restaurant does not use the Toast platform\n KDS, then order items do not reach the `READY`\n status.\n"
enum:
- NEW
- HOLD
- SENT
- READY
fulfillment:
x-toast-read-only: true
type: object
description: 'Information about the fulfillment requirements for this menu item selection. Response only.
'
$ref: '#/definitions/Fulfillment'
taxInclusion:
type: string
description: "Indicates whether the menu item price includes one or more tax\namounts. If the menu item is a modifier for another menu item\nselection, it always inherits the tax inclusion behavior of the menu\nitem that it applies to.\n\nValid values:\n* `INCLUDED` - The menu item price includes one or more tax amounts.\n* `NOT_INCLUDED` - The menu item price does not include any tax\n amounts.\n* `INHERITED` - The menu item is a modifier for another menu item\n selection in the check. The `taxInclusion` value of the parent menu\n item selection applies to the modifier. If a menu item selection\n *that is not a modifier* inherits tax inclusion behavior from a\n menu or menu group, the `taxInclusion` value is either\n `INCLUDED` or `NOT_INCLUDED`.\n"
enum:
- INCLUDED
- NOT_INCLUDED
- INHERITED
appliedTaxes:
x-toast-read-only: true
type: array
description: An array of `AppliedTaxRate` objects that contain information about tax payments made for the selection. Response only.
items:
$ref: '#/definitions/AppliedTaxRate'
diningOption:
x-toast-read-only: true
description: 'A reference to the setting or method that a restaurant uses to fulfill orders. For example, dine-in, takeout, or delivery might be dining options.
Restaurants configure the dining options that they fulfill orders in.
Response only.
'
type: object
$ref: '#/definitions/ExternalReference'
openPriceAmount:
description: 'A non-negative currency amount that sets the price of a
menu item that is 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 sets 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
inclusive tax amount._
`POST` only. The `openPriceAmount` value is not
present in orders API return data. It is used to
populate `receiptLinePrice`.
'
type: number
format: double
receiptLinePrice:
type: number
format: double
description: "The price of the menu item selection without any quantity, taxes, \ndiscounts, and modifier adjustments. If the menu item has taxes included, the `receiptLinePrice` value shows the original price, including taxes.\n\nFor example, if the menu item selection is for two orders of fries, \n`receiptLinePrice` is the price of one order of fries. If a menu item selection \nis for three large drinks, receiptLinePrice is the price of one large drink.\n\nPopulated based on the menu configuration, or using the value provided in \n`externalPriceAmount` or `openPriceAmount`.\n"
optionGroupPricingMode:
type: string
description: Information about how the modifier group affects the pricing of its parent item.
enum:
- INCLUDED
- FIXED_PRICE
- ADJUSTS_PRICE
- REPLACES_PRICE
- LOCATION_SPECIFIC_PRICE
externalPriceAmount:
description: 'The menu item price that was calculated by the
marketplace facilitator organization that created the
order.
`POST` only. The orders API does not include the
`externalPriceAmount` value in return data. It is
used to populate `receiptLinePrice`.
**Note**: you can only include this information if your
Toast API client is associated with a designated
marketplace facilitator organization. Most Toast API
clients do not create marketplace facilitator orders.
'
type: number
format: double
splitOrigin:
description: 'Reserved for future use.
'
type: object
$ref: '#/definitions/ExternalReference'
AppliedTaxRate:
type: object
description: A tax rate that is applied to an item or service charge.
required:
- taxRate
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
properties:
entityType:
description: The type of object this is.
type: string
taxRate:
type: object
$ref: '#/definitions/ToastReference'
name:
type: string
description: The name of the tax rate.
rate:
type: number
format: double
description: The tax rate, which can be a fixed amount, a percentage, or null.
taxAmount:
type: number
format: double
description: The tax amount that was actually applied.
type:
type: string
description: 'The type of the tax rate. Default is `PERCENT`.
The value `EXTERNAL` indicates that the tax is for a marketplace
facilitator order, and that the marketplace facilitator
organization calculated the tax amount.
'
enum:
- PERCENT
- FIXED
- NONE
- TABLE
- EXTERNAL
facilitatorCollectAndRemitTax:
type: boolean
description: 'Indicates 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 ident
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toast/refs/heads/main/openapi/toast-discounts-api-openapi.yml