Purpose

This 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). OTP is always allowed, but Loyalty ID’s may or may not be allowed depending on configuration. Each user can only have one transaction ID open at a time. The latest transaction ID will always be kept and any other open transaction will be cancelled.

This endpoint should only be called during the first scan. Subsequent scans should call Identify (PUT) instead.

Request Format

Endpoint

POST /loyalty/v2/identify

Headers

Bearer token in JWT format as specified in https://rbictg.atlassian.net/wiki/spaces/IN/pages/3739288100.

Body

identifier <string>: OTP (6 digit code) or Loyalty ID in UUID format.
location: object identifying the location the guest is identifying from.
- storeId <integer>: uniquely identifies the store where the guest is identifying from.
- terminalId <string> (optional): identifies the POS or Kiosk terminal used in the restaurant
- hasLoyalty <boolean> (optional): defaults to true. If false, then no points will be earned or burned for transaction and no rewards can be ordered.
content <boolean> (optional): whether the endpoint should return the list of offers and rewards that are visible to this guest. Defaults to false.

Example request

{
    "identifier": "123456",
    "location": {
        "storeId": "9999",
        "terminalId": "0", 
        "hasLoyalty": true 
    }
}

Response Format

Success response body

transactionId <UUID>: unique identifier of the loyalty transaction created.
balance <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.
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>: Loyalty ID of the user in UUID format
- name <string>: name of the user that was saved upon account creation
- tier <number>: loyalty tier this user is in. Only applies for markets that have loyalty tier feature enabled. It can be “1” for guests that are in tier 1 or “2” for guests that are in tier 2.
cart: an array that includes objects with the below fields for each product that is in the order basket.
- externalreferenceId <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.
- type <string>: the type of product. It could be Reward , Offer, Item or Combo
- menuSelections(optional): an array that includes combos or sub-items within the product.
  - externalreferenceId <string>: PLU of the menu selection within the the product that was pre-selected in the app. This can be a combo or item PLU.
  - quantity <number>: the amount of the above product that is in the loyalty order.
  - type <string>: the type of product. It could be Item or Combo
  - menuSelections(optional): an array that includes sub-items within a specific product.
content: array that includes all PLUs for offers and rewards in the market
- plu <string>: PLU of all rewards or offers that should be excluded from showing to that specific user.

Success response example

Success response without content information

{
    "transactionId": "f4190848-169d-4c69-9f53-f916318c432b", // UUID of the loyalty order/transaction
    "balance": 14464,
    "loyaltyUser": {
        "created": "2021-08-10T12:18:39.180Z",
        "id": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7",
        "name": "Farhan",
        "tier": 1
    },
    "cart": [
        {
            "externalReferenceId": "2244",
            "menuSelections": [
                    {
                        "externalReferenceId": "100-1-1", // item PLU
                        "menuSelections": [],
                        "quantity": 1,
                        "type": "Item"
                    }
                ],
            "quantity": 1,
            "type": "Reward",
        },
        {         
            "externalReferenceId": "1050", // offer PLU
            "menuSelections": [
                    {
                        "externalReferenceId": "100-1-1", // combo plu
                        "menuSelections": [
                              {
                                  "externalReferenceId": "101-1-1", // item 1 plu
                                  "menuSelections": [],
                                  "quantity": 1,
                                  "type": "Item"
                              },
                              {
                                  "externalReferenceId": "102-1-1", // item 2 plu
                                  "menuSelections": [],
                                  "quantity": 1,
                                  "type": "Item"
                              },
                              {
                                  "externalReferenceId": "103-1-1", // item 3 plu
                                  "menuSelections": [],
                                  "quantity": 1,
                                  "type": "Item"
                    },
                ],
                 "quantity": 1,
                 "type": "Combo"
                 }
              ],
              "quantity": 1,
              "type": "Offer"
            }
        ]
    }

Success response with content information

This section needs revisiting after we finalise the Get Content endpoint.

{
    "transactionId": "f4190848-169d-4c69-9f53-f916318c432b", // uuid of the loyalty order/transaction
    "balances": [
        {
            "amount": 14464,
            "currency": "points"
        }
    ],
    "loyaltyUser": {
        "created": "2021-08-10T12:18:39.180Z",
        "id": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7",
        "name": "Farhan"
    },
    "content": [
        { 
         "plu": "8810",    
        },
        { 
         "plu": "8811",    
        },
        { 
         "plu": "8812",    
        },
        { 
         "plu": "8813",    
        },
        { 
         "plu": "8814",    
        },
        { 
         "plu": "8815",    
        },
        { 
         "plu": "8816",    
        },
        { 
         "plu": "8817",    
        },
        { 
         "plu": "8818",    
        },
        { 
         "plu": "8819",    
        },
    ]
}

Error responses

All error responses use the standard Loyalty API v1 - Error Responses 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.
HTTP 401 (Unauthorized) if the bearer token is missing or not valid.
HTTP 404 (Not Found): in the following scenarios indicated in the code field of the error response:
- "IdentifierNotFound": if the specified identifier was not found.
- "StoreNotFound": if the specified storeId was not found.

RBI Developer Portal

Identify (POST)