This API redeems an issued reward transaction, moving every user reward in the transaction from the ISSUED state to REDEEMED.

Use it to mark a reward as consumed once the customer has actually used it (for example, a voucher scanned in-store or a coupon applied at checkout). Only transactions in the ISSUED state can be redeemed.

The endpoint is gated by the brand-level REDEEM_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 redeemed together. If any one of them is not in the ISSUED state, the entire request is rejected and none of them are redeemed.
• A successful redeem also triggers a rewardRedeemed event notification, if configured. See Supported Events.

Prerequisites

• Authentication: Basic or OAuth authentication.
• The REDEEM_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

API Quick Reference

POST /api_gateway/rewards/core/v1/user/reward/redeem
   ├─ Request
   │   ├─ txnId (integer)
   │   └─ redeemedAtEventDateTime (string)
   └─ Response
       ├─ status
       │   ├─ success (boolean)
       │   ├─ code (integer)
       │   └─ message (string)
       ├─ txnId (integer)
       ├─ state (string)
       └─ userRewardCount (integer)

Example request

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

Example response

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

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

When the transaction's user rewards are not all in the ISSUED state, the state is not changed and the response reports the failure.

{
  "status": {
    "success": false,
    "code": 13003,
    "message": "Transaction is not in the required state for this operation"
  },
  "txnId": 9876543210
}

Response parameters

API-specific error codes

The endpoint returns HTTP 200 for every outcome once the request reaches the business logic, with the outcome conveyed through the status object in the response body. The one exception is a missing required txnId, which fails standard request validation before the business logic runs and returns a raw HTTP 400. The table below lists the status.code values and the symbolic name of each.