...
| Table of Contents | ||
|---|---|---|
|
Overview
This document explains how Loyalty API endpoints must be used with Reward combos for NCR point of sale system.
Identify
When a guest scans an identification code on a POS or Kiosk, they may pre-select offers or rewards. For Rewards, NCR expects use to provide them w/ a new field called eligibleDiscounts that tells their system which item needs to be marked as free.
| Info |
|---|
Note: This field is completely optional, it helps the cashier register a reward at an earlier step, but we can still provide this property for any of the subsequent update calls. |
Example Request
| Code Block |
|---|
{
"identifier": "$digitCode or $loyaltyId",
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
} |
Example Response
| Code Block |
|---|
{
"balances": [
{
"amount": 14464,
"currency": "points"
}
],
"eligibleDiscounts": [
{
"details": {
"displayName": "some display name",
"type": "REWARD or OFFER"
},
"productId": "$benefitPlu",
"referenceId": "$loyaltyIncentiveId"
}
],
"loyaltyUser": {
"created": "2021-08-10T12:18:39.180Z",
"id": "$loyaltyUserId",
"name": "$loyaltyUserName"
},
"order": [
{
"name": "Whopper",
"productId": "$incentivePlu",
"referenceId": "00"
}
],
"transactionId": "$loyaltyTransactionId"
} |
Update (Pending)
NCR will call us w/ with two update calls. The first one will send a status of PENDING. This first call will have appliedDiscounts with no referenceId (engine id which will later use to apply the discount on our side). If the user pre-selected a reward prior to identifying OR the cart contains an upsize plu, NCR expects us to return an eligibleDiscounts field that points to the entry being discounted, the pointer used is the orderReferenceId. The orderReferenceId must match the referenceId of the cart entry that needs to be discounted from the request body.
For combos, NCR will provide all the combo slots in the appliedDiscounts array. Each entry will have a comboId (the combo document plu) and comboInstanceId which will be unique identifier for us to group all of the slots for one particular combo entry.
...
Example request
| Code Block |
|---|
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"loyaltyId": "$loyaltyUserId",
"serviceMode": "$serivceMode",
"status": "PENDING",
"transactionDetails": {
"currency": "USD",
"appliedDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": ""
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": ""
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": ""
},
{
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"comboInstanceId": "$uniqueIdPerCombo",
"comboId": "$comboPlu",
"orderReferenceId": "4",
"productId": "400102",
"referenceId": ""
}
],
"order": [
{
"name": "Meal selection",
"price": 0,
"productId": "9088",
"productType": "product",
"quantity": 1,
"referenceId": "6",
"tax": 0
},
{
"name": "WHOPPER",
"price": 6.49,
"productId": "110",
"productType": "product",
"quantity": 1,
"referenceId": "7",
"tax": 0
},
{
"name": "REGULAR FRIES ML",
"price": 2.39,
"productId": "713",
"productType": "product",
"quantity": 1,
"referenceId": "8",
"tax": 0
},
{
"name": "REGULAR COKE",
"price": 2.82,
"productId": "400102",
"productType": "product",
"quantity": 1,
"referenceId": "9",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CREDIT",
"ccToken": "$panToken"
},
{
"amount": 400,
"type": "CASH"
},
{
"amount": 1000,
"type": "SUBTOTAL"
},
{
"amount": 300,
"type": "DISCOUNTS"
},
{
"amount": 200,
"type": "TAXES"
}
],
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
},
"transactionId": "$loyaltyTransactionId"
} |
...
Example response
| Code Block |
|---|
{
"eligibleDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"orderReferenceId": "4",
"productId": "400102",
"referenceId": "$loyaltyIncentiveId"
}
],
"points": 102220,
"pointsEarned": 5000,
"pointsRedeemed": 0,
"loyaltyId": "$loyaltyUserId",
"presentation": {
"footer": "Crowns expire 180 days from last purchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms",
"header": "Royal Perks",
"identifier": "Transaction ID: $loyaltyTransactionId",
"pointsEarned": "Earned: 5000",
"totalPoints": "Balance: 102220"
},
"receiptCode": "J25QL1WAH5KJ7P75",
"transactionId": "$loyaltyTransactionId"
} |
Update (Claimed)
NCR will call us w/ with two update calls. The second call will send a status of CLAIMED which will include any appliedDiscounts for rewards / upsizes that was given to the user. Unlike the first call, these entries will contain a referenceId for us to reconcile with the customer’s preselected rewards.
...
Example request
| Code Block |
|---|
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"loyaltyId": "$loyaltyUserId",
"serviceMode": "$serivceMode",
"status": "PENDING",
"transactionDetails": {
"currency": "USD",
"appliedDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"orderReferenceId": "4",
"productId": "400102",
"referenceId": "$loyaltyIncentiveId"
}
],
"order": [
{
"name": "Meal selection",
"price": 0,
"productId": "9088",
"productType": "product",
"quantity": 1,
"referenceId": "6",
"tax": 0
},
{
"name": "WHOPPER",
"price": 6.49,
"productId": "110",
"productType": "product",
"quantity": 1,
"referenceId": "7",
"tax": 0
},
{
"name": "REGULAR FRIES ML",
"price": 2.39,
"productId": "713",
"productType": "product",
"quantity": 1,
"referenceId": "8",
"tax": 0
},
{
"name": "REGULAR COKE",
"price": 2.82,
"productId": "400102",
"productType": "product",
"quantity": 1,
"referenceId": "9",
"tax": 0
}
],
"payments": [
{
"amount": 500,
"type": "CREDIT",
"ccToken": "$panToken"
},
{
"amount": 400,
"type": "CASH"
},
{
"amount": 1000,
"type": "SUBTOTAL"
},
{
"amount": 300,
"type": "DISCOUNTS"
},
{
"amount": 200,
"type": "TAXES"
}
],
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
},
"transactionId": "$loyaltyTransactionId"
} |
...
Example response
| Code Block |
|---|
{
"eligibleDiscounts": [
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER Meal",
"type": "REWARD"
},
"orderReferenceId": "1",
"productId": "9088",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "WHOPPER",
"type": "REWARD"
},
"orderReferenceId": "2",
"productId": "110",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR FRIES ML",
"type": "REWARD"
},
"orderReferenceId": "3",
"productId": "713",
"referenceId": "$loyaltyIncentiveId"
},
{
"comboId": "$comboPlu",
"comboInstanceId": "$uniqueIdPerCombo",
"details": {
"displayName": "REGULAR COKE",
"type": "REWARD"
},
"orderReferenceId": "4",
"productId": "400102",
"referenceId": "$loyaltyIncentiveId"
}
],
"points": 102220,
"pointsEarned": 5000,
"pointsRedeemed": 0,
"loyaltyId": "$loyaltyUserId",
"presentation": {
"footer": "Crowns expire 180 days from last purchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms",
"header": "Royal Perks",
"identifier": "Transaction ID: $loyaltyTransactionId",
"pointsEarned": "Earned: 5000",
"totalPoints": "Balance: 102220"
},
"receiptCode": "J25QL1WAH5KJ7P75",
"transactionId": "$loyaltyTransactionId"
} |
...