Create an order with loyalty

Introduction

This article discusses a scenario for applying loyalty system bonuses and discounts to an order on a restaurant website.

The basics of interaction between a restaurant website and r_k Delivery are described in the articles API Capabilities.

Basic scenario for creating an order with loyalty bonuses:

Receiving a preliminary estimate of the order
Creating an order
The order is transferred to the cash register manually or automatically
Loyalty at checkout is applied to the order.

Presets

Set up your establishment in r_k Delivery
Set up integration with r_k Loyalty
Set up an API connection for the website backend or restaurant app backend
Enable guest authorization by phone number on the website.

Guest authorization by phone number is necessary for communication with the guest database in r_k Delivery and r_k Loyalty, as well as for user identification on the website: this way you can control that the guest uses his own bonuses, and not someone else's.

Pre-calculation method

To obtain guest loyalty data, it is necessary to use the pre-order calculation method. This method should be used after filling in the order details: contents, delivery method, etc. and authorizing the guest.

Request:

HTTP POST /orders/api/v1/orders/delivery

CODE

Example request:

HTTP POST https://delivery.ucs.ru/orders/api/v1/orders/delivery

CODE

Example of request body data:

{
   "dishList":[
      {
         "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
         "name":"Mimosa Salad",
         "price":200,
         "discount":0,
         "schemeId":"",
         "description":"",
         "imageUrls":[
            
         ],
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ],
         "isListStoped":false
      }
   ],
   "address":null,
   "expectedAt":"2022-06-16T09:41:08.278+03:00",
   "soonest":true,
   "useLoyalty":true,
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65",
   "phone":"71111111111",
   "expeditionType":"pickup",
   "useLoyaltyBonusPayments":false,
   "orderId":"",
   "manualDiscounts":[
   ],
   "loyaltyPromo":[
      "PROMOCODE1"
   ],
   "hideLoader":true
}

CODE

Parameter	Parameter type	Description
dishList	array	order contents
-id	string	dish id (GUID format) from the Delivery menu view, which is used to synchronize with the cash register
-name	string	name of the dish
-price	double the separator will always be a period - "."	price of the dish
-discount	double	discount
-measure		measure
--value	double	serving size
--unit	string	unit of measurement: kg, liter, pcs. The meaning is not a dictionary one.
-quantity	double the separator will always be a period - "."	number of dishes
-ingredients	array	ingredients
--id	string	ingredient id (GUID format) from the Delivery menu view, which is used to sync with the cash register
--name	string	name of ingredient
--price	double the separator will always be a period - "."	ingredient price
--quantity	double the separator will always be a period - "."	quantity of ingredient
--ingredients	array	modifiers
---id	string	modifier id (GUID format) from the Delivery menu view, which is used for synchronization with the cash register
---name	string	modifier name
---price	double the separator will always be a period - "."	modifier price
---quantity	double the separator will always be a period - "."	modifier amount
-isListStoped	string	is it in the out-of-stock list
address		delivery address In case of self-pickup, it takes the value null. For an example of parameters when specifying an address, see the article Creating an order
expectedAt	DateTime	time by which the order is expected
soonest	bool	deliver the order as soon as possible If it evaluates to true, then the expectedAt parameter value does not need to be sent: the system will calculate it automatically. If it evaluates to false, then the expectedAt parameter is required.
useLoyalty	bool	using loyalty in order Returns true if loyalty is used. Returns false if not used.
restaurantId	string	restaurant id
phone	string	guest phone number
expeditionType	string	delivery type
useLoyaltyBonusPayments	string	rewarding loyalty points
orderId	string	order id
manualDiscounts		manual discounts If loyalty is applied, the parameter is not used. For information on using manual discounts, see the article Creating an order with a cash discount.
loyaltyPromo	string array	List of promo codes to apply

Parameters responsible for loyalty:

useLoyalty — indicates whether the guest intends to use the loyalty program
useLoyaltyBonusPayments — indicates whether the guest intends to use loyalty bonuses
phone — guest phone number. This is the main parameter responsible for linking the order with the loyalty program, since r_k Loyalty identifies the guest by phone number.

Accumulation or redemption of loyalty points

Here's an example of a pre-calculation method response if points accumulation or redemption occurs under the loyalty program:

{
   "result":{
      "amount":{
         "totalAmount":100.00,
         "orderAmount":200.00,
         "deliveryAmount":0.0,
         "discountDeliveryAmount":null,
         "minOrderAmountFreeDelivery":0.0,
         "needForFree":0.0,
         "dishList":[
            {
               "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
               "name":"Mimosa Salad",
               "price":200.0,
               "measure":{
                  "value":0.0,
                  "unit":""
               },
               "quantity":1.0,
               "ingredients":[
                  
               ],
               "discount":0.0
            }
         ],
         "loyaltyAmount":{
            "totalAmount":100.00,
            "loyaltyDiscountAmount":100.0,
            "bonuses":{
               "guestBalance":1230.58,
               "rankName":"Platinum\t",
               "maxBonusesForPayment":100.0,
               "accrualWithPayment":5.0,
               "accrualWithoutPayment":10.0
            },
            "loyaltyPrograms":[
               
            ],
            "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOjE3NzY2NDAzNzYsIkRpc2NvdW50U3VtIjowLjB9",
            "useRkLoyalty":true,
            "useLoyaltyBonusPayments":true
         },
         "discounts":{
            "useRk7Discounts":false,
            "total":100.0,
            "discount":0.0,
            "discountList":[
               
            ]
         }
      },
      "times":{
         "deliveryTime":360
      }
   }
}

