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.

Inquire

The inquire workflow occurs when a restaurant employee selects the Rewards button in the Toast POS app if a restaurant guest's loyalty account has already been found. The Toast platform might send multiple inquire transactions while handling a single purchase interaction for a restaurant guest.

Inquire workflow

  1. The restaurant employee selects a guest's loyalty account from search results or scans, swipes, or keys in the loyalty account identifier in the Toast POS app.

  2. The POS sends an inquire request to your loyalty program integration. 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 already been applied (redemptions).

  3. Your loyalty program integration responds to the inquire request. The request body includes a ResponseCheck object holding the following information:

    • A list of available offers. You determine which offers to include in the list. If an item-level offer is available, you must specify the item GUID so the POS knows which item it applies to.

      Each offer contains a boolean value indicating whether the offer is applicable based on the current check contents. If the offer is not applicable, the POS will display the offer with formatting to indicate that it is not available (for example, light gray text) and without a Redeem button.

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

    • A list of offers that are currently applied to the check (redemptions) that are valid.

    • A ResponseCheck object must include an accountInfo value.

    • If you include a numeric pointsBalance on your ResponseCheck object, the points balance will display on the POS.

  4. The restaurant employee might make changes to the check. For example:

    • Apply and remove loyalty program offers based on the offers that the guest chooses. Each time the employee selects the Rewards button, the Toast platform sends an inquire request.

    • Add and remove items from the check.

    • Apply and remove discounts that are not associated with the loyalty program to and from the check.

  5. The restaurant employee finishes entering the guest's order and enters the payment screen of the POS.

  6. The POS sends another inquire request. This request repeats step Step 2.

  7. Your loyalty program integration responds to the inquire request. This response repeats step Step 3.

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

When discounts display on the POS, all applicable discounts display first, followed by all discounts that are not applicable. Within each type of discount (applicable and non-applicable), discounts are ordered by name alphabetically.

In all scenarios, response contains a list of accepted and rejected redemptions, if any.

  • If ACCEPTED, redemption is added to check as a discount.

  • If REJECTED, redemption is removed from the check with an error message.

    This is still possible if the check changes. For example, add two pizzas to the order and apply a BOGO discount, buy two pizzas and get a pizza for free. Then remove one of the pizzas. The next inquire will indicate that the offer which was previously applied is rejected because the check does not have the items that are needed to qualify for the offer.

Loyalty inquire request

{
  "toastTransactionType":"LOYALTY_INQUIRE",
  "searchTransactionInformation":null,
  "checkTransactionInformation":{
    "loyaltyIdentifier":"1",
    "check":{
      "guid":"5728df00-d770-4aeb-a4c9-53226a104ac0",
      "entityType":null,
      "externalId":null,
      "displayNumber":"3001",
      "payments":[],
      "appliedDiscounts":[],
      "lastModifiedDevice":null,
      "voidDate":null,
      "paidDate":null,
      "appliedLoyaltyInfo":null,
      "voided":false,
      "paymentStatus":"OPEN",
      "amount":97.42,
      "tabName":null,
      "taxExempt":false,
      "openedDate":null,
      "totalAmount":103.51,
      "selections":[
        {
          "guid":"5e4fa4aa-4269-4383-9bbd-774591bbfb3c",
          "entityType":null,
          "externalId":null,
          "deferred":false,
          "preDiscountPrice":87.92,
          "voidReason":null,
          "optionGroup":null,
          "displayName":"Crab Cakes",
          "appliedDiscounts":[],
          "modifiers":[],
          "voidDate":null,
          "fulfillmentStatus":"NEW",
          "salesCategory":null,
          "selectionType":null,
          "price":87.92,
          "voided":false,
          "appliedTaxes":[
            {
              "guid":null,
              "entityType":"AppliedTaxRate",
              "taxRate":{
                "guid":"78aca305-6fbc-42ea-a85b-1671c52367eb",
                "entityType":"TaxRate"
              },
              "rate":0.0625,
              "name":"MA Tax",
              "taxAmount":5.49612811,
              "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":8.0,
          "unitOfMeasure":null,
          "tax":5.49612811,
          "diningOption":null,
          "voidBusinessDate":null,
          "createdDate":null,
          "preModifier":null,
          "modifiedDate":null
        },
        {
          "guid":"c4c6cd98-d1ba-42f6-87c0-4d8af7486be7",
          "entityType":null,
          "externalId":null,
          "deferred":false,
          "preDiscountPrice":9.5,
          "voidReason":null,
          "optionGroup":null,
          "displayName":"BBQ Pulled Pork Sliders",
          "appliedDiscounts":[],
          "modifiers":[],
          "voidDate":null,
          "fulfillmentStatus":"NEW",
          "salesCategory":null,
          "selectionType":null,
          "price":9.5,
          "voided":false,
          "appliedTaxes":[
            {
              "guid":null,
              "entityType":"AppliedTaxRate",
              "taxRate":{
                "guid":"78aca305-6fbc-42ea-a85b-1671c52367eb",
                "entityType":"TaxRate"
              },
              "rate":0.0625,
              "name":"MA Tax",
              "taxAmount":0.59387189,
              "type":"PERCENT"
            }
          ],
          "itemGroup":{
            "guid":"15694864-225d-4b47-a60b-b9c20986b0af",
            "entityType":"MenuGroup",
            "externalId":"100000000100004070"
          },
          "item":{
            "guid":"a1a96ffc-fb39-422b-93bd-44f15692f707",
            "entityType":"MenuItem",
            "externalId":"100000000100004072"
          },
          "taxInclusion":null,
          "quantity":1.0,
          "unitOfMeasure":null,
          "tax":0.59387189,
          "diningOption":null,
          "voidBusinessDate":null,
          "createdDate":null,
          "preModifier":null,
          "modifiedDate":null
        }
      ],
      "voidBusinessDate":null,
      "deleted":false,
      "createdDevice":null,
      "closedDate":null,
      "deletedDate":null,
      "modifiedDate":null,
      "taxAmount":6.09,
      "appliedServiceCharges":[],
      "customer":null
    },
    "redemptions":[]
  },
  "reverseTransactionInformation":null
}

Successful loyalty inquire response

{
  "checkResponse":{
    "accountInfo":{
      "identifier":"1",
      "firstName":"james",
      "lastName":"smith",
      "phone":"1111111111",
      "email":"a1@gmail.com"
    },
    "offers":[
      {
        "identifier":"4",
        "name":"reward 3",
        "applicable":false,
        "selectionType":"ITEM",
        "amount":"10",
        "quantity":2
      }
    ],
    "rejectedRedemptions":[],
    "appliedRedemptions":[],
    "userMessage":"Visit http://www.website.com to check your points balance."
  },
  "transactionStatus":"ACCEPT"
}