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.

This section provides reference information about the endpoints and data types of the Toast loyalty program API specification. You implement the Toast loyalty program API so that the Toast POS system can make calls to your loyalty program service when it performs loyalty program transactions. For more information about implementing a Toast loyalty program integration and code examples, see Loyalty program integration overview.

Toast Loyalty Integration API

Base URL: /yourapiname/v1, Version: 1.1.0

This API specification describes the interface that the Toast POS system will call when it processes loyalty transactions.

Implement this REST API to allow the Toast POS system to process loyalty transactions using a loyalty provider that it does not currently support.

Default request content-types: application/json
Default response content-types: application/json
Schemes: https

Summary

Path Operation Description
/yourendpointname POST

Provide information on a loyalty transaction

Paths

Provide information on a loyalty transaction

POST /yourendpointname

Provides information about a loyalty transaction processed by the Toast platform. The transaction information in the message body is intended to allow a loyalty provider to perform corresponding operations on the loyalty account, maintained by that provider.

You define the endpoint name for this implementation. The Toast POS system makes requests to the REST path that you supply during integration setup.

Each POST request to the endpoint includes a Toast-Transaction-Type header parameter value to indicate the type of loyalty transaction it represents. The possible transaction types are:

  • Inquire to get information about a given loyalty account given the items currently on the check.
  • Search for a loyalty account.
  • Redeem offers.
  • Accrue rewards based on a given check.
  • Reverse a previous redeem or accrue transaction.

The LoyaltyTransaction object in the message body includes a set of information that is specific for each transaction type.

The response time for a loyalty transaction request must be less than 500ms on average. A response time of greater than 5000ms will be considered a timeout and will be retried. There is a limit on the number of retries which depends on the context of the call.

All loyalty transactions must be considered idempotent. The implementation must handle multiple requests with the same Toast-Transaction-GUID and the same loyaltyIdentifier.

Uses default content-types: application/json

A LoyaltyTransaction object containing information about the loyalty transaction that the Toast POS system processed.

Toast-Transaction-GUID

A unique identifier of the loyalty transaction, defined by the Toast POS system.

header string
Toast-Restaurant-External-ID

The unique identifier of the restaurant, defined by the Toast POS system.

header string
Toast-Transaction-Type

The type of loyalty transaction that occurred. Values are:

  • LOYALTY_INQUIRE
  • LOYALTY_SEARCH
  • LOYALTY_REDEEM
  • LOYALTY_ACCRUE
  • LOYALTY_REVERSE
  • LOYALTY_TRANSFER
header string , x ∈ { LOYALTY_INQUIRE , LOYALTY_SEARCH , LOYALTY_REDEEM , LOYALTY_ACCRUE , LOYALTY_REVERSE , LOYALTY_TRANSFER }
Authorization

A JSON Web Token (JWT) that you can use to authenticate the request. Verify the token using the public key that you get from the Toast user management service.

header string

application/json

200 OK

OK. The transactionStatus value of the LoyaltyTransactionResponse object is ACCEPT.

400 Bad Request

Bad request. The transactionStatus value of the LoyaltyTransactionResponse object is one of:

  • ERROR_INVALID_TOAST_TRANSACTION_TYPE
  • ERROR_ACCOUNT_INVALID
  • ERROR_INVALID_INPUT_PROPERTIES
  • ERROR_TRANSACTION_DOES_NOT_EXIST
  • ERROR_INVALID_TOKEN
  • ERROR_TRANSACTION_CANNOT_BE_REVERSED
  • ERROR_INVALID_RESTAURANT
500 Internal Server Error

Internal server error.

Schema definitions

AccountInfo: object

Identifying information about a specific loyalty account.

identifier: string

A unique identifer for this account.

firstName: string

First or given name of the account holder

lastName: string

Last or family name of the account holder

phone: string

Phone number of the account holder

email: string

Email address of the account holder

pointsBalance: string

If the loyalty program tracks points, use this field to report the current points available to the account owner. This field only displays on the POS in LOYALTY_INQUIRE workflows. If absent, no value is displayed. Optional.

AccountSearchCriteria: object

