As documented here: Loyalty API - Getting Started.

Body

loyaltyId <string>: Loyalty ID unique identifier of the loyalty user in UUID format.
transactionId <string>: Loyalty order ID unique identifier of the loyalty transaction created in UUID format.
channel <string>: “Restaurant”, “App”, or “Web”. Always use “Restaurant” for In-Restaurant orders.
created <string>: string that represents the current date and time of the request.
created serviceMode <string>: service mode of the order being placed. This can be “EAT_IN”, “TAKEOUT”, ”DRIVE_THRU”, “CURBSIDE”, or “TABLE_SERVICE”.
status <string>: status of the order that indicates if the order is still pending or if it has been completed. This can be “PENDING” for orders not yet completed and “CLAIMED” for orders that were completed.
transactionDetails: object identifying order information from the request (POS or Kiosk):
- currency <string>: the ISO currency code used in the market.
- order: array identifying all products inside the order. each Each product is an object with these fields:
  posVendor: object identifying system making the request (POS or Kiosk):
  - name <string>: name of the product.
  - price <number>: price of the product.
  - productId <string>: PLU of the product.
  - productType <string>: type of the product. This can be “combo”, “item”, “reward” or “offer”.
  - quantity <number>: number of times this product was ordered.
  - referenceId <string>: line ID of product
  - tax <number>: tax amount attributed to this product.
  - parentReferenceId <number> (optional): line id of parent product. Only relevant for children products (e.g. a coke drink that was ordered as part of a whopper medium meal combo).
- payments: array with an object identifying payment information of the order:
  - amount <number>: total cost of the order in cents.
  - type <string>: type of payment method that was used during payment for order. This can be “CASH”, “CREDIT”, “VISA”, “MASTERCARD”.
- - transactionId <string>: the incentiveId <string> (optional): Sanity ID of the offer or reward. Only needs to be sent for offers and rewards.
  - loyaltyEngineId <string> (optional): Loyalty Engine ID of the personalized offer. Only needs to be sent for personalized offers, but it can be sent for all offers. When this field is sent for a personalized offer, the incentiveId does not need to be sent. Read more about this here: https://rbictg.atlassian.net/wiki/x/iABm-g.
- payments: array with an object identifying payment information of the order:
  - amount <number>: total cost of the order in cents.
  - type <string>: type of payment method that was used during payment for order. This can be “CASH”, “VISA”, “MASTERCARD”, ”AMEX”.
- 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> (optional): identifies the POS or Kiosk terminal used in the restaurant
  - operator <string> (optional): 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): in case the posType is “Partner”used mainly by kiosk vendors, this field should be used to identify the POS/Kiosk brand for analytical purposes.

Example request

...

- - will need to refer to the POS vendor of the store the kiosk is sending the request from.
- appliedDiscounts (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 added to cart.

Example request

Request that does not contain a cart or product level discount

Code Block

{
    "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7",
    "transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142",
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z"
    "serviceMode": "EAT_IN",
    "pricestatus": 5.00"CLAIMED",
       "transactionDetails": {
        "productIdcurrency": "$pluUSD",
        "order": [
          "productType": "combo",  {
                "quantityname": 1 "med whopper combo",
                "referenceIdprice": "1"5.00,
// line id                 "taxproductId": 0"$plu",
            },             {"productType": "combo",
                "namequantity": "whopper"1,
                "parentReferenceIdreferenceId": "1", // line id of parent element (for children entries)
                "pricetax": 0,
            },
   "productId": "$plu",        {
        "productType": "item",                 "quantity"name": 1"whopper",
                "referenceIdparentReferenceId": "21", // line id of parent element (for children entries)
                "taxprice": 0,
             },   "productId": "$plu",
        {        "productType": "item",
       "name         "quantity": "med fries"1,
                "parentReferenceIdreferenceId"?: "12", // line id
of parent element (for children entries)           "tax": 0
      "price": 0,     },
           "productId": "$plu", {
                "productTypename": "itemmed fries",
                "quantityparentReferenceId"?: "1", // line id of parent element (for children entries)
       "referenceId": "3", // line id     "price": 0,
          "tax": 0     "productId": "$plu",
      },             {"productType": "item",
                "incentiveIdquantity": "$sanityRewardId"1,
                "namereferenceId": "free drink reward",3", // line id
                "pricetax": 0
            },
            {
       "productId         "incentiveId": "$rewardPlu$sanityRewardId",
                "productTypename": "free drink reward",
                "quantityprice": 10,
                "referenceIdproductId": "4$rewardPlu",
// line id              "productType":   "taxreward":,
0             },             {"quantity": 1,
                "incentiveIdreferenceId": "$sanityOfferId4", // line id
                "nametax": "$2.99 chicken sandwich meal", 0
            },
        "price": 2.99,   {
             "productId   "incentiveId": "$offerPlu$sanityOfferId",
                "productTypeloyaltyEngineId": "offer$offerLoyaltyEngineId", 
                "quantityname": 1"$2.99 chicken sandwich meal",
                "referenceIdprice": "5"2.99,
// line id                "productId": "tax$offerPlu":,
 0.50             }  "productType": "offer",
     ],         "payments  "quantity": [1,
            {    "referenceId": "5", // line id
        "amount": 500,       "tax": 0.50
         "type": "CASH",  }
        ],
     "ccToken": "optional PAN token"payments": [
           } {
       ],         "posVendoramount": {500,
                "operatortype": "300CASH", //
operator / cashier name             "posTypeccToken": "Kioskoptional vendorPAN nametoken",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
   }
        ],
        "storeIdposVendor": "9999",{
            "terminaloperator": "0300", // terminal idoperator / cashier name
            "posType": "Kiosk vendor name",
            "transactionIdsupportingPos": "000000000257"POS vendor name (optional field)", // vendor transactionto idreturn plu for
      },     }
}

