Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt

Use this file to discover all available pages before exploring further.

Redemptions debit a participant’s balance via 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.

​
Amount Redemption

Debit a specific 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. Change a program’s target with Update a program: 
PATCH /v1/programs/{id}
{
  "redemption_target_type": "LEDGER_ENTITY",
  "redemption_target_entity_id": "entity-uuid"
}
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.

​
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 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 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.