A set of possible criteria to be used to search for a given loyalty account. The provider must return a list of loyalty accounts that match the criteria given so the customer can select the correct one. All of the fields are optional, though at least one will be populated.

firstName: string

The first or given name of the customer attached to the loyalty account.

lastName: string

The last or family name of the customer attached to the loyalty account.

email: string

An email address for the customer attached to the loyalty account.

phone: string

A telephone number for the customer attached to the loyalty account. This number will be ten digits with no other characters.

AppliedDiscount:

A discount applied to a check or item. The Toast POS system calculates service charges before applying discounts. The system calculates tax after applying discounts. In a POST request, the type of the discount must be fixed amount or fixed percentage, and the discount must be applied to a check. See Applying Discounts to a Check in an Order.

name: string

The name of the applied discount.

discountAmount: number (double)

The discount amount in USD. This amount will be subtracted from the check or item.

nonTaxDiscountAmount: number (double)

The amount that a discount reduces a menu item price, excluding any discount amount applied to taxes. In most cases, a discount only applies to the menu item price and the nonTaxDiscountAmount is the same as the discountAmount. If you apply a discount to a menu item that includes tax in its price, the nonTaxDiscountAmount is less than the full discount amount.

discount: ToastReference

A GUID reference to the discount configured for the restaurant.

triggers: object[]

Optional items which triggered this discount.

approver: ExternalReference

The user who approved the discount.

processingState: string , x ∈ { PENDING_APPLIED , APPLIED , PENDING_VOID , VOID }

Applies to loyalty program discounts only. Loyalty program reward discounts are validated and then applied, or redeemed, by the third-party loyalty program service provider depending on the state of the Toast POS order. This value indicates the state of the discount in that validation and application process. Response only. The processingState may be one of the following enumerated values.

  • PENDING_APPLIED - The loyalty program service provider has confirmed that the reward discount is valid for the order and customer. The reward has not been redeemed, or applied to the customer's loyalty account.
  • APPLIED - The reward discount has been redeemed. The reward is no longer available from the customer's loyalty program account.
  • PENDING_VOID - The reward discount has been removed from the Toast POS order. The reward is not available from the customer's loyalty program account until the loyalty program service provider processes the void operation.
  • VOID - The reward discount has been removed from the Toast POS order and the reward is available from the customer's loyalty program account again.
loyaltyDetails: LoyaltyDetails

Information about the customer loyalty program discount being applied to the check.

comboItems: object[]

A List of Menu Item Selections that this discount is applied to (empty for NonCombo Discounts).

appliedPromoCode: string

The promo code that was applied for this discount.

AppliedDiscountTrigger: object

The Selection which triggered the application of this discount

selection: ExternalReference
quantity: number (double)

The amount of the selection used to trigger the applied discount.

AppliedLoyaltyInfo:

Information about the customer loyalty program account associated with a check.

loyaltyIdentifier: string

An identifier for the loyalty program account.

vendor: string , x ∈ { INTEGRATION }

The specific loyalty program service provider that supports the loyalty account. For all interactions with the Loyalty Integration API, this value will be INTEGRATION.

accrualFamilyGuid: string

An internal Toast POS identifier for loyalty program transactions.

accrualText: string

A description of the loyalty program transaction that will be printed on the customer's reciept. For example, "Earned 27 points." The maximum length of the description string is 255 characters.

AppliedServiceCharge:

A percentage/open/fixed service charge added to a check which could represent in general an upcharge like a gratuity or delivery fee. Whether the upcharge is taxable is defined in the restaurant-configured serviceCharge. The fields on the AppliedServiceCharge are computed based on the referenced ServiceCharge configuration.

chargeAmount: number (double)

The final applied amount excluding tax. This is required if the amountType is OPEN.

serviceCharge: ExternalReference

A reference to the restaurant-configured service charge. If a service charge is taxable, the tax amount will be applied to the check.

chargeType: string , x ∈ { FIXED , PERCENT , OPEN }

Derived from serviceCharge. An OPEN service charge can either be a dollar amount or a percentage.

name: string

Derived from serviceCharge - the configured human readable label for the service charge.

delivery: boolean

Derived from serviceCharge - whether this service charge is a delivery charge.

