Purpose

The Identify endpoint is used to identify a guest who scans an identifier generated by the RBI app (which could be an OTP or the Loyalty ID) at a client device (typically a POS or Kiosk terminal). Identification will include any potential rewards/offers that they had pre-selected within the app.

Request Format

Endpoint

POST /loyalty/identify

Headers

As documented here: Loyalty API - Getting Started.

Body

identifier <string>: OTP (6 digit code) or Loyalty ID in UUID format.
posVendor: object identifying system making the request (POS or Kiosk):
- transactionId <string>: the POS transaction identifier.
- storeId <integer>: uniquely identifies the store where the guest is identifying from.
- terminal <string>: identifies the POS or Kiosk terminal used in the restaurant
- operator <string>: identifies the POS operator (only applicable for orders made on a POS terminal)
- posType <string>: identified the type of POS or Kiosk system making the request. This value must have been previously agreed between the vendor and RBI, so that the correct integration configuration is applied. In most cases, this will be set to a value of “Partner”.
- supportingPos <string> (optional): used mainly by kiosk vendors, this field will need to refer to the POS vendor of the store the kiosk is sending the request from.

Example request

{
    "identifier": "123456",
    "posVendor": {
        "operator": "300", // operator id
        "supportingPos": "POS vendor name (optional field)"
        "posType": "Kiosk vendor name",
        "storeId": "9999",
        "terminal": "0", // terminal id
        "transactionId": "000000000257"
    }
}

Response Format

Success response body

transactionId <string>: unique identifier of the loyalty transaction created in UUID format.
balances: object that indicates loyalty balance of the user's account
- amount <number>: this represents the number of loyalty points the user has. If this QR code was pre-selected with rewards, then this number already has those loyalty points temporarily deducted from total user’s loyalty points balance.
- currency <string>: this represents the ISO currency the above amount. Normally set to "points".
loyaltyUser: object that indicates information about this loyalty user
- created <string>: string that represents that date and time user loyalty account was created
- id <string>: unique identifier of the loyalty user in UUID format
- name <string>: name of the user that was saved upon account creation
order: an array that includes objects with the below fields for each product that is in the order basket.
- productId <string>: PLU of the product that was pre-selected in the app. This can be an offer or a reward.
- quantity <number>: the amount of the above product that is in the loyalty order.
- price <number>: the price of the product
- productType <string>: the type of product. In this case it would either be REWARD or OFFER
- referenceId <string>: unique line ID of the product
- incentiveId <string> (optional): Sanity ID of the offer or reward if an offer or reward is pre-selected in the app.
- loyaltyEngineId <string> (optional): Loyalty Engine ID of the personalized offer if a personalized offer is pre-selected in the app. Only needs to be sent for personalized offers, but it can be sent for all offers. Read more about this here: https://rbictg.atlassian.net/wiki/x/iABm-g
eligibleDiscounts (optional): an array of any offer or rewards discount that were pre-selected by the user in the app.
- details <object> (optional): details of the discount included in the basket.
  - displayName <string> (optional): name of the offer or reward discount included in the basket.
  - discountValue <integer> (optional): an integer that represents the value of the discount.
  - subType <string> (optional): the type of the discount. Discount can only be PERCENTAGE_DISCOUNT or AMOUNT_DISCOUNT .
  - type <string> (optional): the type of the benefit of the discount. This can only be offer or reward.
- incentiveId <string> (optional): Sanity ID of the offer or reward discount.
- productId <string>: PLU of the discount that was pre-selected in the app. This can be an offer or a reward.
- referenceId <string> (optional): Loyalty Engine ID of the offer or reward discount if an offer or reward discount is pre-selected in the app.

Success response example

Response that does not contain a cart or product level discount

{
    "balances": [
        {
            "amount": 14464,
            "currency": "points"
        }
    ],
    "loyaltyUser": {
        "created": "2021-08-10T12:18:39.180Z",
        "id": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7",
        "name": "Farhan"
    },
    "order": [
        {
            "productId": "Reward PLU",
            "incentiveId": "Sanity ID of Reward"
            "loyaltyEngineId": "$rewardLoyaltyEngineId",
            "quantity": 1,
            "price": 0,
            "productType": "reward",
            "referenceId": "00", // unique line id
        },
        {
            "productId": "Offer PLU",
            "incentiveId": "Sanity ID of Offer"
            "loyaltyEngineId": "$offerLoyaltyEngineId",
            "quantity": 1,
            "productType": "offer",
            "referenceId": "00", // unique line id
        },
    ],
    "transactionId": "f4190848-169d-4c69-9f53-f916318c432b" // uuid of the loyalty order/transaction
}

Response that contain a cart or product level discount: Redeem discounts

{
    "balances": [
        {
            "amount": 14464,
            "currency": "points"
        }
    ],
    "eligibleDiscounts": [
        {
            "details": {
                "displayName": "20% off order",
                "discountValue": 20,
                "subtype": "PERCENTAGE_DISCOUNT or AMOUNT_DISCOUNT",
                "type": "offer" or "reward"
            },
            "incentiveId": "$sanityIncentiveId",
            "productId": "$incentivePlu",
            "referenceId": "$incentiveLoyaltyId"
        }
    ],
    "loyaltyUser": {
        "created": "2021-08-10T12:18:39.180Z",
        "id": "$loyaltyUserId",
        "name": "$loyaltyUserName"
    },
    "order": [],
    "transactionId": "$loyaltyTransactionId"
}

Error responses

All error responses use the standard format.

HTTP 400 (Bad Request) if the request body has an incorrect format. In this case, the response will include details about which specific field or fields have an incorrect format:
- "IdentificationFailed": the sent identifier was not correct (e.g. not an OTP code) but complies to a loyalty ID number format, then it’s detected as a LOYALTY_ID by accident.
HTTP 401 (Unauthorized) if authentication headers are missing or not valid.
HTTP 404 (Not Found): in the following scenarios indicated in the code field of the error response:
- "HashSetNotFoundError": if the specified identifier was not found.
- "UserNotFoundError": the Loyalty user (specifically the loyalty id) was not found.
- "RewardNotFoundError" : the reward being pre-selected was not found.
- "OfferNotFoundError" : the offer being pre-selected was not found.
HTTP 422 (Unprocessable Entity) if identifier cannot be processed
- "OrderSelectionStatusUnclaimable": the identifier (e.g. OTP) was already used.
- "InvalidIdentifier": the identifier was not a valid type.
- "IdentifierTypeDisabled": the detected identifier type is not supported in the market.

RBI Developer Portal

Loyalty API v1 - Identify