Listing offers and rewards on kiosks

Contents

Overview

To display valid offers and rewards on the UI, the client needs to retrieve data from two sources: the Loyalty Engine (Through the Loyalty Middleware) and Sanity (RBI’s CMS). The Loyalty Engine will provide incentives for which the user is "eligible," meaning they satisfy all necessary criteria (rules). Meanwhile, Sanity will offer information about active incentives, and reward categories, as well as all visual display content, such as names, images, descriptions, and more.

The client must hit both of the previously mentioned data sources and intersect the data to decide what to present. The sequence in which these queries are executed will depend on the client and its implementation. It is advised to first query Sanity for all "sorted offers" (active system-wide offers), “config offers” (possible personalized offers for any given user), and "reward categories" (active rewards), and then utilize those identifiers to request pertinent information from the Loyalty Engine.

Querying Sanity using GraphQL

GraphQL URL (Playground Available): https://czqk28jt.apicdn.sanity.io/v1/graphql/dev_bk_us/default

Replace dev_bk_us with the {{stage}}_{{brand}}_{{country}} that you desire to query.
Sanity GraphQL can be hit via a POST request. Please reference the POST URL structure for each of the sample queries below.
Please use this playground to play with the queries below and examine the schema for fields you may wish to request.

Example Offers Query

The _id is subject to the dataset you are using. For the most part, it will be feature-loyalty-offers-ui-singleton, however, some markets have drifted from this convention
Sample Query:

query getSanityOffers {
	LoyaltyOffersUI(id: "feature-loyalty-offers-ui-singleton") {
	# Available for all users.
    sortedSystemwideOffers {
      _id
      loyaltyEngineId
      name {
        enRaw
      }
    }
    # These are "templates", personalized offers get created based on this template.
    # You should use these only to display content (images, names, etc), and display only the actual offer from the engine.
    liveConfigOffers {
      _id
      loyaltyEngineId
      name {
        enRaw
      }
    }
  }
}

Example Rewards Query

The _id is subject to the dataset you are using. For the most part it will be reward-list-singleton, however, some markets have drifted from this convention
Sample Query:

query getSanityRewards {
  RewardList(id: "reward-list-singleton") {
    rewardCategories {
      _id
      label {
        en
      }
      rewards {
        ... on Reward {
          # Sanity ID of the reward
          _id
          # Loyalty Engine ID to be used in the Loyalty Engine query if needed
          loyaltyEngineId
          # Reward content to display to the user (name, image, description...)
          name {
            en
          }
          image {
            en {
              asset {
                url
              }
            }
          }
          description {
            enRaw
          }
          # Here we add the rules we want to check for the rewards
          # e.g., LoyaltyPoints (reward points cost), RewardPrice (reward money price),
          # SubtotalSpend (minimum subototal to spend for redeeming the reward)
          ruleSet {
            ... on LoyaltyPoints {
              points
            }
            ... on RewardPrice {
              price
            }
            ... on SubtotalSpend {
              minimumSpend
            }
            # Add more ruleSets as needed here (e.g. FirstOrderOnly, LoyaltyBetweenDates, etc)
            # See the screenshot below for how get the list of available ruleSet from GraphQL Playground
          }
          # Benefit of the reward, it can be either a Combo, Item, OfferDiscount
          # or Picker
          # e.g., OfferDiscount (It can be a discount for the whole cart or 
          # a discount for a specific product)
          incentives {
            ... on OfferDiscount {
              discountType
              discountValue
              discountProduct {
                ... on Item {
                  name {
                    en
                  }
                }
                ... on Combo {
                  name {
                    en
                  }
                }
              }
            }
          }
          # Reward redemption method available
          redemptionMethod
          # Here we can get the needed PLUs by looking for a specific vendor
          # e.g., Partner constant PLU
          vendorConfigs {
            partner {
              _type
              constantPlu
              pluType
            }
          }
        }
      }
    }
  }
}

Getting the list of ruleSets from GraphQL Playground

