Purpose

This endpoint is used when a client device (typically a POS or Kiosk terminal) would like to change the status of a loyalty order. This endpoint will only change the status to CLAIMED (in the case an order is completed successfully) or VOID (in the case the order needs to be cancelled).

When an order status is changed to CLAIMED both points burned and earned are permanently updated in the guest’s account. When an order status is changed to VOID both points earned and burned of that order will be reversed back to the guest. A loyalty order must exist for this endpoint to be called; therefore, it must be used after Identify (POST) has been called.

Note: when an order has the status of VOID, it can no longer be changed to CLAIMED.

Request Format

Endpoint

PUT /loyalty/transaction/v2/status

Headers

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

Body

newStatus <string>: the status that this order must change to, either CLAIMED or VOID
transactionId <UUID>: unique identifier of the transaction.

Example request

{
    "newStatus": "CLAIMED",
    "transactionId": "f4190848-169d-4c69-9f53-f916318c432b"
}

Response Format

Success response body

balance <number>: this represents the number of loyalty points the user has after the change of status is complete. If the order changes to a status of "CLAIMED" this is the final point balance of the guest after the order is completed. If the order changes to a status of "VOID" this is the final point balance after the order has been cancelled and guest loyalty points reversed.
pointsEarned <number>: this represents the number of loyalty points the user has earned with this change of status. If the order changes to a status of "CLAIMED" this is the total number of points that were earned in this order. If the order changes to a status of "VOID" this is the total number of points that were earned when the guest’s loyalty points were reversed.
pointsRedeemed <number>: this represents the number of loyalty points the user has redeemed with this change of status. If the order changes to a status of "CLAIMED" this is the final number of points that were deducted / burned in this order. If the order changes to a status of "VOID" this is the final number of points that were deducted from the user balance after the cancellation of the order is complete.

Success response example (status CLAIMED)

{
    "balance": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
    "loyaltyId": "4711fc2a-3a8f-414f-a9e7-44dd5231dca7", 
        "footer": "Crowns expire 180 days from last purjchase. At participating U.S. restaurants. Terms at bk.com/rewards-terms.",
        "header": "My Burger King",
        "identifier": "Transaction ID: 07e5c312-9e8e-4e67-8980-f42fc499a142",
        "pointsEarned": "Earned: 50",
        "totalPoints": "Balance: 14464"
    },
    "receiptCode": "NCGXOZOIY2RUX5VR",    
}

Error responses

All error responses use the standard Loyalty API v1 - Error Responses format.

HTTP 400 (Bad Request) if the either identifier or transactionId are not included with the request body, or if these parameters have an incorrect format.
HTTP 401 (Unauthorized) if the bearer token is missing or not valid.
HTTP 404 (Not Found): in the following scenarios indicated in the code field of the error response:
- "CodeNotFound": the specified identifier has not been found;
- "TransactionNotFound": the specified transaction has not been found.
HTTP 403 (Forbidden): if the specified identifier was generated for a different transactionId.
HTTP 422 (Unprocessable Entity): if the specified payload cannot be processed.
- "StatusUnchangeable": if the current status of the transaction means it cannot be updated to a new status (for example, if the current status is 'VOID' it cannot be updated to 'CLAIMED').

RBI Developer Portal

Change Status (PUT)

Analytics