gratuity: boolean

Derived from serviceCharge - whether this service charge is a gratuity. Can be used to derive required tip amount on the check.

taxable: boolean

Derived from serviceCharge - whether this service charge is taxable.

appliedTaxes: object[]

Derived from serviceCharge - the taxes applied to the service

AppliedTaxRate:

A tax rate applied to an Item or ServiceCharge.

entityType: string

The type of object this is.

taxRate: ToastReference
name: string

The name of the tax rate.

rate: number (double)

The tax rate, which can be a fixed amount, a percentage, or null.

taxAmount: number (double)

The tax amount that was actually applied.

type: string , x ∈ { PERCENT , FIXED , NONE , TABLE }

The type of the tax rate. Default is percent if no tax rate config

Check:

Represents a single check within an order.

openedDate: string (date-time)

The date at which this check was opened. Use ISO 8601 date and time format for all Toast APIs.

closedDate: string (date-time)

The most recent date at which this check's payment status was set to CLOSED. Use ISO 8601 date and time format for all Toast APIs.

modifiedDate: string (date-time)

The most recent date at which this check was modified. Use ISO 8601 date and time format for all Toast APIs.

deletedDate: string (date-time)

The date at which this check was deleted. deletedDate is only applicable when deleted is true (by default the value will be set to 1970-01-01T00:00:00.000+0000). Use ISO 8601 date and time format for all Toast APIs.

deleted: boolean

True if this check has been deleted.

selections: object[]
customer: Customer
appliedLoyaltyInfo: AppliedLoyaltyInfo

Information about the customer loyalty program account associated with the check. Used to accrue loyalty program benefits and to redeem loyalty program discounts.

taxExempt: boolean

True if this check is tax exempt. Tax exempt number is not yet supported.

displayNumber: string

Generally starts at one each day and counts up. Not guaranteed to be unique.

appliedServiceCharges: object[]

Any restaurant-configured service charges that applied to this check.

amount: number (double)

The dollar amount due on this check in USD, after discounts but before tax.

taxAmount: number (double)

The computed tax amount in USD. Includes service charge and item level taxes.

totalAmount: number (double)

The total amount due on this check in USD, including discounts and taxes.

payments: object[]

Payments made on this check

tabName: string

The name of the tab on this check. This will show up on the KDS (Kitchen Display System) for pending orders. The tabName's length can be up to 255 characters.

paymentStatus: string , x ∈ { OPEN , PAID , CLOSED }

The payment status of this check. OPEN means there is outstanding balance. PAID means a credit card payment has been applied but the tip has not been adjusted. CLOSED means there is no remaining amount due on this check. Toast does not prevent a CLOSED check from transitioning back to OPEN or PAID.

appliedDiscounts: object[]

The discounts applied to this check.

voided: boolean

True if this check has been voided.

voidDate: string (date-time)

The date at which this check was voided. Use ISO 8601 date and time format for all Toast APIs.

voidBusinessDate: integer

The business date (yyyyMMdd) on which this check was voided.

paidDate: string (date-time)

The most recent date at which this check received payment. Use ISO 8601 date and time format for all Toast APIs.

createdDevice: Device

The Toast POS device that created the check. This value is null if the check was not created using a Toast POS device.

lastModifiedDevice: Device

The Toast POS device that modified the check most recently. This value is null if the check has not been modified using a Toast POS device. If the check is modified but the modificiation is not made using a Toast POS device, this value does not change.

ConfigReference:

A wrapper object containing identifier values for Toast platform entities.

multiLocationId: object

A consistent identifier for Toast platform entities, such as menu items, that applies to all versions of a shared entity at all locations in a restaurant group. For example, you can use the multiLocationId value to identify menu entities that are versions of a shared menu entity. The multiLocationId value in the orders API corresponds to the masterId value for menu configuration entities in the menus API. For more information about the menus API masterId value, see the Toast Developer Guide. type: string

externalId: string

An external identifier that is prefixed by a naming authority. Deprecated for use in ConfigReference.

Customer:

firstName: string
lastName: string
phone: string
email: string

DeliveryInfo: object

