Time	Status	User Agent
Retrieving recent requests…

This API reverses a redemption, moving every user reward in the transaction from the REDEEMED state back to ISSUED.

Use it to undo a redemption that was recorded in error, for example when a voucher was marked as redeemed by mistake or a return/exchange means the reward should become usable again. Only transactions in the REDEEMED state can be reverse-redeemed.

The endpoint is gated by the brand-level REVERSE_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 reverse-redeemed together. If any one of them is not in the REDEEMED state, the entire request is rejected and none of them change state.

A successful reverse-redeem also triggers a rewardRedemptionReversed event notification, if configured. See Supported Events.

Prerequisites

Authentication: Basic or OAuth authentication.
The REVERSE_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 REDEEMED state.

Request query parameters

Field	Type	Required	Description
`username`	string	Optional	Store identifier used for gateway authentication, consistent with other reward APIs.

Request body parameters

Field	Type	Required	Description
`txnId`	integer	Required	Transaction ID of the issuance transaction whose rewards are to be reverse-redeemed. This is the reward issuance transaction ID returned at the time of issuance.
`redemptionReversedEventDateTime`	string	Optional	The date and time at which the reversal happened at the source, in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`). Defaults to the processing time if not provided.
`redemptionReversedBy`	string	Optional	Identifier of the actor who initiated the reversal, for example `BRAND_OPERATOR`. Stored against the reversal record for audit.
`redemptionReversalReason`	string	Optional	Reason for reversing the redemption, for example `INCORRECT_REDEMPTION`. Stored against the reversal record for audit.

API Quick Reference

POST /api_gateway/rewards/core/v1/user/reward/reverse-redeem
   ├─ Request
   │   ├─ txnId (integer)
   │   ├─ redemptionReversedEventDateTime (string)
   │   ├─ redemptionReversedBy (string)
   │   └─ redemptionReversalReason (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/reverse-redeem?username=swati' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <token>' \
  --data '{
    "txnId": 9876543210,
    "redemptionReversedEventDateTime": "2026-05-13T09:32:11.000Z",
    "redemptionReversedBy": "BRAND_OPERATOR",
    "redemptionReversalReason": "INCORRECT_REDEMPTION"
  }'

Example response

A successful reverse-redeem returns the resulting state and the number of user rewards that were moved back to ISSUED for the transaction.

{
  "status": {
    "success": true,
    "code": 200,
    "message": "Reward redemption reversed successfully"
  },
  "txnId": 9876543210,
  "state": "ISSUED",
  "userRewardCount": 1
}

When the transaction's user rewards are not all in the REDEEMED 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

Field	Type	Description
`status`	object	Object containing the outcome of the request.
`.success`	boolean	Indicates whether the reverse-redeem succeeded.
`.code`	integer	Status code for the outcome. `200` indicates success; other values indicate the failure reason. See API-specific error codes.
`.message`	string	Human-readable description of the outcome.
`txnId`	integer	Transaction ID that was reverse-redeemed, echoed from the request.
`state`	string	Resulting state of the transaction's user rewards. Returned as `ISSUED` only when the reverse-redeem succeeds.
`userRewardCount`	integer	Number of user rewards transitioned to `ISSUED` for the transaction. Returned only when the reverse-redeem succeeds.

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.

Code	Symbolic name	Message	When it occurs
200	`REWARD_REVERSE_REDEEMED_OK`	Reward redemption reversed successfully	The transaction was reverse-redeemed and its rewards moved back to `ISSUED`.
400	—	must not be null	The required `txnId` field is missing from the request body.
400	`INVALID_REQUEST`	Invalid date format: `<value>`	`redemptionReversedEventDateTime` was provided but is not a valid ISO 8601 date-time.
13002	`REVERSE_REDEEM_FEATURE_NOT_ENABLED`	Reverse-redeem feature is not enabled for this brand	The `REVERSE_REDEEM_ENABLE` flag is `false` for the org.
13003	`INVALID_REWARD_STATE`	Transaction is not in the required state for this operation	One or more user rewards in the transaction are not in the `REDEEMED` state.
10007	`TRANSACTION_NOT_FOUND`	Transaction not found	No transaction exists for the provided `txnId`.
10008	`USER_REWARD_NOT_FOUND`	User reward not found	The transaction exists but has no associated user rewards.

Note