CODE

where:

loyaltyAmount — block containing loyalty data
- totalAmount — total order amount
- loyaltyDiscountAmount — total discount amount for the order, including bonuses, if they will be redeemed
- bonuses — block responsible for guest loyalty points data
  - guestBalance — current guest loyalty points balance
  - rankName — current guest rank.
  - maxBonusesForPayment — the maximum number of loyalty points available for write-off for this guest
  - accrualWithPayment — how many loyalty points will be accumulated if there is a write-off of points in this order
  - accrualWithoutPayment — how many loyalty points will be accumulated if there is no write-off of points in this order.

Loyalty program discount

Example of a pre-calculation method response if a loyalty program discount can be applied:

{
   "result":{
      "amount":{
         "totalAmount":1260.00,
         "orderAmount":1400.00,
         "deliveryAmount":0.0,
         "discountDeliveryAmount":null,
         "minOrderAmountFreeDelivery":0.0,
         "needForFree":0.0,
         "dishList":[
            {
               "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
               "name":"Mimosa Salad",
               "price":200.0,
               "measure":{
                  "value":0.0,
                  "unit":""
               },
               "quantity":7.0,
               "ingredients":[
                  
               ],
               "discount":0.0
            }
         ],
         "loyaltyAmount":{
            "totalAmount":1260.00,
            "loyaltyDiscountAmount":140.0,
            "bonuses":{
               "guestBalance":1230.58,
               "rankName":"Platinum\t",
               "maxBonusesForPayment":0.0,
               "accrualWithPayment":0.0,
               "accrualWithoutPayment":0.0
            },
            "loyaltyPrograms":[
               {
                  "programName":"Basic promotion: 10% discount on check for checks over $10",
                  "programNotification":[
                     "You received a 10% discount on the promotion \"Basic promotion discount on the check 10% for a check from $10\"."
                  ]
               }
            ],
            "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOi0zNDA5MTI4NTMsIkRpc2NvdW50U3VtIjoxNDAuMDB9",
            "useRkLoyalty":true,
            "useLoyaltyBonusPayments":true
         },
         "discounts":{
            "useRk7Discounts":false,
            "total":1260.0,
            "discount":0.0,
            "discountList":[
               
            ]
         }
      },
      "times":{
         "deliveryTime":360
      }
   }
}

CODE

where:

loyaltyAmount — block containing loyalty data
- totalAmount — total order amount
- loyaltyDiscountAmount — total discount amount for the order, including loyalty points, if they will be written off
- loyaltyPrograms[] — block of data about the executed action
  - programName — name of the loyalty program
  - programNotification[] — discount message, which is set in the r_k Loyalty admin panel.

Discount with promo code

Example of a pre-calculation method response if a loyalty promo code discount can be applied:

{
   "result":{
      "amount":{
         "totalAmount":1300.00,
         "orderAmount":1400.00,
         "deliveryAmount":0.0,
         "discountDeliveryAmount":null,
         "minOrderAmountFreeDelivery":0.0,
         "needForFree":0.0,
         "dishList":[
            {
               "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
               "name":"Mimosa Salad",
               "price":200.0,
               "measure":{
                  "value":0.0,
                  "unit":""
               },
               "quantity":7.0,
               "ingredients":[
                  
               ],
               "discount":0.0
            }
         ],
         "loyaltyAmount":{
            "totalAmount":1300.00,
            "loyaltyDiscountAmount":100.0,
            "bonuses":{
               "guestBalance":1230.58,
               "rankName":"Platinum\t",
               "maxBonusesForPayment":0.0,
               "accrualWithPayment":0.0,
               "accrualWithoutPayment":0.0
            },
            "loyaltyPrograms":[
               {
                  "programName":"Discount using promotional code PROMOCODE1",
                  "programNotification":[
                     "You received a discount of $1.49 using the promo code PROMOCODE1."
                  ]
               }
            ],
            "loyaltyPromo": [ "PROMOCODE1" ]
            "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOi0zNDA5MTI4NTMsIkRpc2NvdW50U3VtIjoxNDAuMDB9",
            "useRkLoyalty":true,
            "useLoyaltyBonusPayments":true
         },
         "discounts":{
            "useRk7Discounts":false,
            "total":1300.0,
            "discount":0.0,
            "discountList":[
               
            ]
         }
      },
      "times":{
         "deliveryTime":360
      }
   }
}

CODE

where:

loyaltyAmount — block containing loyalty data
- totalAmount — total order amount
- loyaltyDiscountAmount — total discount amount for the order, including loyalty points, if they will be written off
- loyaltyPrograms[] — block of data about the executed program
  - programName — name of the loyalty program
  - programNotification[] — discount message, which is set in the r_k Loyalty admin panel.

