Purpose

This endpoint is used to add items to the basket of an existing Loyalty transaction by using the client app’s user interface.

Add and remove offers/rewards to the basket of an existing Loyalty transaction, either by scanning pre-selected offers/rewards, or by using the client app’s user interface.
Validate an entire basket

Request Format

Endpoint

PUT /loyalty/transaction/v2/update

Headers

Bearer token in JWT format as specified in https://rbictg.atlassian.net/wiki/spaces/IN/pages/3739288100.

Body

transactionId <UUID>: unique identifier of the Loyalty transaction to be updated.
cart: an array that includes objects with the below fields for each product that is in the order basket.
- externalreferenceId <string>: PLU of the product that was pre-selected in the app. This can be an offer or a reward.
- quantity <number>: the amount of the above product that is in the loyalty order.
- price <number>: price in cents of the product.
- type <string>: the type of product. It could be Reward, Offer, Item or Combo
- menuSelections(optional): an array that includes combos or sub-items within the product.
  - externalreferenceId <string>: PLU of the menu selection within the product that was pre-selected in the app. This can be a combo or item PLU.
  - quantity <number>: the amount of the above product that is in the loyalty order.
  - price :
    - amount: <number>: price amount in cents of the product.
    - currency: <string>: type of currency i.e USD / EUR etc
  - type <string>: the type of product. It could be Item or Combo
  - menuSelections(optional): an array that includes sub-items within a specific product.
payments: an array that includes objects with payment breakdown for the order (e.g. taxes, subtotal, total and fees).
userDateTime: user local date time.

Example request

Example request of a cart with an offer combo and reward item

{
    "transactionId": "f4190848-169d-4c69-9f53-f916318c432b",
    "cart": {
        "menuSelections": [
            {
                "externalReferenceId": "948920",
                "quantity": 1,
                "menuSelections": [
                    {
                        "externalReferenceId": "948920",
                        "quantity": 1,
                        "menuSelections": [
                            {
                                "externalReferenceId": "560014",
                                "quantity": 2,
                                "price": {
                                    "amount": 0,
                                    "currency": "EUR"
                                },
                                "id": "367953b0-cbf0-42ab-a08c-88f4da49584d",
                                "type": "Item"
                            }
                        ],
                        "price": {
                            "amount": 550,
                            "currency": "EUR"
                        },
                        "id": "9430f9bb-dce8-4740-82f0-b44780c4454d",
                        "type": "Combo"
                    }
                ],
                "price": {
                    "amount": 550,
                    "currency": "EUR"
                },
                "id": "0bfad3b8-a1da-4356-af14-a9b1e8b91da3",
                "type": "Offer"
            },
            {
                "externalReferenceId": "2244",
                "menuSelections": [
                    {
                        "externalReferenceId": "100-1-1",
                        "menuSelections": [],
                        "quantity": 1,
                        "price": {
                            "currency": "USD",
                            "amount": 0
                        },
                        "type": "Item"
                    }
                ],
                "quantity": 1,
                "type": "Reward"
            }
        ]
    },
    "payments": {
        "tax": {
            "currency": "USD",
            "amount": 100
        },
        "subTotal": {
            "currency": "USD",
            "amount": 100
        },
        "total": {
            "currency": "USD",
            "amount": 100
        },
        "fees": [
            {
                "type": "BAG_FEE",
                "total": {
                    "currency": "USD",
                    "amount": 100
                }
            }
        ]
    },
    "userDateTime": "2025-03-18T17:30:16+08:00"  // 2025-03-18T17:30:16 is the local date time, +08:00 is the UTC offset
}

Example request of a cart with an cart level discount

{
  "transactionId": "f4190848-169d-4c69-9f53-f916318c432b",
  "orderDiscounts": [
    {
      "type": "amount",
      "value": 200,
      "plu": "D-107"
    }
  ],
  "cart": [
    "menuSelections": [
      {
        "externalReferenceId": "100-1-1",
        "id": "7403727e-949c-42b6-a544-5f2124e17c5c",
        "menuSelections": [
          {
            "externalReferenceId": "101-1-1",
            "id": "item_11177",
            "menuSelections": [],
            "price": {
              "amount": 0,
              "currency": "EUR"
            },
            "quantity": 1,
            "type": "Item"
          },
          {
            "externalReferenceId": "102-1-1",
            "id": "2d874c0a-37da-406e-a50e-cd3cd9c5c710",
            "menuSelections": [],
            "price": {
              "amount": 0,
              "currency": "EUR"
            },
            "quantity": 1,
            "type": "Item"
          }
        ],
        "price": {
          "amount": 425,
          "currency": "EUR"
        },
        "quantity": 1,
        "type": "Combo"
      },
      {
        "externalReferenceId": "D-107", // Oracle Discount ID
        "id": "08e4ccf5-23fc-4bc7-a800-a7703e7228c6",
        "menuSelections": [],
        "price": {
          "amount": 0,
          "currency": "EUR"
        },
        "quantity": 1,
        "type": "Offer"
      }
    ],
  ],
  "payments": {
    "tax": {
      "currency": "USD",
      "amount": 100
    },
    "subTotal": {
      "currency": "USD",
      "amount": 100
    },
    "total": {
      "currency": "USD",
      "amount": 100
    },
    "fees": [
      {
        "type": "BAG_FEE",
        "total": {
          "currency": "USD",
          "amount": 100
        }
      }
    ]
  },
  "userDateTime": "2025-03-18T17:30:16+08:00"
}