Response format

Success response body

points <number>: this represents the number of loyalty points the user has. If the order has a status of “PENDING” and includes rewards, then this number already has those loyalty points temporarily deducted from total user’s loyalty points balance. If the order has a status of “CLAIMED” this is the final point balance of the guest after the order is completed.
pointsEarned <number>: this represents the number of loyalty points the user has. If the order has a status of “PENDING”, then this number will always be 0 since we don’t update the guests earned loyalty points until the order is completed. If the order has a status of “CLAIMED” this is the total number of points that were earned in this order.
pointsRedeemed <number>: this represents the number of loyalty points the user has. If the order has a status of “PENDING” and includes rewards, then this number is the total loyalty points temporarily deducted from total user’s loyalty points balance. If the order has a status of “CLAIMED” this is the final number of points that were deducted / burned in this order.
loyaltyId <UUID>: Loyalty ID in UUID format.
transactionId <UUID>: unique identifier of the loyalty transaction created.
receiptCode <string>: ?
presentation (optional): object that returns Receipt content information set in Sanity here.
- footer <string> (optional): this represents the content that will show in the footer of the receipt: Loyalty API - Receipts
- header <string>(optional): this represents the content that will show in the header of the receipt: Loyalty API - Receipts
- identifier <string>(optional): this represents the content that will show in the receipt to identify the order: Loyalty API - Receipts
- pointsEarned <string>(optional): this represents the points earned that will show in the receipt of the loyalty order: Loyalty API - Receipts
- totalPoints <string>(optional): this represents the total points balance that will show in the receipt of the loyalty order: Loyalty API - Receipts

Success response example

Code Block

{
    "points": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", // uuid of loyalty user
    "presentation": { "storeId": "9999",
            "terminal": "0", // terminal id
            "transactionId": "000000000257" // vendor transaction id
        },
    }
}

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

Code Block

{
    "channel": "Restaurant",
    "created": "2021-05-04T13:39:47Z",
    "loyaltyId": "$loyaltyUserId",
    "serviceMode": "$serviceMode",
    "status": "CLAIMED",
    "transactionDetails": {
        "appliedDiscounts": [
            {
                "details": {
                    "displayName": "20% off order",
                    "footerdiscountValue": 20,
 "Crowns expire 180 days from last purjchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms.",         "headersubtype": "Royal PerksPERCENTAGE_DISCOUNT or AMOUNT_DISCOUNT",
        "identifier": "Transaction ID: 07e5c312-9e8e-4e67-8980-f42fc499a142",         "pointsEarnedtype": "offer"Earned: 50", or "reward"
         "totalPoints       },
                "incentiveId": "Balance: 14464""$sanityIncentiveId",
                "productId": "$incentivePlu",
          },
    "receiptCode": "NCGXOZOIY2RUX5VR",
    "transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142" // uuid of loyalty transaction/order
}

Error responses

Info
All error responses use the standard Error Responses format.

...

      "referenceId": "$incentiveLoyaltyEngineId"
            }
        ],
        "currency": "USD",
        "order": [
            {
                "name": "med whopper combo",
                "price": 4.00,
                "productId": "$plu",
                "productType": "combo",
                "quantity": 1,
                "referenceId": "3",
                "tax": 0
            },
            {
                "name": "whopper",
                "parentReferenceId": "1",
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "4",
                "tax": 0
            },
            {
                "name": "med fries",
                "parentReferenceId": "1",
                "price": 0,
                "productId": "$plu",
                "productType": "item",
                "quantity": 1,
                "referenceId": "5",
                "tax": 0
            },
            {
                "incentiveId": "$sanityRewardId",
                "price": 0,
                "productId": "$rewardPlu",
                "productType": "reward",
                "quantity": 1,
                "referenceId": "3",
                "tax": 0
            }               
        ],
        "payments": [
            {
                "amount": 500,
                "type": "$paymentMethod",
                "ccToken"?: "$panToken"
            }
        ],
        "posVendor": {
            "operator": "$operatorId",
            "posType": "$posVendorName",
            "storeId": "$rbiStoreId",
            "supportingPos": "POS vendor name (optional field)", // vendor to return plu for
            "terminal": "$terminalNumber",
            "transactionId": "$posTransactionId"
        }
    },
    "transactionId": "$loyaltyTransactionId"
}