Required if the dining option behavior is DELIVERY

address1: string

The first line of the street address of the delivery destination.

address2: string

The second line of the street address of the delivery destination.

city: string

The name of the city or town of the delivery destination.

state: string (ISO 3166-2)

The postal abbreviation of the state or province of the delivery destination. The abbreviation must be in ISO 3166-2 format (two capital letters).

zipCode: string

The postal or zip code of the delivery destination.

latitude: number (double)

The north/south geographic coordinate of the delivery destination, in decimal format.

longitude: number (double)

The east/west geographic coordinate of the delivery destination, in decimal format.

notes: string

Additional instructions or information about the delivery.

deliveredDate: string (date-time)

The date and time that the delivery employee indicated that the order was delivered in the Toast POS. Response only. This value is only set when the dining option for the order is DELIVERY. For other dining options, the value is null. Use ISO 8601 date and time format for all Toast APIs.

dispatchedDate: string (date-time)

The date and time that the restaurant indicated that the order was available for delivery and assigned to a delivery employee in the Toast POS. This value is only set when the dining option for the order is DELIVERY. For other dining options, the value is null. Use ISO 8601 date and time format for all Toast APIs.

deliveryEmployee: ExternalReference

The Toast GUID or external identifier of the delivery employee.

Device: object

The Device ID value that the Toast POS system 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, do the following. From the overflow menu (⋮) select Device Status and then select the Device tab.

id: string

The physical id of the device

ExpirationData: object

If an offer will expire, this can detail information of when that offer is set to expire.

date: string (date-time)

The date at which the offer will expire. Optional. Use ISO 8601 date and time format for all Toast APIs.

quantity: object (number)

The quantity of the offer that will expire at the expiration date. If not present assumes the entire offer will expire at the expiration date. Optional.

ExternalReference:

A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.

externalId: string

External identifier string that is prefixed by the naming authority.

ItemRedemptionInfo: object

Information about the application of a Redemption to a specific item.

selectionIdentifier: string

The identifier of the selection that discount is applied to. This will correspond to the guid field on the Selection object that is included with the Check. Toast uses these values to determine which item(s) will have the offer applied.

amount: number

The currency amount of the discount applied to this item. This value can be updated in future calls. This field is optional in response to LOYALTY_INQUIRE requests and required in response to LOYALTY_REDEEM requests.

appliedDiscountIdentifier: object

If this redemption has been applied, this is the identifier of the applied discount created for this offer on this selection. It will correspond to the guid field of the AppliedDiscount object on the Selection. Response only.

LoyaltyDetails: object

Information about the loyalty program discount applied to a check. The loyalty program account is identified in the AppliedLoyaltyInfo value for the check.

vendor: string , x ∈ { INTEGRATION }

The specific loyalty program service provider that supports the loyalty account.

referenceId: string

The identifier of the loyalty program discount that is recognized by the loyalty program service provider. The Toast POS transmits the discount identifier to the service provider to determine the validity and amount of the discount.

LoyaltyTransaction: object

Information about a loyalty transaction in the Toast POS system. Loyalty providers are expected to handle that transaction.

The set of information in this object depends on the loyalty transaction type. The transaction type is specified in the Toast-Transaction-Type header parameter for the request, and within the body of the request.

The LoyaltyTransaction object includes the the toastTransactionType value, which will be the same as the value in the header. It will also include one of the following values depending on the transaction type:

  • LOYALTY_INQUIRE - checkTransactionInformation
  • LOYALTY_SEARCH - searchTransactionInformation
  • LOYALTY_REDEEM - checkTransactionInformation
  • LOYALTY_ACCRUE - checkTransactionInformation
  • LOYALTY_REVERSE - reverseTransactionInformation
  • LOYALTY_TRANSFER - transferTransactionInformation
toastTransactionType: string , x ∈ { LOYALTY_INQUIRE , LOYALTY_SEARCH , LOYALTY_REDEEM , LOYALTY_ACCRUE , LOYALTY_REVERSE , LOYALTY_TRANSFER }

The transaction type that is included in the header is duplicated here in the body of the request.