To get list of ruleSet available, navigate to https://czqk28jt.apicdn.sanity.io/v1/graphql/dev_bk_aq/default, and search for “ruleSet” in the Schema explorer as seen here:

Querying Loyalty Engine

GraphQL URL (Playground Available): https://euc1-dev-bk-loyalty-middleware.rbictg.com/graphql

Replace dev-bk with the {{stage}}-{{brand}} that you desire to query. You will need to prefix the URL with the AWS region that your market lives in. Please communicate with RBI reps to know which region your market is hosted.
- An example URL for ES (Spain) would be https://euw3-dev-bk-loyalty-middleware.rbictg.com/graphql
Make sure to set the x-ui-region header to the country you want to query:

Please use this playground to play with the queries below and examine the schema for fields you may wish to request.
Some where filters that may be relevant to Kiosk
- ids - a collection of Engine IDs for offers/rewards. This is the loyaltyEngineId field on every sanity offer/reward document.
- omitInvalids - This controls whether invalid incentives will be returned. Only incentives that failed “fixable” rules will be returned if this is set to false. A fixable rule is one that the user can change behavior to make the rule pass, like the minSpend, the user can add more items to their cart to meet the requirement. An absolute failure like date-band will not be returned regardless of what the value of this filter is
  - This is useful for displaying error / in-line messages in the UI
- serviceMode - some incentives can only be redeemed if the service mode meets the required ruleset
- storeId - some incentives can only be redeemed at certain stores
- subtotalAmount = some incentives require a minimum spend
- cartEntries - some incentives require certain items to be in the cart, this rule uses the sanity id of each rbi product
- paymentMethod - some incentives require certain payment methods to be used

Example Offers Query

You should use the sanityId to match these objects to the ones from the above query.

type = "GLOBAL" refers to Systemwide Offers (sorted offers) and "PERSONALIZED" refers to Config Offers (live config offers)

query getLoyaltyOffers {
  loyaltyOffersV2(loyaltyId: "<USER_LOYALTY_ID>", where: { omitInvalids: false }) {
    id
    name
    type
    sanityId
    errors {
      code
      ruleId
    }
  }
}

Example Offers Query Response

{
  "data": {
    "loyaltyOffersV2": [
      {
        "id": "a4c24211-2d36-47be-bad8-8deea437dbfa",
        "name": "$6 Let's Get This Bacon Meal",
        "type": "GLOBAL",
        "sanityId": "AAA-AAA-AAA",
        "errors": null
      },
      {
        "id": "fbba4e93-eecd-42b6-a4ed-333856d47bda",
        "name": "Delivery Offer - $8 The Spicy One Meal",
        "type": "GLOBAL",
        "sanityId": "BBB-BBB-BBB",
        "errors": null
      },
      {
        "id": "2a7b2f20-1662-4854-9f4b-e9974200f294",
        "name": "Support 50% Discount Offer",
        "type": "PERSONALIZED",
        "sanityId": "CCC-CCC-CCC",
        "errors": null
      },
      {
        "id": "6646b80b-dea9-4bf4-81f5-390554926987",
        "name": "Loyalty Upsize Swap",
        "errors": [
          {
            "code": "unsatisfied-cart-requirements",
            "ruleId": "cart-requirement"
          }
        ]
      }
    ]
  }
}

Example Rewards Query

query getLoyaltyRewards {
  loyaltyRewards(loyaltyId: "<USER_LOYALTY_ID>", where: { omitInvalids: false }) {
    id
    name
    errors {
      code
      ruleId
    }
  }
}

Example Rewards Response

{
  "data": {
    "loyaltyRewardsV2": [
      {
        "id": "3b5bdddc-c7c9-42d8-9332-b0c3f36c8e1c",
        "name": "Value Powerade Zero",
        "errors": null
      },
      {
        "id": "728aaedd-3234-4eae-89af-35cd5672adcb",
        "name": "Large Dr. Pepper",
        "errors": null
      },
      {
        "id": "480122d7-86ff-4db0-965c-7dbb72bb5179",
        "name": "Value Soft Drinks",
        "errors": null
      }
    ]
  }
}