Example request of a reward product level discount

{
  "transactionId": "f4190848-169d-4c69-9f53-f916318c432b",
  "cart": [
    "menuSelections": [
    {
      "externalReferenceId": "D-106", // Oracle Discount ID
      "menuSelections": [
        {
          "externalReferenceId": "100-1-1",
          "menuSelections": [],
          "quantity": 1,
          "price": {
                    "currency": "USD",
                    "amount": 229
          },
          "type": "Item"
        }
      ],
      "quantity": 1,
      "type": "Reward"
    },
        {
          "externalReferenceId": "100-1-1",
          "menuSelections": [
            {
              "externalReferenceId": "101-1-1",
              "menuSelections": [],
              "quantity": 1,
              "type": "Item"
            },
            {
              "externalReferenceId": "102-1-1",
              "menuSelections": [],
              "quantity": 1,
              "type": "Item"
            },
            {
              "externalReferenceId": "103-1-1",
              "menuSelections": [],
              "quantity": 1,
              "type": "Item"
            }
          ],
          "quantity": 1,
          "price": {
            "currency": "USD",
            "amount": 200
          },
          "type": "Combo"
        }
      ],
  ],
  "payments": {
    "tax": {
      "currency": "USD",
      "amount": 100
    },
    "subTotal": {
      "currency": "USD",
      "amount": 100
    },
    "total": {
      "currency": "USD",
      "amount": 100
    },
    "fees": [
      {
        "type": "BAG_FEE",
        "total": {
          "currency": "USD",
          "amount": 100
        }
      }
    ]
  },
  "userDateTime": "2025-03-18T17:30:16+08:00"
}

Response Format

Success response body

balance <number>: this represents the number of loyalty points the user has. The order has a status of “PENDING” and includes rewards, so this number already has those loyalty points temporarily deducted from total user’s loyalty points balance.
pointsEarned <number>: this represents the number of loyalty points the user has earned. The order has a status of “PENDING”, so this number will always be 0 since we don’t update the guests earned loyalty points until the order is completed.
pointsRedeemed <number>: this represents the number of loyalty points the user has redeemed. The order has a status of “PENDING” and includes rewards, so this number is the total loyalty points temporarily deducted from total user’s loyalty points balance.
loyaltyId <string>: unique identifier of the loyalty user in UUID format.
transactionId <string>: unique identifier of the loyalty transaction created in UUID format.

Success response example

{
    "balance": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "transactionId": "07e5c312-9e8e-4e67-8980-f42fc499a142"
}

Error response example

{
    "code": "RulesError",
    "details": {
        "ruleEvaluation": [
            {
                "code": "invalid-service-mode",
                "currentValue": "TAKEOUT",
                "message": "Service mode is not in the list of valid
                "ruleId": "service-mode",
                "targetValue": [
                    "EAT_IN"
                ],
                "externalReferenceId": "2244"
            },
        ],
        "isEngineError": true,
        "errorConfig": {
            "transitional": {
                "silentJSONParsing": true,
                "forcedJSONParsing": true,
                "clarifyTimeoutError": false
            },
            "transformRequest": [
                null
            ],
            "transformResponse": [
                null
            ],
            "timeout": 0,
            "xsrfCookieName": "XSRF-TOKEN",
            "xsrfHeaderName": "X-XSRF-TOKEN",
            "maxContentLength": -1,
            "maxBodyLength": -1,
            "headers": {
                  "Accept": "application/json, text/plain, */*",
                  "Content-Type": "application/json",
                  "x-api-key": "************************************HyaM",
                  "x-region": "DE",
                  "x-request-id": "cla8q5fzx000e36i03wsmhejq",
                  "User-Agent": "axios/0.26.1",
                  "Content-Length": 1397
            },
            "method": "post",
            "data": "__REDACTED__",
            "url": "{{url}}"
        } 
    }
}

Error responses

All error responses use the standard Loyalty 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.
HTTP 401 (Unauthorized) if the bearer token is missing or not valid.
HTTP 403 (Forbidden): if the specified identifier is not valid.
HTTP 404 (Not Found): if the specified storeId was not found.

Update Cart (PUT)