searchTransactionInformation: TransactionInformationSearch
checkTransactionInformation: TransactionInformationCheck
reverseTransactionInformation: TransactionInformationReverse
transferTransactionInformation: TransactionInformationTransfer

LoyaltyTransactionResponse: object

Information about a loyalty transaction from the loyalty provider. The Toast POS system uses this information to complete guests' loyalty transactions.

The set of information in this object depends on the loyalty transaction type. The transaction type is specified in the Toast-Transaction-Type header parameter for the request.

All LoyaltyTransactionResponse objects must include a transactionStatus value. The object must include one of the following additional values depending on the transaction type:

  • LOYALTY_INQUIRE - checkResponse
  • LOYALTY_SEARCH - searchResponse
  • LOYALTY_REDEEM - checkResponse
  • LOYALTY_ACCRUE - checkResponse
  • LOYALTY_REVERSE - none
  • LOYALTY_TRANSFER - transferResponse
transactionStatus: string , x ∈ { ACCEPT , ERROR_INVALID_TOAST_TRANSACTION_TYPE , ERROR_ACCOUNT_INVALID , ERROR_INVALID_INPUT_PROPERTIES , ERROR_TRANSACTION_DOES_NOT_EXIST , ERROR_INVALID_TOKEN , ERROR_TRANSACTION_CANNOT_BE_REVERSED , ERROR_INVALID_RESTAURANT , ERROR_INVALID_TRANSFER }

Indicates the result of a loyalty transaction, reported by the loyalty service provider. Possible values are:

  • ACCEPT - The loyalty service provider processed the transaction successfully.
  • ERROR_INVALID_TOAST_TRANSACTION_TYPE - The requested Toast-Transaction-Type is not valid.
  • ERROR_ACCOUNT_INVALID - The loyalty account is not recognized or is not valid at the current restaurant.
  • ERROR_INVALID_INPUT_PROPERTIES - The specified JSON properties in the request body are not valid.
  • ERROR_TRANSACTION_DOES_NOT_EXIST - The transaction that is being requested to be reversed does not exist. Only occurs on a LOYALTY_REVERSE transaction.
  • ERROR_INVALID_TOKEN - The token supplied in the Authorization header field is invalid or cannot be validated.
  • ERROR_TRANSACTION_CANNOT_BE_REVERSED - The specified transaction cannot be reversed. Only LOYALTY_REDEEM and LOYALTY_ACCRUE transactions can be reversed.
  • ERROR_INVALID_RESTAURANT - The restaurant specified by the Toast-Restaurant-External-ID is invalid.
  • ERROR_INVALID_TRANSFER - The cards that is being requested to be Transfer could not be completed.
searchResponse: ResponseSearch
checkResponse: ResponseCheck
transferResponse: ResponseTransfer

Offer: object

Information about a potential discount or other benefit available to the holder of a loyalty account. Contrast with a Redemption, which is an Offer that is applied to a Check.

identifier: string

A unique identifier for this offer.

name: string

The name of this discount. This should be a human readable description of the order. Examples include "5% off your entire order" or "Free small cheese pizza".

applicable: boolean

true if this offer can be applied to the check submitted with the request, false otherwise

selectionType: string , x ∈ { CHECK , ITEM , MULTI_ITEM }

Describes what this offer covers. A CHECK level discount applies to the entire check, without requirements on the items contained within the check. An ITEM level discount applies to a specific item on the check.

itemApplication: object[]

If this offer is of type ITEM or MULTI_ITEM, this array includes the selection or selections to which the offer can be applied. Required if applicable is true, optional otherwise.

amount: number

The currency amount of the discount when applied based on the current check information. This value can be updated in future calls based on updated check information (for example, a 10% off offer will change based on the check total). This field is optional in response to LOYALTY_INQUIRE requests and required in response to LOYALTY_REDEEM requests. If the selection type is ITEM or MULTI_ITEM, this amount should be the sum of the amounts on each ItemRedemptionInfo in the itemApplication array.

quantity: number

The quantity of this reward available to the account owner. This is informational to display to the user. It does not necessarily mean the offer is redeemable multiple times (for example, a guest may have two "10% off your entire check" offers, but only one can be redeemed per visit).

expiration: object[]

