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.

Redeem

The redeem workflow occurs when the Toast platform processes a guest payment and completes a purchase transaction.

The redeem transaction follows the final inquire transaction during the payment process of the guest purchase transaction.

Redeem workflow

  1. The POS sends a redeem request. The request body includes a TransactionInformationCheck object holding the following information:

    • The loyalty program account information that identifies the guest.

    • The restaurant check for the guest. The check might include menu item selections or have no selections. The check might include loyalty program offers that have been applied.

  2. Your loyalty program integration responds to the redeem request. The request body might include a ResponseCheck object holding the following information:

    • A list of offers that are currently applied to the check that are not valid. The POS will remove those offers from the check.

  3. The POS processes the payment and completes the guest transaction.

Note

The Toast platform does not process rewards offer redemptions when a restaurant experiences an Internet outage or other network disruption. When a restaurant does not have a functioning network, it is in offline mode. For more information, see Offline Mode.

Loyalty redeem request

{
  "toastTransactionType":"LOYALTY_REDEEM",
  "searchTransactionInformation":null,
  "checkTransactionInformation":{
    "loyaltyIdentifier":"3",
    "check":{
      "guid":"c79ecf26-1540-486c-9aee-e10ef34e228e",
      "entityType":null,
      "externalId":null,
      "displayNumber":"3002",
      "payments":[],
      "appliedDiscounts":[
        {
          "guid":"5318bf86-505a-43fe-91ad-feb6fe6e0ad2",
          "entityType":"AppliedLoyaltyProviderDiscount",
          "approver":{
            "guid":"915ae2ef-a59a-44dd-bea3-a23977cf5e26",
            "entityType":"RestaurantUser",
            "externalId":"100000000100005200"
          },
          "processingState":"PENDING_APPLIED",
          "loyaltyDetails":{
            "vendor":null,
            "referenceId":"1"
          },
          "name":"reward 1",
          "comboItems":[],
          "discountAmount":5,
          "discount":{
            "guid":"e7b9fc51-bb27-47c5-b3e8-c5c47600380e",
            "entityType":"CustomDiscount"
          },
          "nonTaxDiscountAmount":null,
          "triggers":[],
          "appliedPromoCode":null
        }
      ],
      "lastModifiedDevice":null,
      "voidDate":null,
      "paidDate":null,
      "appliedLoyaltyInfo":{
        "guid":null,
        "entityType":null,
        "accrualText":null,
        "accrualFamilyGuid":null,
        "vendor":null,
        "loyaltyIdentifier":"3"
      },
      "voided":false,
      "paymentStatus":"OPEN",
      "amount":38.96,
      "tabName":"jack williams",
      "taxExempt":false,
      "openedDate":1549306677657,
      "totalAmount":41.4,
      "selections":[
        {
          "guid":"dfa59529-c3d1-4dff-967d-12e19525f749",
          "entityType":null,
          "externalId":null,
          "deferred":false,
          "preDiscountPrice":43.96,
          "voidReason":null,
          "optionGroup":null,
          "displayName":"Crab Cakes",
          "appliedDiscounts":[],
          "modifiers":[],
          "voidDate":null,
          "fulfillmentStatus":"SENT",
          "salesCategory":null,
          "selectionType":null,
          "price":38.96,
          "voided":false,
          "appliedTaxes":[
            {
              "guid":null,
              "entityType":"AppliedTaxRate",
              "taxRate":{
                "guid":"78aca305-6fbc-42ea-a85b-1671c52367eb",
                "entityType":"TaxRate"
              },
              "rate":0.0625,
              "name":"MA Tax",
              "taxAmount":2.44,
              "type":"PERCENT"
            }
          ],
          "itemGroup":{
            "guid":"15694864-225d-4b47-a60b-b9c20986b0af",
            "entityType":"MenuGroup",
            "externalId":"100000000100004070"
          },
          "item":{
            "guid":"5abf524e-31b5-4c1b-a797-7a44d888d071",
            "entityType":"MenuItem",
            "externalId":"100000000100004071"
          },
          "taxInclusion":null,
          "quantity":4,
          "unitOfMeasure":null,
          "tax":2.44,
          "diningOption":null,
          "voidBusinessDate":null,
          "createdDate":null,
          "preModifier":null,
          "modifiedDate":null
        }
      ],
      "voidBusinessDate":null,
      "deleted":false,
      "createdDevice":null,
      "closedDate":null,
      "deletedDate":null,
      "modifiedDate":null,
      "taxAmount":2.44,
      "appliedServiceCharges":[],
      "customer":null
    },
    "redemptions":[
      {
        "identifier":"1",
        "itemId":null,
        "selectionGuid":null,
        "amount":5,
        "quantity":2
      }
    ]
  },
  "reverseTransactionInformation":null
}

Successful loyalty redeem response

{
  "checkResponse":{
    "accountInfo":{
      "identifier":"3",
      "firstName":"jack",
      "lastName":"williams",
      "phone":"1111111113",
      "email":"a3@gmail.com"
    },
    "offers":[
      {
        "identifier":"1",
        "name":"reward 1",
        "applicable":true,
        "selectionType":"CHECK",
        "amount":"5",
        "quantity":4
      },
      {
        "identifier":"3",
        "name":"reward 3",
        "applicable":false,
        "selectionType":"ITEM",
        "amount":"10",
        "itemApplication":[
          {
            "selectionIdentifier":"undefined",
            "amount":"10"
          }
        ],
        "quantity":10
      }
    ],
    "rejectedRedemptions":[],1
    "appliedRedemptions":[2
      {
        "identifier":"1",
        "itemId":null,
        "selectionGuid":null,
        "amount":5,
        "quantity":23
      }
    ],
    "userMessage":"Visit http://www.website.com to check your points balance"
  },
  "transactionStatus":"ACCEPT"4
}

1

The rejectedRedemptions array is empty because your loyalty program service determined that all of the redeemed reward offers in the redeem request are valid. If your loyalty program service determines that a redeemed reward is not valid, you must include a RejectedRedemption object in this array. For more information, see Handling Redeemed Offers That Are Not Valid.

2

The appliedRedemptions array includes a Redemption object for each rewards offer that your loyalty program service determines is valid for the loyalty account and the current guest check.

3

In this example, since the quantity of the applied redemption is 2 and the amount is 5, the total amount discounted will be 10.

4

Set the transactionStatus to ACCEPT to indicate that your service has successfully processed the request. The status is ACCEPT even when you determine that some redeemed rewards offers are not valid.