Loyalty API - NCR Incentives
- Lopes da Costa, Valentina
- Silva, Carlos
Contents
Overview
This document explains how Loyalty API endpoints must be used with 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. In that case, the Loyalty API v1 - Identify endpoint will return an eligibleDiscounts field on the response. This will contain any offer or reward that was pre-selected.
Note: NCR expects us to provide them a field called eligibleDiscounts that tells their system which products needs to be repriced. This field is completely optional, it helps the cashier register an incentive at an earlier step, but we can still provide this property for any of the subsequent update calls.
Example request
Note: This first version should not contain an orderReferenceId. This is used to tell NCR’s system which order line this discount should be applied to. We won’t know this till later steps when NCR provides us with a cart.
Note: For Pickers, the same eligibleDiscounts object will be returned in the response along with all potential picker options. On a later step, we will attempt to reconcile these options with what NCR provides on appliedDiscounts, which tells us which picker option was selected
{
"identifier": "$digitCode or $loyaltyId",
"posVendor": {
"matchingId": "$smgCode",
"operator": "$operatorId",
"posType": "$posVendorName",
"storeId": "$rbiStoreId",
"terminal": "$terminalNumber",
"transactionId": "$posTransactionId"
}
}Example response
{
"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 with two update calls. The first one will send a status of PENDING and will not have any discounts applied. If the user pre-selected an incentive 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.
Example request
{
"channel": "Restaurant",
"created": "2021-05-04T13:39:47Z",
"loyaltyId": "$loyaltyUserId",
"serviceMode": "$serivceMode",
"status": "PENDING",
"transactionDetails": {
"currency": "USD",
"appliedDiscounts": [
{
"details": {
"displayName": "some display name"
},
"orderReferenceId": "1",
"productId": "$benefitPlu",
"referenceId": ""
}
],
"order": [
{
"name": "some incentive name",
"price": 0,
"productId": "$benefitPlu",
"productType": "item",
"quantity": 1,
"referenceId": "1",
"tax": 0
},
{
"name": "med fries",
"price": 0,
"productId": "$plu",
"productType": "item",
"quantity": 1,
"referenceId": "2",
"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
Â
Update (Claimed)
NCR will call us with two update calls. The second call will send a status of CLAIMED which will include any appliedDiscounts for incentives that was given to the user on the final cart state. Using the referenceId on each entry, we can determine which incentives we should keep as applied on our final transaction state.
Example request
Example response
Â