Skip to main content
Redemptions debit a participant’s balance via the API. They cover point cashouts, catalog item purchases, and any other spend that happens outside of rules. You might use a raw redemption to let someone cash out points for a statement credit, or a catalog redemption to let them buy a gift card from your rewards store.

​
Raw Redemption

Debit an arbitrary amount from a participant’s balance: 
POST /v1/participants/{id}/redemptions
{
  "program_id": "program-uuid",
  "asset_id": "asset-uuid",
  "amount": "1000",
  "description": "Cash out request #12345",
  "idempotency_key": "cashout-12345"
}
FieldRequiredDescription
program_idYesProgram context
asset_idYesWhich asset to debit
amountYesPositive decimal amount
descriptionYesReason for the redemption (1-500 characters)
idempotency_keyNoPrevents duplicate redemptions on retry. Same key + different payload returns 409.
The amount is debited from the participant’s AVAILABLE balance and credited to the program’s configured redemption target.

​
Catalog Item Redemption

Redeem a specific item from the reward catalog: 
POST /v1/participants/{id}/redemptions/items
{
  "program_id": "program-uuid",
  "reward_id": "reward-uuid",
  "quantity": 2,
  "idempotency_key": "order-789"
}
For UNIT_BASED rewards, specify quantity (defaults to 1 if omitted). For AMOUNT_BASED rewards, specify amount instead. The cost is calculated from the reward’s unit_cost and stored on the redemption record. For UNIT_BASED rewards, inventory is tracked: redeemed_count increments globally and per participant, and the reward status changes to OUT_OF_STOCK when max_total is reached. See Rewards Catalog for setting up catalog items.

​
Redemption Targets

Each program configures where redeemed funds flow via redemption_target_type. Most programs use SYSTEM_REDEMPTION to keep redeemed value separate from breakage.
TargetDescription
SYSTEM_REDEMPTIONDefault. Tracks redeemed value in a dedicated system account.
SYSTEM_BREAKAGECombines with forfeited value in the breakage account.
LEDGER_ENTITYRoutes to a specific ledger entity. Requires redemption_target_entity_id on the program.
The target is captured on the redemption record at creation time. If you change the program’s target configuration later, existing redemptions and their reversals still use the original target. This keeps the ledger consistent.

​
Reversals

Reverse a redemption to return funds to the participant: 
# Full reversal
POST /v1/redemptions/{id}/reverse
{
  "reason": "Order cancelled by customer",
  "idempotency_key": "refund-123"
}

# Partial reversal (amount-based)
POST /v1/redemptions/{id}/reverse
{
  "amount": "500",
  "reason": "Partial refund for damaged item",
  "idempotency_key": "refund-456"
}

# Partial reversal (unit-based, whole units only)
POST /v1/redemptions/{id}/reverse
{
  "quantity": 1,
  "reason": "Customer returned 1 gift card",
  "idempotency_key": "refund-789"
}
Omit amount or quantity for a full reversal. Include it for a partial reversal. The type must match the original redemption: UNIT_BASED redemptions accept quantity, AMOUNT_BASED and raw redemptions accept amount. reason is required (1-500 characters). Reversals are often reviewed during disputes or audits, so every reversal needs a human-readable explanation on record.

​
Reversal Status

Each reversal updates the redemption’s status:
StatusMeaning
COMPLETEDNo reversals applied
PARTIALLY_REVERSEDSome amount or quantity reversed, more can follow
FULLY_REVERSEDEntire redemption reversed, no further reversals allowed
The redemption tracks cumulative totals in reversed_amount and, for catalog items, reversed_quantity.

​
Inventory Restoration

For UNIT_BASED catalog items, reversals decrement redeemed_count and the per-participant redemption_count. If a reward was OUT_OF_STOCK and the reversal brings inventory below max_total, the reward status returns to ACTIVE.

​
Lot Restoration

For LOT-mode assets, reversals restore the specific lots consumed by the original redemption. Lots are restored in LIFO order (last in, first out) and retain their original metadata including expires_at and matures_at.

​
Viewing Redemptions

You can list redemptions per participant, fetch a single redemption by ID, or list the reversals attached to a redemption. 
# List participant redemptions
GET /v1/participants/{id}/redemptions

# Get redemption details
GET /v1/redemptions/{id}

# List reversals for a redemption
GET /v1/redemptions/{id}/reversals

​
Requirements

Both redemptions and reversals enforce the same base checks:
  • Participant must be ACTIVE
  • Program must be ACTIVE (not SUSPENDED or ARCHIVED)
  • Asset must not be archived
  • Sufficient AVAILABLE balance for the requested amount
  • For catalog items: reward must be ACTIVE and within its availability window
Idempotency keys are scoped per program. Replaying a request with the same key returns the original record without creating a duplicate.