Offers & Rewards - Payload Format

By Silva, Carlos
8 min

Please note the RBI payloads in this documented have been deprecated. For an up to date list of the RBI payloads, please refer to: Orders API - Cart Structure Examples | Cart Structures

 

Requirements for the JSON payload to be sent by the Partners API to Khumbu.

Contents

Reward payload structures

Rewards are an item benefit that can be redeemed in exchange for points (and sometimes money + points). Read more about it here: Rewards - Getting Started .

Oracle documentation: Configuration Guide

Online

  • 0 Priced reward item - discount it 100%.

    • discounts have a discount ID.

    • each offer / reward has a unique discount ID

In Restaurant

  • 0 priced reward item - pre select and offer and reward. discount it 100%.

Next steps:

  • Send all offer and reward information to Oracle team. Multiple different discounts that can be used (100% discount off, item price substitution)

  • Talk with TRX team about Rewards with prices + loyalty points (using item price substitution discount)

  • Have internal discussion and setup a call with Oracle team to validate

  • Understand if there are any implications to analytics (understanding the difference between offers and rewards)

 

 

Reward with an item

"cart": [ { "menuSelections": [ { "id": "7ee7338a-a016-47c6-aef6-3783d40c003e", // Reward Sanity id "externalReferenceId": "123", // Reward constant plu defined in Sanity "quantity": 1, "price": { "amount": 0, "currency": "SAR", } "type": "Reward", "menuSelections": [ { "externalReferenceId": "51056", // item constant plu "id": "item_1862", // item Sanity id "menuSelections": [], "price": { "amount": 2495, // normal price "currency": "SAR" }, "quantity": 1, "type": "Item" } ] } ] } ]
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}} }, "menuItems": [], "comboMeals": [ { "comboMealId": 51002003, // Cheeseburger reward "comboItem": { "menuItemId": 51002003, // Cheeseburger reward PLU "definitionSequence": 1, "quantity": 1 }, "mainItem": { "menuItemId": 1002003, // A la carte cheeseburger "definitionSequence": 1, "quantity": 1 }, "sideItems": [] } ], "tenders": [ { "tenderId": 901 // payment method ID. Pay at Counter for this example. } ] }

In Oracle, we use a separate combo for reward items so that we can set up a different price (0) vs the single item ALC. Alternatively, we could create a new priceSequence set to 0 for each definitionSequence , and then re-use the single item.

Oracle can only handle up to 10,000 combos.

Reward with an item + premium modifier

"cart": [ { "menuSelections": [ { "id": "7ee7338a-a016-47c6-aef6-3783d40c003e", // Reward Sanity id "externalReferenceId": "123", // Reward constant plu defined in Sanity "quantity": 1, "price": { "amount": 0, "currency": "SAR", } "type": "Reward", "menuSelections": [ { "externalReferenceId": "51056", // item constant plu "id": "item_1862", // item Sanity id "menuSelections": [], "price": { "amount": 2495, // normal price "currency": "SAR" }, "quantity": 1, "type": "Item" } ] } ] } ]
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}}, "language": "es-ES", "Accept-Language": "es-ES" }, "menuItems": [], "comboMeals": [ { "comboMealId": 51002003, // Cheeseburger reward "comboItem": { "menuItemId": 51002003, // Cheeseburger reward "definitionSequence": 1, "quantity": 1 }, "mainItem": { "menuItemId": 1002003, // Cheeseburger ALC "definitionSequence": 1, "quantity": 1, "condiments": [ { "condimentId": 9011005, // Add bacon. Premium modifier (extra cost) "priceSequence": 2, "quantity": 2 } ] }, "sideItems": [] } ], "tenders": [ { "tenderId": 901 } ] }

Reward with a combo

"cart": { "menuSelections": [ { "externalReferenceId": "8351", // reward plu "id": "43b4cf07-79c9-4aff-98d1-bce9cf2d890f", //reward sanity id "menuSelections": [ { "externalReferenceId": "8350", // combo plu "id": "43b4cf07-79c9-4aff-98d1-bce9cf2d890f", //combo sanity id "menuSelections": [ { "externalReferenceId": "10059", "id": "item_1852", "menuSelections": [], "price": { "amount": 0, "currency": "SAR" }, "quantity": 1, "type": "Item" }, { "externalReferenceId": "80007", "id": "4f99db1e-128a-4e53-b23b-dffc0fedf636", "menuSelections": [], "price": { "amount": 0, "currency": "SAR" }, "quantity": 1, "type": "Item" }, { "externalReferenceId": "80001", "id": "16f482db-2f13-4476-88d3-d2eec26057f3", "menuSelections": [], "price": { "amount": 0, "currency": "SAR" }, "quantity": 1, "type": "Item" }, { "externalReferenceId": "141139", "id": "141139", "menuSelections": [], "price": { "amount": 0, "currency": "SAR" }, "quantity": 1, "type": "Item" } ], "price": { "amount": 300, // original price of combo "currency": "SAR" }, "quantity": 1, "type": "Combo" } ], "price": { "amount": 0, // final price of the reward "currency": "SAR" }, "quantity": 1, "type": "Reward" } ] },
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}}, "language": "es-ES", "Accept-Language": "es-ES" }, "menuItems": [], "comboMeals": [ { "comboMealId": 51001504, //Whopper with Cheese Combo Reward "comboItem": { "menuItemId": 51001504, //Whopper with Cheese Combo Reward "definitionSequence": 1, "quantity": 1 }, "mainItem": { "menuItemId": 1001003, // Whopper with cheese ALC "definitionSequence": 1, "quantity": 1 }, "sideItems": [ { "menuItemId": 1013201, //Small pepsi "definitionSequence": 1, "quantity": 1 }, { "menuItemId": 2102002, //Small fries "definitionSequence": 1, "quantity": 1 } ] } ], "tenders": [ { "tenderId": 901 } ] }

Reward with a combo + premium modifier

{ "payload": { "number": "5848", "fees": [ { "total": { "amount": 19, "currency": "EUR" }, "type": "BAG_FEE" } ], "serviceMode": "DELIVERY", "channel": "WHITELABEL_DELIVERY", "callbackUrl": "https://euw3-staging-bk-partners-api.rbictg.com/api/v1/orders/15c3dbe1-5165-404b-8858-088239d14014/price/callback", "id": "15c3dbe1-5165-404b-8858-088239d14014", "storeId": "12349", "cart": { "menuSelections": [ { "externalReferenceId": "948351", "quantity": 1, "menuSelections": [ { "externalReferenceId": "502617", "quantity": 1, "menuSelections": [ { "externalReferenceId": "502633", "quantity": 1, "menuSelections": [ { "externalReferenceId": "528232", "quantity": 1, "price": { "amount": 90, "currency": "EUR" }, "id": "8ba0df7b35df", "type": "ItemOptionModifier" } ], "price": { "amount": 0, "currency": "EUR" }, "id": "item_11107", "type": "Item" }, { "externalReferenceId": "942258", "quantity": 1, "price": { "amount": 0, "currency": "EUR" }, "id": "item_11126", "type": "Item" }, { "externalReferenceId": "527646", "quantity": 1, "price": { "amount": 0, "currency": "EUR" }, "id": "9aac0a46-5a73-431d-937c-8848ca01ac86", "type": "Item" } ], "price": { "amount": 875, "currency": "EUR" }, "id": "a2e73fd9-5f3d-4afc-9585-43ebd7bbc6dc", "type": "Combo" } ], "price": { "amount": 450, "currency": "EUR" }, "id": "024f9096-e3ee-45fc-8f76-d75e272ff9e9", "type": "Reward" } ] } } }
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}}, "language": "es-ES", "Accept-Language": "es-ES" }, "menuItems": [], "comboMeals": [ { "comboMealId": 51001504, // Whopper Cheese combo reward "comboItem": { "menuItemId": 51001504, //// Whopper Cheese combo reward "definitionSequence": 1, "quantity": 1 }, "mainItem": { "menuItemId": 1001003, // whopper cheese "definitionSequence": 1, "quantity": 1, "condiments": [ { "condimentId": 9011005, // Add bacon. Premium modifier (extra cost) "priceSequence": 2, "quantity": 2 } ] }, "sideItems": [ { "menuItemId": 1013201, // Small fries "definitionSequence": 1, "quantity": 1 }, { "menuItemId": 2000008, // Icy mango. Premium drink (extra cost) "definitionSequence": 1, "quantity": 1 } ] } ], "tenders": [ { "tenderId": 901 } ] }

Reward with a cart discount

The reward is the cart discount. You use points to buy a discount.

"payload": { "number": "5803", "fees": [ { "total": { "amount": 19, "currency": "EUR" }, "type": "BAG_FEE" } ], "serviceMode": "DELIVERY", "channel": "WHITELABEL_DELIVERY", "callbackUrl": "https://euw3-staging-bk-partners-api.rbictg.com/api/v1/orders/60c1983c-8cbc-4aa8-9486-c55fa78566f5/price/callback", "id": "60c1983c-8cbc-4aa8-9486-c55fa78566f5", "orderDiscounts": [ { "type": "amount", "value": 200 } ], "storeId": "12349", "cart": { "menuSelections": [ { "externalReferenceId": "502633", "quantity": 1, "price": { "amount": 645, "currency": "EUR" }, "id": "item_11107", "type": "Item" } ] } }

Note: the cart discount can be also sent with a plu inside the orderDiscounts object. Please refer to “Reward with a product discount” section for an example.

{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}} }, "menuItems": [ { "menuItemId":1001001, // Whopper ALC "definitionSequence": 1, "quantity": 1 } ], "tenders": [ { "tenderId": 901 } ], "discounts" : [ { "discountId": 104, // PLU for the cart level amount discount "referenceText": "Reward 1234", "total": 10 // the amount that you are discounting. 10 euros off. We can send whatever amount we want } ] }

Reward with a product discount

{ "payload": { "number": "5807", "fees": [ { "total": { "amount": 19, "currency": "EUR" }, "type": "BAG_FEE" } ], "serviceMode": "DELIVERY", "channel": "WHITELABEL_DELIVERY", "callbackUrl": "https://euw3-staging-bk-partners-api.rbictg.com/api/v1/orders/781f28e9-d6bb-4c8e-9ea6-e65a2e7c3764/price/callback", "id": "781f28e9-d6bb-4c8e-9ea6-e65a2e7c3764", "orderDiscounts": [ { "plu": "948348", "type": "percentage", "value": 50 } ], "storeId": "12349", "cart": { "menuSelections": [ { "externalReferenceId": "948348", "quantity": 1, "menuSelections": [ { "externalReferenceId": "502633", "quantity": 1, "price": { "amount": 0, "currency": "EUR" }, "id": "item_11107", "type": "Item" } ], "price": { "amount": 645, "currency": "EUR" }, "id": "fbdead97-5acb-4d1c-a5fe-5794ece61aaa", "type": "Reward" } ] } } }
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}} }, "menuItems": [ { "menuItemId": 1001001, // Whopper "definitionSequence": 1, "quantity": 1, "itemDiscounts": [ { "discountId": 104, // PLU of the product amount discount off "referenceText": "Reward Item Discount", "total": 59 // amount of discount (can be sent as any number). 59 pesos off the whopper ALC price. } ] } ], "tenders": [ { "tenderId": 901 } ] }

Offer Payload Structure

Offers are a discount on the order or item. Can take the form of a discounted bundle, cheaper item, order-level % discount, or order-level $ off. Also known as a “coupon” in some markets. Read more about it here: Offers - Getting Started .

Offer with an item

As with rewards, Oracle also creates a separate combo for an item offer.

{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}} }, "menuItems": [], "comboMeals": [ { "comboMealId": 4000045, // Offer PLU for vanilla cone "comboItem": { "menuItemId": 4000045, // Offer PLU for vanilla cone "definitionSequence": 1, "quantity": 1 }, "mainItem": { "menuItemId": 1014013, // Vanilla Cone ALC "definitionSequence": 1, "quantity": 1 }, "sideItems": [] } ], "tenders": [ { "tenderId": 901 } ] }

Offer with a combo

"cart": { "menuSelections": [ { "externalReferenceId": "8351", // offer plu "id": "43b4cf07-79c9-4aff-98d1-bce9cf2d890f", //offer sanity id "menuSelections": [ { "externalReferenceId": "8167", // combo plu "id": "d90a7113-0620-44d9-b678-743330a2f207", //combo sanity id "menuSelections": [ { "externalReferenceId": "80003", "id": "ce847c79-9eb5-4be3-8a1e-842919aa5ba0", "menuSelections": [], "price": { "amount": 0, "currency": "SAR" }, "quantity": 1, "type": "Item" }, { "externalReferenceId": "142538", "id": "142538", "menuSelections": [], "price": { "amount": 0, "currency": "SAR" }, "quantity": 1, "type": "Item" } ], "price": { "amount": 500, //price of the combo "currency": "SAR" }, ], "price": { "amount": 100, // final price of the offer "currency": "SAR" }, "quantity": 1, "type": "Offer" } ] },
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}} }, "menuItems": [], "comboMeals": [ { "comboMealId": 4000045, // Buy one Cone, Get one Cone for free Offer PLU "comboItem": { "menuItemId": 4000045, // Buy one Cone, Get one Cone for free Offer PLU "definitionSequence": 1, "quantity": 1 }, "sideItems": [{ "menuItemId": 1014013, // Vanilla Cone (could be any selection of cones) "definitionSequence": 1, "quantity": 1 }, { "menuItemId": 1014012, // Strawberry Cone (could be any selection of cones) "definitionSequence": 1, "quantity": 1 }] } ], "tenders": [ { "tenderId": 901 } ] }

Offer with a cart discount

{ "payload": { "number": "5814", "fees": [ { "total": { "amount": 19, "currency": "EUR" }, "type": "BAG_FEE" } ], "serviceMode": "DELIVERY", "channel": "WHITELABEL_DELIVERY", "callbackUrl": "https://euw3-staging-bk-partners-api.rbictg.com/api/v1/orders/6d66a02e-810f-478f-bf0d-b69bfcb56d51/price/callback", "id": "6d66a02e-810f-478f-bf0d-b69bfcb56d51", "orderDiscounts": [ { "type": "percentage", "value": 20 } ], "storeId": "12349", "cart": { "menuSelections": [ { "externalReferenceId": "502633", "quantity": 1, "price": { "amount": 645, "currency": "EUR" }, "id": "item_11107", "type": "Item" } ] } } }
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}} }, "menuItems": [ { "menuItemId":1001001, // Whopper ALC "definitionSequence": 1, "quantity": 1 } ], "tenders": [ { "tenderId": 901 } ], "discounts" : [ { "discountId": 106, // PLU for the cart level percent discount "referenceText": "Offer 1234", "total": 0.10 // the percentage that you are discounting. 10% off. We can send whatever percentage we want } ] }

Offer with a product discount

{ "payload": { "number": "5821", "fees": [ { "total": { "amount": 19, "currency": "EUR" }, "type": "BAG_FEE" } ], "serviceMode": "DELIVERY", "channel": "WHITELABEL_DELIVERY", "callbackUrl": "https://euw3-staging-bk-partners-api.rbictg.com/api/v1/orders/ed50be10-cf7c-4b1c-8bb1-0c2625cbf3be/price/callback", "id": "ed50be10-cf7c-4b1c-8bb1-0c2625cbf3be", "orderDiscounts": [ { "plu": "502617", "type": "percentage", "value": 20 } ], "storeId": "12349", "cart": { "menuSelections": [ { "externalReferenceId": "502617", "quantity": 1, "menuSelections": [ { "externalReferenceId": "502633", "quantity": 1, "price": { "amount": 0, "currency": "EUR" }, "id": "item_11107", "type": "Item" }, { "externalReferenceId": "942258", "quantity": 1, "price": { "amount": 0, "currency": "EUR" }, "id": "item_11126", "type": "Item" }, { "externalReferenceId": "527646", "quantity": 1, "price": { "amount": 0, "currency": "EUR" }, "id": "9aac0a46-5a73-431d-937c-8848ca01ac86", "type": "Item" } ], "price": { "amount": 875, "currency": "EUR" }, "id": "a2e73fd9-5f3d-4afc-9585-43ebd7bbc6dc", "type": "Offer" } ] } } }
{ "header": { "orgShortName": "{{OrgShortName}}", "locRef": "{{LocRef}}", "rvcRef": {{RvcRef}}, "idempotencyId": "{{$guid}}", "orderTypeRef": 9, "checkEmployeeRef": {{check_employee_ref}} }, "menuItems": [ { "menuItemId": 1001001, // Whopper "definitionSequence": 1, "quantity": 1, "itemDiscounts": [ { "discountId": 106, // PLU of the product percent discount off "referenceText": "Offer Item Discount", "total": 0.50 // percentage discount (can be sent as any percentage). 50% off the whopper ALC price. } ] } ], "tenders": [ { "tenderId": 901 } ] }

Reference

NMS guides on how to set up offers and rewards in Sanity for Oracle: https://rbictg.atlassian.net/wiki/spaces/MS/pages/4057661622

Related content