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. If the flag is not enabled for the org, the request is rejected.

👍

Note

• For detailed information about our APIs and for hands-on testing, refer to the documentation in API overview and the step-by-step guide on making your first API call in Make your first API call.
• All user rewards belonging to the transaction are revoked together. The points reversal is a single call for the whole transaction, because the rewards of a transaction share one redemption identifier.

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.

Resource information

API endpoint example

https://eu.api.capillarytech.com/api_gateway/rewards/core/v1/user/reward/revoke?username=swati

Request query parameters

Request body parameters

Example request

curl --location --request POST 'https://eu.api.capillarytech.com/api_gateway/rewards/core/v1/user/reward/revoke?username=swati' \
  --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"
  }'

Example response

A successful revoke returns the resulting state and the number of user rewards that were cancelled for the transaction.

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

When the points reversal could not be completed, the state is not changed and the response reports the failure. The caller should retry the revoke.

{
  "status": {
    "success": false,
    "code": 1018,
    "message": "Failed to reverse points"
  },
  "txnId": 9876543210
}

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.

API-specific error codes

The endpoint returns HTTP 200 in all cases. The outcome is conveyed through the status object in the response body. The table below lists the status.code values and the symbolic name of each.