Contents

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.

Request Format

Endpoint

PUT /loyalty/v2/changestatus

Headers

Bearer token in JWT format as specified in /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

• points <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

{
    "points": 14464,
    "pointsEarned": 50,
    "pointsRedeemed": 750,
}

Error responses

• 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.