If this offer will expire, expiration dates can be included in this element to indicate on which date(s) this offer will expire. The next upcoming expiration date will be displayed for the offer on the POS. Optional.

Payment:

Defines a payment.

paidDate: string (date-time)

The date at which the payment was made. Use ISO 8601 date and time format for all Toast APIs.

paidBusinessDate: integer

The business date (yyyyMMdd) on which this payment was first applied.

type: string , x ∈ { CASH , CREDIT , GIFTCARD , HOUSE_ACCOUNT , REWARDCARD , LEVELUP , OTHER , UNDETERMINED }

The payment method.

cardEntryMode: string , x ∈ { SWIPED , KEYED , ONLINE , EMV_CHIP_SIGN , TOKENIZED , PRE_AUTHED , SAVED_CARD , FUTURE_ORDER , CONTACTLESS , APPLE_PAY_CNP , GOOGLE_PAY_CNP , INCREMENTAL_PRE_AUTHED , PARTNER_ECOM_COF }

Indicates how credit card data was obtained. Response only.

amount: number (double)

The amount of this payment, excluding tips.

tipAmount: number (double)

The amount tipped on this payment.

amountTendered: number (double)

The amount tendered for this payment.

cardType: string , x ∈ { VISA , MASTERCARD , AMEX , DISCOVER , JCB , DINERS , CIT , MAESTRO , LASER , SOLO , UNKNOWN }

The type of card used.

last4Digits: string

The last 4 digits of the card used.

originalProcessingFee: number (double)

The original processing fee for this payment. The original processing fee value is populated after the payment has been captured.

cashDrawer: ExternalReference

A reference to the cashDrawer used to receive this payment.

refundStatus: string , x ∈ { NONE , PARTIAL , FULL }
refund: Refund
paymentStatus: string , x ∈ { OPEN , PROCESSING , AUTHORIZED_AT_RISK , AUTHORIZED , ERROR , DENIED , VOIDED_AT_RISK , CANCELLED , CAPTURE_IN_PROGRESS , CAPTURED , VOIDED }

The status of this payment when the type is CREDIT.

voidInfo: VoidInformation

If the payment was voided, this will contain information on who did it and when.

houseAccount: ExternalReference

A reference to the houseAccount associated with this payment, if any.

otherPayment: ExternalReference

Required when the payment type is OTHER. A reference to an alternative payment method configured by the restaurant.

createdDevice: Device

The Toast POS device that created the payment. This value is null if the payment was not created using a Toast POS device.

lastModifiedDevice: Device

The Toast POS device that modified the payment most recently. This value is null if the payment has not been modified using a Toast POS device. If the payment is modified but the modificiation is not made using a Toast POS device, this value does not change.

mcaRepaymentAmount: number (double)

The total currency amount withheld as repayment for a merchant cash advance (MCA). The MCA repayment amount is set at the time the payment is captured, and then updated when settlement occurs.

Redemption: object

Information about an offer to be redeemed (or that was redeemed) to a check.

identifier: string

Identifier of the Offer to be redeemed. The Offer must be one that was returned by the provider in response to an inquiry request.

selectionGuid: string

If this is an item level discount, the guid of the selection that this redemption is attached to. If this redemption has not been added to a specific selection yet, this field will be absent.

appliedDiscountGuid: string

The GUID of the AppliedDiscount on the Check or Selection object corresponding to the discount. This is required if the Redemption object is contained within the RejectionRedemption object and identifies the rejected redemption. This is included to differentiate if multiple redemptions of the same type are applied to the same check or item.

multiItemDiscountGuid: string

The GUID of a Multi Item Redemption. A Multi Item Redemption is a single loyalty redemption that applied to multiple items on the check. For instance, a "$3 off burgers, $2 off fries, and $1 off a drink" would be a single loyalty redemption that applies to 3 separate items. This field is an identifier for a Multi Item redemption, but does not correspond to any one object on the Check. To see what items were discounted, refer to the itemApplication field.

amount: number

The dollar (or other currency) amount that this offer actually discounts.

itemApplication: object[]

