Skip to main content
Redemptions spend a participant’s balance through the API. They come in two forms: an amount-based redemption for open-ended cashouts (statement credits, charitable donations), and a catalog item redemption for purchasing a specific reward. Both are triggered by your application, not by rules. Redemptions capture immediately by default. For fulfillment that happens later, authorize the amount into HELD and resolve the resulting PENDING redemption. See Redemption lifecycle.

​
Amount Redemption

Debit a specific amount from a participant’s balance:
An instant redemption debits the participant’s AVAILABLE balance and credits the program’s configured redemption target. An authorized redemption moves the amount from AVAILABLE to HELD.

​
Catalog Item Redemption

Redeem a specific item from the reward catalog:
For UNIT_BASED rewards, specify quantity (defaults to 1 if omitted). For AMOUNT_BASED rewards, specify amount instead. Catalog item redemptions accept the same capture, expires_at, and ttl_seconds lifecycle fields as amount redemptions. For UNIT_BASED rewards, the cost is quantity * unit_cost. For AMOUNT_BASED rewards, the redeemed amount itself is the cost. Either way, the cost is stored on the redemption record. For UNIT_BASED rewards, authorization and instant redemption both increment committed_units. Authorized units also increment pending_units; instantly captured units increment delivered_units. The reward status changes to OUT_OF_STOCK when committed inventory reaches max_total. 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. 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. Change a program’s target with Update a program. The program must not be archived when you change target configuration:
LEDGER_ENTITY requires redemption_target_entity_id in the same request. Switching to SYSTEM_REDEMPTION or SYSTEM_BREAKAGE must omit redemption_target_entity_id and clears any existing reference. New programs default to SYSTEM_REDEMPTION; the target cannot be set at creation time. Archived programs reject redemption target changes with 409 program_archived. Reactivate the program before changing redemption_target_type or redemption_target_entity_id.

​
Reversals

Reverse a redemption to return funds to the participant:
Omit amount or quantity for a full reversal. Include it for a partial reversal. The field must match the original redemption type: UNIT_BASED catalog redemptions accept quantity, AMOUNT_BASED and amount 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 a completed redemption’s status: The redemption tracks cumulative totals in reversed_amount and, for catalog items, reversed_quantity.

​
Inventory Restoration

For UNIT_BASED catalog items, reversals decrement committed_units, delivered_units, and the per-participant count that max_per_participant limits. 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 spent by the original redemption. Lots are restored in reverse spend order 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.
The list endpoint’s from and to filters use creation time. For a pending redemption, that is authorization time. Reporting recognizes redeemed value at capture time.

​
Requirements

Redemptions enforce these 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
Reversals enforce a shorter list:
  • Participant must be ACTIVE
  • The redemption must not already be FULLY_REVERSED
  • A partial amount or quantity must not exceed the remaining unreversed amount or quantity
Idempotency keys are scoped per program. Replaying a request with the same key and lifecycle fields returns the original record without creating a duplicate.