Overview

Personalised offers (also called config offers) are a specific type of offer that is only available to selected guests. These need to be handled slightly different to systemwide offers, and those details are covered in this document.

Please make sure that you understand Listing offers and rewards on kiosks before reading this document.

Data structure

All offers, regardless of their type, are stored in our Loyalty Platform. We also use a CMS platform called Sanity, where our team and the franchisee can set up marketing materials such as the offer's name, description, and images. Additionally, they can define within Sanity how the offer works, including rules for redemption, limitations, any requirements, and some other miscellaneous aspects of each offer.

It’s important to understand that both of these systems store and handle data separately from each other, some data gets synced between platforms, and some data does not. Sanity for example has all the images for any given offer, whereas the Loyalty Platform does not. The same is true in the other direction, the Loyalty Platform contains the records for Personalized offers, whereas Sanity does not.

The way we like to think about it is, that for any content displayed to the final user, we want to usually use the data from Sanity. For any business rules and logic, like which offer should be displayed to which user we want to use the data from the Loyalty Platform.

Also, please keep in mind that personalized offers will only come from the Loyalty Platform, and their Sanity ID will point to a Configuration Offer, like a Many-to-One relationship.

Retrieving personalised offers

This is an example Sanity GraphQL query that returns personalized offers:

query getSanityOffers {
	LoyaltyOffersUI(id: "feature-loyalty-offers-ui-singleton") {
	# Available for all users.
	# You can use these to lookup assets from global.
    sortedSystemwideOffers {
      _id
      loyaltyEngineId
      name {
        enRaw
      }
    }
    # These are config. offers (templates).
    # You should use these only to display content (images, names, etc).
    # You can use these to lookup assets from the actual Personalized offers.
    liveConfigOffers {
      _id
      loyaltyEngineId
      name {
        enRaw
      }
    }
  }
}

Processing personalized offers

This section explains how the Loyalty API endpoints must be used to process orders that contain personalized offers.

Identify

This endpoint can be used without any changes to support personalised offers.

Validate and Update

When sending a request containing personalized offers to Loyalty API v1 - Validate or Loyalty API v1 - Update, it’s important to include the personalized offer’s loyaltyEngineId. In this case, the incentiveId does not need to be sent.

Example request

{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serviceMode",
    "status": "PENDING or CLAIMED",
    "transactionDetails": {
        "currency": "USD",
        "order": [
            {
                "name": "med whopper combo",
                "price": 5.00,
                "productId": "$plu",
                "productType": "combo",
                "quantity": 1,
                "referenceId": "1", // line id
                "tax": 0
            },
            {
                "name": "whopper",
                "parentReferenceId"?: "1", // line id of parent (for children elements)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "2", // line id
                "tax": 0
            },
            {
                "name": "med fries",
                "parentReferenceId"?: "1", // line id of parent (for children elements)
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "3", // line id
                "tax": 0
            },
            {
                "incentiveId": "$sanityRewardId",
                "name": "free drink reward",
                "price": 0,
                "productId": "$rewardPlu",
                "productType": "REWARD",
                "quantity": 1,
                "referenceId": "4", // line id
                "tax": 0
            },
            {
                "incentiveId": "$sanityOfferId",
                "loyaltyEngineId": "$offerLoyaltyEngineId", // (Optional) Use this field for all Offers if supporting Personalized Offers
                "name": "$2.99 chicken sandwich meal",
                "price": 2.99,
                "productId": "$offerPlu",
                "productType": "OFFER",
                "quantity": 1,
                "referenceId": "5", // line id
                "tax": 0.50
            }
        ],
        "payments": [
            {
                "amount": 500,
                "type": "$paymentMethod",
                "ccToken"?: "$panToken"
            }
        ],
        "posVendor": {
            "matchingId": "$smgCode",
            "operator": "$operatorId",
            "posType": "$posVendorName",
            "storeId": "$rbiStoreId",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "terminal": "$terminalNumber",
            "transactionId": "$posTransactionId"
        }
    },
    "transactionId": "$loyaltyTransactionId"
}

Example response

{
    "loyaltyId": "$loyaltyUserId",
    "points": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "transactionId": "$loyaltyTransactionId"
}