If this offer this object is redeeming is of type MULTI_ITEM, this array includes the selections to which the offer has been applied, along with the amounts applied to each selection and the identifier of the discounts applied to each selection. If this field is present, the selectionGuid, appliedDiscountGuid, and amount fields will be null, as the values in this array convey that information.

quantity: number

The number of times the offer has been applied to the item or check. For example, if an offer is a stackable "$5 off check" discount, this field could indicate that multiple copies of that offer have been applied.

Refund: object

A discount applied to a check or item.

refundAmount: number (double)

The amount of the refund excluding the tip.

tipRefundAmount: number (double)

The amount of the tip refund.

refundDate: string (date-time)

The date and time the refund was made. Use ISO 8601 date and time format for all Toast APIs.

refundBusinessDate: integer

The business date (yyyyMMdd) on which this refund was created.

RejectedRedemption: object

A redemption that was included in a list of redemptions to redeem, but is not valid based on the partner's validation logic.

redemption: Redemption
message: string

An explanation of why the discount was rejected.

ResponseCheck: object

Response to an inquire, redeem, or accure request. For an inquire response this field is requried. For all other responses it is optional unless any of the redemptions were rejected. If the account corresponding to the identifier was not found, the service should return a 404 response.

accountInfo: AccountInfo
offers: object[]

An array of offers that are currently available to the holder of this account.

rejectedRedemptions: object[]

A list of redemptions that were submitted as part of a LOYALTY_INQUIRE or LOYALTY_REDEEM request that are not valid for the given loyalty account and the contents of the check.

appliedRedemptions: object[]

A list of redemptions that were submitted as part of a LOYALTY_INQUIRE or LOYALTY_REDEEM request that are valid for the given loyalty account and the contents of the check. For item level redemptions the selectionGuid will be set to indicate which item it applies to.

userMessage: string

An optional message to be relayed to the guest at the restaurant. Examples could include "Visit http://www.website.com to check your points balance" or "You will accrue 15 points with this transaction!"

ResponseSearch: object

Response to a search request. Contains the array of account information matching the search criteria. If no matching accounts were found, the service should return a 404 response.

accounts: object[]

A list of loyalty accounts that match the criteria from the search request.

ResponseTransfer: object

Response to a transfer request. For a transfer response this field is required. Contains the loyalty identifier that the old account transferred to.

loyaltyIdentifier: string

A unique identifier for the new account.

Selection:

A Selection object can represent either a primary item (i.e. Check.selections) or a modifier (Selection.modifiers) selection. Quantity defaults to 1.

Specify a modifier selection by adding it to the modifiers list of another selection. For each modifier selection, its optionGroup field must be set correctly, because a MenuItem can be included in multiple MenuOptionGroups, potentially with different prices or sizing.

item: ConfigReference

A reference to the selected MenuItem.

itemGroup: ConfigReference

A reference to the MenuGroup from which the item was selected.

optionGroup: ConfigReference

A reference to the modifier group from which the menu item was selected. Only applies if this is a modifier selection.

preModifier: ExternalReference

A reference to the selected pre-modifier.

quantity: number (double)

Quantity ordered. A decimal number for items sold by weight; a counting number for discrete items.

unitOfMeasure: string , x ∈ { NONE , LB , OZ , KG , G }

The unit of measure required for weighing the item. Default is NONE, which means the item is not meant to be weighed.

selectionType: string , x ∈ { NONE , OPEN_ITEM , SPECIAL_REQUEST , PORTION }

Specifies whether this selection is a special request or other off-menu sale. If left null or NONE, describes a normal modifier or item selection.

salesCategory: ExternalReference

A reference to the salesCategory of the item.

appliedDiscounts: object[]

The itemized discounts applied to this item.

deferred: boolean

Whether this selection is a deferred revenue transaction, e.g. gift card sales.

preDiscountPrice: number (double)

Gross sale price for this selection. Excludes tax.

price: number (double)

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.

tax: number (double)

The total tax amount for this selection.

voided: boolean

True if this selection has been voided.

voidDate: string (date-time)

The date at which this selection was voided. Use ISO 8601 date and time format for all Toast APIs.

voidBusinessDate: integer

The business date (yyyyMMdd) on which this selection was voided.

