--- title: "Provide information on a loyalty transaction" method: POST path: "/yourendpointname" --- # 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. * Signup to create a new 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`. ## Headers - `Toast-Transaction-GUID` string - `Toast-Restaurant-External-ID` string - `Toast-Transaction-Type` 'LOYALTY_INQUIRE' | 'LOYALTY_SEARCH' | 'LOYALTY_SIGNUP' | 'LOYALTY_REDEEM' | 'LOYALTY_ACCRUE' | 'LOYALTY_REVERSE' | 'LOYALTY_TRANSFER' - `Authorization` string ## Request body - LoyaltyTransaction — 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 `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_SIGNUP` - signupTransactionInformation * `LOYALTY_REDEEM` - checkTransactionInformation * `LOYALTY_ACCRUE` - checkTransactionInformation * `LOYALTY_REVERSE` - reverseTransactionInformation * `LOYALTY_TRANSFER` - transferTransactionInformation - `toastTransactionType` 'LOYALTY_INQUIRE' | 'LOYALTY_SEARCH' | 'LOYALTY_SIGNUP' | '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 — Information needed to complete a search transaction. Included if the toastTransactionType is LOYALTY_SEARCH, absent otherwise. - `searchCriteria` AccountSearchCriteria — 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. - `signupTransactionInformation` TransactionInformationSignup — Information needed to complete a signup transaction. Included if the toastTransactionType is LOYALTY_SIGNUP, absent otherwise. Requires exactly one of email or phone to be provided (not both, not neither). - `phone` string — A telephone number for the customer to create the loyalty account. This number will be ten digits with no other characters. Either phone or email must be provided, but not both. - `email` string — An email address for the customer to create the loyalty account. Either phone or email must be provided, but not both. - `checkTransactionInformation` TransactionInformationCheck — 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 — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `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` Selection[], required - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `item` ConfigReference, required — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `multiLocationId` unknown - `externalId` string — An external identifier that is prefixed by a naming authority. Deprecated for use in `ConfigReference`. - `itemGroup` ConfigReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `multiLocationId` unknown - `externalId` string — An external identifier that is prefixed by a naming authority. Deprecated for use in `ConfigReference`. - `optionGroup` ConfigReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `multiLocationId` unknown - `externalId` string — An external identifier that is prefixed by a naming authority. Deprecated for use in `ConfigReference`. - `preModifier` ConfigReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `multiLocationId` unknown - `externalId` string — An external identifier that is prefixed by a naming authority. Deprecated for use in `ConfigReference`. - `quantity` number, double, required — Quantity ordered. A decimal number for items sold by weight; a counting number for discrete items. - `unitOfMeasure` '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` 'NONE' | 'OPEN_ITEM' | 'SPECIAL_REQUEST' | 'PORTION' | 'HOUSE_ACCOUNT_PAY_BALANCE' — 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` ConfigReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `multiLocationId` unknown - `externalId` string — An external identifier that is prefixed by a naming authority. Deprecated for use in `ConfigReference`. - `appliedDiscounts` AppliedDiscount[] — The itemized discounts applied to this item. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `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 wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `triggers` AppliedDiscountTrigger[] — Optional items which triggered this discount. - `selection` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - … - `quantity` number, double — The amount of the selection used to trigger the applied discount. - `approver` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `processingState` '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. - `loyaltyDetails` LoyaltyDetails — Information about the loyalty program discount applied to a check. The loyalty program account is identified in the AppliedLoyaltyInfo value for the check. - `vendor` 'INTEGRATION', required — The specific loyalty program service provider that supports the loyalty account. - `referenceId` string, required — 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. - `comboItems` ExternalReference[] — A List of Menu Item Selections that this discount is applied to (empty for NonCombo Discounts). - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `appliedPromoCode` string — The promo code that was applied for this discount. - `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 — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `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` Selection[] — A list of modifiers applying to this selection. - `fulfillmentStatus` 'NEW' | '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. - `taxInclusion` '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` AppliedTaxRate[] — An array of AppliedTaxRate objects that contain information about tax payments made for the selection. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `taxRate` ToastReference, required — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `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` 'PERCENT' | 'FIXED' | 'NONE' | 'TABLE' | 'EXTERNAL' — The type of the tax rate. Default is percent if no tax rate config - `plu` string — The price look-up (PLU) code for the menu item selection used for pricing and inventory management. This value is null if the menu item does not have a PLU code configured. For information about configuring PLUs for menu items, see [Toast product documentation](https://doc.toasttab.com/doc/platformguide/platformMenuManagerWorkingWithMenuItems.html#platformMenuManagerSpecifyingAPluOrSkuForAMenuItem). - `appliedLoyaltyInfo` AppliedLoyaltyInfo — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `loyaltyIdentifier` string, required — An identifier for the loyalty program account. - `vendor` 'INTEGRATION', required — 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. - `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` AppliedServiceCharge[] — Any restaurant-configured service charges that applied to this check. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `chargeAmount` number, double — The final applied amount excluding tax. This is required if the amountType is OPEN. - `serviceCharge` ExternalReference, required — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `chargeType` '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` AppliedTaxRate[] — Derived from serviceCharge - the taxes applied to the service - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `taxRate` ToastReference, required — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `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` 'PERCENT' | 'FIXED' | 'NONE' | 'TABLE' | 'EXTERNAL' — The type of the tax rate. Default is percent if no tax rate config - `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` Payment[] — Payments made on this check - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `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` 'CASH' | 'CREDIT' | 'GIFTCARD' | 'HOUSE_ACCOUNT' | 'REWARDCARD' | 'LEVELUP' | 'OTHER' | 'UNDETERMINED', required — The payment method. - `cardEntryMode` 'SWIPED' | 'KEYED' | 'ONLINE' | 'EMV_CHIP_SIGN' | 'TOKENIZED' | 'PRE_AUTHED' | 'SAVED_CARD' | 'FUTURE_ORDER' | 'CONTACTLESS' | 'APPLE_PAY_CNP' | 'GOOGLE_PAY_CNP' | 'CLICK_TO_PAY_CNP' | 'INCREMENTAL_PRE_AUTHED' | 'PARTNER_ECOM_COF' — Indicates how credit card data was obtained. Response only. - `amount` number, double, required — The amount of this payment, excluding tips. - `tipAmount` number, double, required — The amount tipped on this payment. - `amountTendered` number, double — The amount tendered for this payment. - `cardType` 'VISA' | 'MASTERCARD' | 'AMEX' | 'DISCOVER' | 'JCB' | 'DINERS' | 'CIT' | 'MAESTRO' | 'LASER' | 'SOLO' | 'INTERAC' | '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. - `server` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `cashDrawer` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `refundStatus` 'NONE' | 'PARTIAL' | 'FULL' - `refund` Refund — 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. - `paymentStatus` 'OPEN' | 'PROCESSING' | 'AUTHORIZED_AT_RISK' | 'AUTHORIZED' | 'ERROR' | 'DENIED' | 'VOIDED_AT_RISK' | 'CANCELLED' | 'CAPTURE_IN_PROGRESS' | 'CAPTURED' | 'VOIDED' | 'PROCESSING_VOID' — The status of this payment when the type is CREDIT. - `voidInfo` VoidInformation — Information about a void applied to a check or item. - `voidUser` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `voidApprover` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `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 wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `houseAccount` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `otherPayment` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `createdDevice` Device — 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 - `lastModifiedDevice` Device — 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 - `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. - `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` '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` AppliedDiscount[] — The discounts applied to this check. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `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 wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `triggers` AppliedDiscountTrigger[] — Optional items which triggered this discount. - `selection` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `quantity` number, double — The amount of the selection used to trigger the applied discount. - `approver` ExternalReference — A wrapper object with fields that allow reference to a Toast entity by Toast GUID. - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `processingState` '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. - `loyaltyDetails` LoyaltyDetails — Information about the loyalty program discount applied to a check. The loyalty program account is identified in the AppliedLoyaltyInfo value for the check. - `vendor` 'INTEGRATION', required — The specific loyalty program service provider that supports the loyalty account. - `referenceId` string, required — 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. - `comboItems` ExternalReference[] — A List of Menu Item Selections that this discount is applied to (empty for NonCombo Discounts). - `guid` string, required — The GUID maintained by Toast. - `entityType` string, required — The type of object this is. - `externalId` string — External identifier string that is prefixed by the naming authority. - `appliedPromoCode` string — The promo code that was applied for this discount. - `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 *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 - `lastModifiedDevice` Device — 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 - `redemptions` Redemption[] — 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`. - `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` ItemRedemptionInfo[] — 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. - `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` unknown - `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. - `name` string — Human-readable name of the offer being redeemed. Used to identify the specific offer on POS, Kiosk, and Guest Display. Maximum 200 characters. - `reverseTransactionInformation` TransactionInformationReverse — 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` Redemption[] — 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. - `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` ItemRedemptionInfo[] — 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. - `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` unknown - `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. - `name` string — Human-readable name of the offer being redeemed. Used to identify the specific offer on POS, Kiosk, and Guest Display. Maximum 200 characters. - `transferTransactionInformation` TransactionInformationTransfer — 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. ## Response `200` OK. The `transactionStatus` value of the `LoyaltyTransactionResponse` object is `ACCEPT`. - LoyaltyTransactionResponse — 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_SIGNUP` - signupResponse * `LOYALTY_REDEEM` - checkResponse * `LOYALTY_ACCRUE` - checkResponse * `LOYALTY_REVERSE` - none * `LOYALTY_TRANSFER` - transferResponse - `transactionStatus` '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' | 'ERROR_ALREADY_REGISTERED' — Indicates the result of a loyalty transaction, reported by the loyalty service provider. Possible values are: - `searchResponse` ResponseSearch — 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` AccountInfo[] — A list of loyalty accounts that match the criteria from the search request. - `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. - `signupResponse` ResponseSignup — Response to a signup request. For a signup response this field is required. Contains the loyalty identifier of the newly created account. - `loyaltyIdentifier` string, required — The identifier of the loyalty account that was created. This identifier will be used in subsequent loyalty transactions to identify this account. - `checkResponse` ResponseCheck — 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 — 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. - `offers` Offer[] — An array of offers that are currently available to the holder of this account. - `identifier` string — A unique identifier for this offer. Each offer must have a unique identifier. The Toast platform will not apply discounts correctly if your integration uses an identifier for more than one offer on a check. - `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` '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` ItemRedemptionInfo[] — 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. - `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` unknown - `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` ExpirationData[] — 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. - `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` unknown - `description` string — Optional description providing additional context about the offer, such as requirements or restrictions. This text will be displayed on the Customer's Reward Screen to help guests understand offer eligibility before attempting redemption. Examples include "Requires additional purchase of $0.50" or "Valid on dine-in orders only". Maximum 200 characters. Optional. - `autoApply` boolean — Indicates whether the offer should be automatically applied to the check without requiring explicit action from a guest or employee. When `true`, the Toast platform will automatically apply the offer. If you do not provide an `autoApply` value, the Toast platform uses the default value `false`. This Toast platform feature is in limited release. Not all Toast POS locations will automatically apply offers in response to this value. - `rejectedRedemptions` RejectedRedemption[] — 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. - `redemption` Redemption, required — 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` ItemRedemptionInfo[] — 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. - `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` unknown - `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. - `name` string — Human-readable name of the offer being redeemed. Used to identify the specific offer on POS, Kiosk, and Guest Display. Maximum 200 characters. - `message` string — An explanation of why the discount was rejected. - `appliedRedemptions` Redemption[] — 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. - `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` ItemRedemptionInfo[] — 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. - `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` unknown - `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. - `name` string — Human-readable name of the offer being redeemed. Used to identify the specific offer on POS, Kiosk, and Guest Display. Maximum 200 characters. - `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!" - `redemptionLimit` RedemptionLimit — Controls the maximum number of rewards a guest can redeem for this check. When this object is present (non-`null`), the Toast POS enforces the limit you specify by disabling the ability to select additional rewards once the limit is reached. Guests can always deselect rewards to choose different ones. The effective limit accounts for rewards that are already applied. If you return `maxRedemptions` = 3 and the guest has 1 reward already applied, the guest can select 2 more rewards. When this object is absent or `null`, the Toast POS applies no redemption restrictions. The Toast POS does NOT validate that the `appliedRedemptions` array length matches the `maxRedemptions` value. You are responsible for ensuring consistency in your responses. If you send `maxRedemptions` = 2 but include 5 items in `appliedRedemptions`, the Toast POS may behave unexpectedly. This object applies to `LOYALTY_INQUIRE` responses. For other transaction types, this object should be absent or `null`. - `maxRedemptions` integer, nullable, required — The maximum number of rewards the guest may redeem for this check. **Required field**, but the value may be `null`. The meaning of each value: - `null`: Explicitly allow unlimited redemptions - `0`: No rewards can be redeemed - N (N > 0): Guest can redeem up to N rewards You must include this field when providing a `RedemptionLimit` object. You can adjust this value on each `LOYALTY_INQUIRE` response based on business rules specific to your loyalty program. - `transferResponse` ResponseTransfer — 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. ## Other responses - `400` — 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` * `ERROR_ALREADY_REGISTERED` - `500` — Internal server error. --- [API](https://skmtc.dev/toasttab/apis/toast-loyalty-integration-api.md) · [All operations](https://skmtc.dev/toasttab/apis/toast-loyalty-integration-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/toasttab/toast-loyalty-integration-api/revisions/758a34fa6bd3/schema)