Creating an order

After specifying the order details and the pre-calculation method is triggered, you need to create an order.

Example request:

POST https://delivery.ucs.ru/orders/api/v1/orders

Content-Type: application/json

CODE

Example of request body data:

{
   "comment":"",
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65",
   "persons":1,
   "expeditionType":"pickup",
   "paymentTypeId":"cash",
   "courierId":"",
   "soonest":true,
   "expectedAt":"2022-06-16T10:07:08.278+03:00",
   "dishList":[
      {
         "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
         "name":"Mimosa Salad",
         "price":200,
         "discount":0,
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":7,
         "ingredients":[
            
         ]
      },
      {
         "id":"b5a5e2e8-958e-765c-2822-d5cf7c60df7d",
         "name":"Mimosa Salad",
         "price":200,
         "discount":0,
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ]
      }
   ],
   "changeFrom":null,
   "guest":{
      "firstName":"Denis",
      "lastName":"",
      "phone":"71111111111",
      "email":null
   },
   "loyaltyCalculation":{
      "loyaltyDiscountAmount":160,
      "totalAmount":1440,
      "loyaltyPrograms":[
         {
            "programName":"Basic promotion: 10% discount on check for checks over $10",
            "programNotification":[
               "You received a 10% discount on the promotion \"Basic promotion discount on the check 10% for a check from $10\"."
            ]
         }
      ],
      "bonuses":{
         "guestBalance":1230.58,
         "rankName":"Platinum\t",
         "maxBonusesForPayment":0,
         "accrualWithPayment":0,
         "accrualWithoutPayment":0
      },
      "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOjI1NzQ0ODc3OSwiRGlzY291bnRTdW0iOjE2MC4wMH0=",
      "useRkLoyalty":true,
      "useLoyaltyBonusPayments":true
   },
   "discounts":{
      "discount":0,
      "total":1440,
      "discountList":[
         
      ],
      "useRk7Discounts":false
   },
   "discountDeliveryAmount":null
}

CODE

where

loyaltyCalculation — block of data obtained in the order pre-calculation method in the loyaltyAmount block.

For more information about the request and parameters, see the article Creating an order.

Example answer:

{
   "result":{
      "orderId":"123"
   }
}

CODE

where orderId is the order number.

Editing an order

To edit an order after it has been created, you must reset the order's pre-calculation. If you do not do this, you may have problems with freezing guest loyalty points. To reset the pre-calculation, use the method:

HTTP POST https://delivery.ucs.ru/orders/api/v1/orders/{orderId}/resetLoyalty

CODE

where orderId is the order number that was received in the response to the create order method. For example, 123, as in the response above.

The request body is empty.

Next, make a request for a pre-calculation with the order number. Request example:

HTTP POST https://delivery.ucs.ru/orders/api/v1/orders/delivery
{
   "dishList":[
      {
         "id":"66a506b9-ce54-26f6-c582-dc884f7d02f3",
         "name":"Cheeseburger",
         "price":100,
         "discount":0,
         "schemeId":"",
         "description":"",
         "imageUrls":[
            
         ],
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ]
      }
   ],
   "address":null,
   "expectedAt":"2022-06-16T10:14:58.502+03:00",
   "useLoyalty":true,
   "restaurantId":"18f550d8-7fbe-45fa-8c83-35f531380f65",
   "phone":"72222222222",
   "expeditionType":"pickup",
   "useLoyaltyBonusPayments":false,
   "orderId":"128763",
   "manualDiscounts":[
      
   ],
   "hideLoader":true
}

CODE

Only after a repeated request for a pre-calculation can you begin editing the order. Example of a method for requesting order editing:

HTTP PATCH https://delivery.ucs.ru/orders/api/v1/orders/{orderId}

CODE

Request body example:

{
   "paymentTypeId":"cash",
   "dishList":[
      {
         "id":"66a506b9-ce54-26f6-c582-dc884f7d02f3",
         "name":"Cheeseburger",
         "price":100,
         "discount":0,
         "measure":{
            "value":0,
            "unit":""
         },
         "isContainInStopList":[
            
         ],
         "quantity":1,
         "ingredients":[
            
         ]
      }
   ],
   "loyaltyCalculation":{
      "loyaltyDiscountAmount":0,
      "totalAmount":100,
      "loyaltyPrograms":[
         
      ],
      "bonuses":{
         "guestBalance":3.21,
         "rankName":"Bronze",
         "maxBonusesForPayment":3.21,
         "accrualWithPayment":1.94,
         "accrualWithoutPayment":2
      },
      "fingerPrint":"eyJQYXR0ZXJuIjowLCJPcmRlckhhc2giOi0xODU2ODkwNDM2LCJEaXNjb3VudFN1bSI6MC4wfQ==",
      "useRkLoyalty":true,
      "useLoyaltyBonusPayments":false
   }
}

CODE

where

loyaltyCalculation — block of data obtained in the last order pre-calculation method in the loyaltyAmount block.

For more information about the request and parameters, see the article Changing an order.