voidReason: ExternalReference

If voided is true, a reference to the voidReason.

displayName: string

The display name of the selection. This field can be used to set a special request value, otherwise it will be generated from this Selection's item property.

createdDate: string (date-time)

The date at which this selection was created. Defaults to current time if not specified. Use ISO 8601 date and time format for all Toast APIs.

modifiedDate: string (date-time)

The date at which this selection was last modified. Defaults to current time if not specified. Use ISO 8601 date and time format for all Toast APIs.

modifiers: object[]

A list of modifiers applying to this selection.

fulfillmentStatus: string , x ∈ { NEW (default) , HOLD , SENT , READY }

Indicates the stage of the preparation workflow that the menu item selection is in. The fulfillmentStatus of a menu item selection changes as restaurant employees move the item through the functions of the Toast POS, for example order entry and the kitchen display system (KDS). Response only.

  • NEW - the menu item selection has been added to a check but has not been sent to the KDS for preparation.
  • HOLD - a restaurant employee has paused the menu item selection so that it does not appear in the KDS for preparation.
  • SENT - the menu item selection has been fired and appears in the KDS for preparation.
  • READY - preparation is complete, the menu item selection has been fulfilled and no longer appears in the KDS. If your restaurant does not use the Toast POS KDS, items in an order will not reach the READY status.
taxInclusion: string , x ∈ { INCLUDED , NOT_INCLUDED , INHERITED }

Indicates whether the menu item price includes one or more tax amounts. If the menu item is a modifier for another menu item selection, it always inherits the tax inclusion behavior of the menu item it applies to. Values 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.
appliedTaxes: object[]

An array of AppliedTaxRate objects that contain information about tax payments made for the selection.

ToastReference: object

A wrapper object with fields that allow reference to a Toast entity by Toast GUID.

guid: string

The GUID maintained by Toast.

entityType: string

The type of object this is.

TransactionInformationCheck: object

Information needed to complete an inquire, redeem, or accrue transaction. Included if the toastTransactionType is one of LOYALTY_INQUIRE, LOYALTY_REDEEM, or LOYALTY_ACCRUE, absent otherwise.

loyaltyIdentifier: string

Unique identifier of the loyalty account. Format will vary by provider.

orderGuid: string

The Toast POS system identifier for the order that contains the check.

check: Check
redemptions: object[]

List of offers to be redeemed, or already redeemed on a check. If this is the first time this particular Redemption has been present in a request (as part of this customer interaction), it will be present in this list but not on the Check. If a Redemption has been previously validated, it will be present both in this list and on the Check as an AppliedDiscount.

TransactionInformationReverse: object

Information needed to complete a reverse transaction. Included if the toastTransactionType is LOYALTY_REVERSE, absent otherwise.

loyaltyIdentifier: string

Unique identifier of the loyalty account. Format will vary by provider.

transactionId: string

Id of a previous transaction to reverse.

redemptions: object[]

If the transaction to be reversed was a LOYALTY_REDEEM transaction, this array optional includes the list of redemptions from that transaction to reverse. If this field is absent, all redemptions from the transaction should be reversed.

TransactionInformationSearch: object

Information needed to complete a search transaction. Included if the toastTransactionType is LOYALTY_SEARCH, absent otherwise.

searchCriteria: AccountSearchCriteria

TransactionInformationTransfer: object

Information needed to complete a transfer transaction. Included if the toastTransactionType is LOYALTY_TRANSFER, absent otherwise.

fromLoyaltyIdentifier: string

Unique identifier of the current loyalty account. Format will vary by provider.

toLoyaltyIdentifier: string

Unique identifier of the loyalty account that the user wants to transfer to. Format will vary by provider.

VoidInformation: object

Information about a void applied to a check or item.

voidUser: ExternalReference

The user who voided the order.

voidApprover: ExternalReference

The user who approved the void.

voidDate: string (date-time)

The date at which the refund was made. Use ISO 8601 date and time format for all Toast APIs.

voidBusinessDate: integer

The business date (yyyyMMdd) on which this void was made.

voidReason: ExternalReference

A reference to the configured voidReason that this void corresponds to.