This API revokes an issued reward transaction, moving every user reward in the transaction from the ISSUED state to CANCELLED, and refunds the points that were consumed when the reward was issued.

Use it to reverse a mis-issued or cancelled reward so that its value does not leak. Only transactions in the ISSUED state can be revoked; a reward that has already been redeemed must be reverse-redeemed back to ISSUED before it can be revoked.

The endpoint is gated by the brand-level REVOKE_ENABLE configuration flag, which is false by default. Raise a ticket with Product support to enable this for your organisation.

Example request

curl --location --request POST 'https://eu.api.capillarytech.com/api_gateway/rewards/core/v1/user/reward/revoke?username={tillusername}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <token>' \
  --data '{
    "txnId": 9876543210,
    "revokedEventDateTime": "2026-05-13T09:32:11.000Z",
    "revokedBy": "BRAND_OPERATOR",
    "revokeReason": "VENDOR_FULFILMENT_FAILURE"
  }'

Prerequisites

• Authentication: Basic or OAuth authentication.
• The REVOKE_ENABLE brand configuration flag must be set to true for the org. It is false by default and is managed through the brand configuration API.
• The reward transaction must be in the ISSUED state.

Request query parameters

Request body parameters

Example response

{
  "status": {
    "success": true,
    "code": 200,
    "message": "Reward revoked successfully"
  },
  "txnId": 9876543210,
  "state": "CANCELLED",
  "userRewardCount": 1
}

Response parameters

Points reversal behaviour

On revoke, the points consumed during issuance are refunded through a single points reversal call for the transaction:

1. Rewards that have no points attached (free or non-points rewards) need no reversal, and the revoke proceeds to CANCELLED.
2. If the points reversal succeeds, the user rewards move to CANCELLED and the reversal reference is recorded against the revoke.
3. If the points reversal fails (the points service is unreachable, returns a non-success response, or the points could not be returned), the state does not change. The response returns code 1018 and the revoke attempt is recorded so it can be retried.

Error codes