Updating loyalty information and loyalty discounts for an existing check -

Updating loyalty information and loyalty discounts for an existing check

Use the Toast orders API to attach loyalty program information to a check. This is useful for order-and-pay-at-the-table and kiosk-style ordering workflows, where a guest might not decide to use their loyalty account until the payment step.

Updating loyalty information and adding loyalty discounts overview

Online ordering integrations often submit loyalty information, discounts, and payments together in a single POST request to the /orders endpoint of the orders API.

Tableside kiosk and order-and-pay-at-the-table orders work differently where a guest starts ordering before they've added their loyalty account to their order.

The following steps describe the workflow used by these locations to create an order, apply loyalty, and apply discounts.

POST a request to the orders API /orders endpoint to create the order and check.
Add loyalty program information to the check when the guest is ready to redeem rewards or accrue loyalty. For more information, see Updating the applied loyalty information for a check.
Add loyalty discounts by sending a POST request to the /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts endpoint. For more information, see Applying loyalty discounts.
Add payment details to the check by sending a POST request to /orders/{orderGuid}/checks/{checkGuid}/payments endpoint. For more information, see Adding payments to an existing check.

Attaching a payment triggers the redemption of any pending loyalty discount.

Updating the applied loyalty information for a check

To update the loyalty information for a check, send a PATCH request to the /orders/v2/checks/{checkGuid}/appliedLoyaltyInfo endpoint of the orders API. The request body is a JSON AppliedLoyaltyInfo object. The procedure below explains how to update the loyalty information for a check.

To update the applied loyalty information for a check

Locate the Toast platform GUID of the check you're updating. For more information, see Finding an order or check GUID.
Build a JSON AppliedLoyaltyInfo object with the values you want to set. For more information, see AppliedLoyaltyInfo values.
Send a PATCH request to the /orders/v2/checks/{checkGuid}/appliedLoyaltyInfo endpoint. Include the Toast-Restaurant-External-ID header with the location's identifier, and the AppliedLoyaltyInfo object as the request body.

A successful request returns a 200 status with the full, updated Check object.

Note

You can't update a check whose status is DELETED.

AppliedLoyaltyInfo values

Use the following values to build the AppliedLoyaltyInfo object for your request.

Value	Description
`loyaltyIdentifier`	The identifier for the loyalty program account. The format depends on the loyalty vendor. For example, this may be a loyalty card number, or, for some integrations, a guest's phone number.
`vendor`	The loyalty program service provider. One of `TOAST`, `PUNCHH`, `PUNCHH2`, `PAYTRONIX`, `APPFRONT`, or `INTEGRATION`.
`maskedLoyaltyIdentifier`	A masked representation of the `loyaltyIdentifier` that's safe to display to employees and guests, for example `************1234`. This value isn't supplied by the Toast platform.
`accrualFamilyGuid`	A response-only Toast platform identifier for the loyalty transaction. This is set once the loyalty vendor confirms the transaction.
`accrualText`	A response-only description of the loyalty transaction to print on the guest's receipt, for example "Earned 27 points." Maximum 255 characters.

Note

If the check already has loyalty information, the loyaltyIdentifier in your request must match the existing value.

Example request

The following example shows an AppliedLoyaltyInfo request body for a PATCH request to the /orders/v2/checks/{checkGuid}/appliedLoyaltyInfo endpoint.

{
  "loyaltyIdentifier": "6000101001599474",
  "vendor": "INTEGRATION"
}

Example response

{
  "guid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "entityType": "Check",

  [contents omitted]

  "appliedLoyaltyInfo": {
    "loyaltyIdentifier": "6000101001599474",
    "vendor": "INTEGRATION",
    "maskedLoyaltyIdentifier": "************9474",
    "accrualFamilyGuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "accrualText": "Earned 27 points."
  },

  [contents omitted]

}

Applying loyalty discounts

Once loyalty information is attached to a check, add any applicable loyalty discounts. The procedure below describes how to add a loyalty program discount to a check.

To add a loyalty program discount to a check

Look up the reward the guest is redeeming using your own connection to the loyalty vendor. The Toast orders API doesn't include a lookup or search endpoint for loyalty rewards. You need the vendor's referenceId for the discount before submitting a request to the /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts endpoint.
Build a JSON AppliedDiscount object with a loyaltyDetails object containing the vendor and referenceId.
Send a POST request to the /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts endpoint with the AppliedDiscount object as the request body.

Examine the response. If the discount is valid, its processingState is PENDING_APPLIED. It remains in this state until payment is attached to the check.

loyaltyDetails values

The following table describes the fields included in the loyaltyDetails object.

Value	Description
`vendor`	The loyalty program service provider. Use `INTEGRATION`.
`referenceId`	The identifier of the loyalty program discount that's recognized by the loyalty program service provider. The Toast platform transmits this identifier to the service provider to determine the discount's validity and amount.

Example: applying a loyalty discount

The following example shows an AppliedDiscount request body with loyaltyDetails, for a POST request to the /orders/{orderGuid}/checks/{checkGuid}/appliedDiscounts endpoint.

[
  {
    "loyaltyDetails": {
      "vendor": "INTEGRATION",
      "referenceId": "4"
    }
  }
]