Response format

Success response body

points <number>: this represents the number of loyalty points the user has. If the order has a status of “PENDING” and includes rewards, then this number already has those loyalty points temporarily deducted from total user’s loyalty points balance. If the order has a status of “CLAIMED” this is the final point balance of the guest after the order is completed.
pointsEarned <number>: this represents the number of loyalty points the user has earned. If the order has a status of “PENDING”, then this number will always be 0 since we don’t update the guests earned loyalty points until the order is completed. If the order has a status of “CLAIMED” this is the total number of points that were earned in this order.
pointsRedeemed <number>: this represents the number of loyalty points the user has redeemed. If the order has a status of “PENDING” and includes rewards, then this number is the total loyalty points temporarily deducted from total user’s loyalty points balance. If the order has a status of “CLAIMED” this is the final number of points that were deducted / burned in this order.
loyaltyId <string>: unique identifier of the loyalty user in UUID format.
transactionId <string>: unique identifier of the loyalty transaction created in UUID format.
receiptCode <string>: autogenerated code for easy lookup of the order via support tool
presentation (optional): object that returns Receipt content information set in Sanity here.
- footer <string> (optional): this represents the content that will show in the footer of the receipt: Loyalty API v1 - Receipts
- header <string>(optional): this represents the content that will show in the header of the receipt: Loyalty API v1 - Receipts
- identifier <string>(optional): this represents the content that will show in the receipt to identify the order: Loyalty API v1 - Receipts
- pointsEarned <string>(optional): this represents the points earned that will show in the receipt of the loyalty order: Loyalty API v1 - Receipts
- totalPoints <string>(optional): this represents the total points balance that will show in the receipt of the loyalty order: Loyalty API v1 - Receipts

Success response example

Code Block

{
    "points": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", // uuid of loyalty user
    "presentation": {
        "footer": "Crowns expire 180 days from last purjchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms.",
        "header": "Royal Perks",
        "identifier": "Transaction ID: 07e5c312-9e8e-4e67-8980-f42fc499a142",
        "pointsEarned": "Earned: 50",
        "totalPoints": "Balance: 14464"
    },
    "receiptCode": "NCGXOZOIY2RUX5VR",
    "transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142" // uuid of loyalty transaction/order
}

Error responses

Info
All error responses use the standard https://rbictg.atlassian.net/wiki/spaces/RDP/pages/4231725617/LLoyalty+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:
- "TRANSACTION_NOT_CLAIMABLE" : the transaction status is not Pending or Claimed, or the transaction status in the endpoint call payload is not Pending or Claimed.
- "TRANSACTION_INSUFFICIENT_POINTS": the user want to redeem more points than the user has.
- "REDEEM_REWARD_ERROR": when the Reward is redeemed in a store with loyalty disabled.
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:
- "IdentifierNotFoundTransactionNotFoundError": if the specified identifier the transaction (specifically the transaction id) was not found.
- "StoreNotFound": if the specified storeId was not found.

Testing

Please use this Postman collection for testing purposes:

...

- .

...

Versions Compared

Old Version 8

New Version Current

Key

Body

Example request

Example request

Response format

Success response body

Success response example

Error responses

Response format

Success response body

Success response example

Error responses

Testing

Page Comparison

Versions Compared

Old Version 8

New Version Current

Key

Body

Example request

Example request

Response format

Success response body

Success response example

Error responses

Response format

Success response body

Success response example

Error responses

Testing