Redemption lifecycle

Use an asynchronous redemption when fulfillment happens after you accept the request. Authorization moves the exact amount from the participant’s AVAILABLE balance to HELD and returns a PENDING redemption. Your fulfillment service then completes, fails, or cancels that redemption. Instant redemptions suit flows that can deliver immediately. Both modes use the same amount and catalog redemption endpoints.

Choose a fulfillment mode

Mode	Create behavior	Initial status	Next action
Instant	Debits `AVAILABLE` and credits the redemption target	`COMPLETED`	Deliver the reward, then reverse if a refund is needed
Asynchronous	Moves `AVAILABLE` to `HELD` under a reservation	`PENDING`	Complete, fail, or cancel before `expires_at`

Set the default on the program:

{
  "fulfillment_mode": "ASYNC",
  "pending_redemption_ttl": "24h"
}

fulfillment_mode defaults to INSTANT. pending_redemption_ttl is optional and accepts a duration from 60 seconds through 365 days. A create request can override the mode with capture:

`capture`	Behavior
`true`	Capture immediately
`false`	Authorize and return `PENDING`
Omitted	Use the program’s `fulfillment_mode`

Authorize a redemption

Set capture to false on an amount redemption:

POST /v1/participants/{participant_id}/redemptions

{
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "amount": "2500",
  "description": "Hotel transfer order 8472",
  "capture": false,
  "ttl_seconds": 86400,
  "idempotency_key": "hotel-transfer-8472"
}

Catalog item redemptions accept the same capture, expires_at, and ttl_seconds fields at POST /v1/participants/{id}/redemptions/items. The response includes the status, hold and reservation IDs, and deadline:

{
  "id": "7f422b43-4ba2-41c7-b05d-e4e90b68e978",
  "status": "PENDING",
  "amount": "2500",
  "journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "reservation_id": "d74f90be-9788-4106-852a-e4c03dcc356d",
  "expires_at": "2026-07-28T15:00:00Z"
}

For a pending redemption, journal_entry_id is the HOLD journal entry that authorized it. capture_journal_entry_id, captured_at, and resolved_at appear after successful capture. release_journal_entry_id, released_amount, and resolved_at appear after a fail, cancel, or timeout that released value.

Track catalog inventory

For a UNIT_BASED catalog reward, authorization increments both committed_units and pending_units. Capture moves the quantity from pending_units to delivered_units while committed_units stays unchanged. Failure, cancellation, and timeout decrement pending_units and committed_units without changing delivered_units. Releasing pending inventory can return an OUT_OF_STOCK reward to ACTIVE. See Rewards catalog for the full inventory contract.

Use the returned deadline

You can send one request deadline:

expires_at: absolute RFC 3339 timestamp
ttl_seconds: lifetime relative to authorization

The two fields are mutually exclusive. A request or program deadline must be at least 60 seconds and no more than 365 days. If the request and program both set a deadline, the earlier one wins. If neither sets one, Scrip uses 90 days. For a LOT asset, the redemption must complete before any selected lot expires. This can shorten the deadline. Schedule fulfillment against the expires_at returned on the redemption. If the resulting deadline is less than 60 seconds away, authorization returns 422 fulfillment_window_too_short. Capture is accepted only before the returned deadline. At or after it, the complete endpoint returns 409 reservation_expired, even if the redemption still shows PENDING.

Resolve the redemption

Send an Idempotency-Key header on complete, fail, and cancel.

Complete

Complete only after your fulfillment provider confirms delivery:

POST /v1/redemptions/{redemption_id}/complete

{}

Completion moves the authorized amount from HELD to the redemption target in one REDEMPTION journal entry and changes the redemption to COMPLETED. Capture is full-only. The amount cannot be changed during completion. An authorization can still complete while the participant is SUSPENDED because the spend was already approved. A CLOSED participant cannot be captured.

Fail

Use failure when fulfillment was attempted and could not be delivered:

POST /v1/redemptions/{redemption_id}/fail

{"reason": "provider_rejected"}

Cancel

Use cancellation when your application or the participant stops fulfillment before delivery:

POST /v1/redemptions/{redemption_id}/cancel

{"reason": "customer_cancelled"}

Fail and cancel return the reserved value still in HELD to AVAILABLE in one RELEASE journal entry. The response names that entry in release_journal_entry_id and the amount it returned in released_amount. They do not recreate LOT value that already expired. If all of the reserved value has expired, no RELEASE is created and both fields are null.

State transitions

Status	Meaning
`PENDING`	Authorized value is reserved in `HELD`
`COMPLETED`	Value reached the redemption target
`FAILED`	Fulfillment failed and live reserved value was released
`CANCELLED`	Fulfillment was cancelled and live reserved value was released
`PARTIALLY_REVERSED`	Some completed value was returned
`FULLY_REVERSED`	All completed value was returned

Only COMPLETED and PARTIALLY_REVERSED redemptions can be reversed. See Redemptions. The first terminal request wins. Repeating the same outcome returns the stored redemption. A different terminal request returns 409 redemption_already_resolved.

Ledger entries

Each transition creates one journal entry. Its action_type tells you which step a statement row or journal entry belongs to.

Transition	`action_type`	Postings
Authorize	`HOLD`	`AVAILABLE` down, `HELD` up, for the authorized amount
Complete	`REDEMPTION`	`HELD` down, redemption target up, for the authorized amount
Fail, cancel, or timeout	`RELEASE`	`HELD` down, `AVAILABLE` up, for the part still held
Reserved lot expires first	`EXPIRATION`	`HELD` down, `SYSTEM_BREAKAGE` up, for the expired lot value

The redemption’s journal_entry_id is the HOLD entry, capture_journal_entry_id is the REDEMPTION entry, and release_journal_entry_id is the RELEASE entry. released_amount is the amount the RELEASE returned to AVAILABLE. For a LOT asset, the HOLD, RELEASE, and REDEMPTION entries share one reference_id, so GET /v1/journal-entries?reference_id=... returns the full ledger history of one redemption. For a SIMPLE asset, reference_id is empty on these entries. release_journal_entry_id and released_amount are set only when reserved value was released:

Redemption	`release_journal_entry_id` and `released_amount`
`PENDING`	Null
`COMPLETED`	Null. See `capture_journal_entry_id`.
`FAILED` or `CANCELLED`, some value still held	Set. If some reserved value expired first, `released_amount` is the part still held, not the authorized `amount`.
`FAILED` or `CANCELLED`, all reserved value expired	Null. There is no `RELEASE`.

The EXPIRATION entry comes from lot expiration, not from the redemption. It has no program_id, event_id, or reference_id, so a group statement filtered by program_id leaves it out. See Lots and expiration.

Expiration and reserved lots

A reservation protects value from RELEASE, FORFEIT, and VOID_HOLD operations. It does not stop normal LOT expiration. Reserved lots keep their original expiration, maturity, and issuing program. Scrip changes an overdue PENDING redemption to FAILED with failure_reason: "expired" and creates a RELEASE for the reserved value still in HELD. Fail and cancel behave the same way. If every reserved lot already expired, there is no RELEASE, the reservation ends EXPIRED, and release_journal_entry_id stays null. That value left HELD earlier through an EXPIRATION entry.

Inventory mode	Authorization	Capture
`LOT`	Selected lots move to `HELD` under an internal reservation reference	Only those referenced lots are consumed
`SIMPLE`	A reservation claims part of the aggregate `HELD` balance	The exact reserved amount is consumed

Gift cards

Scrip handles fulfillment for gift cards. It reserves the participant’s balance, orders the card, and captures the balance when the order succeeds. Follow Gift cards for the purchase flow and Get redemption for order statuses and cancellation rules.

Webhooks and balance mirrors

Authorization emits redemption.pending and balance.held. The pending webhook includes the reservation_id and effective expires_at. A fulfillment provider can identify the reservation and schedule capture without fetching the redemption first. Capture emits redemption.completed and balance.redeemed with bucket: "HELD". An instant redemption emits redemption.completed and balance.redeemed with bucket: "AVAILABLE". Failure and timeout emit redemption.failed plus balance.released when live value is released. Cancellation emits redemption.cancelled plus balance.released when live value is released. A reversal emits redemption.reversed and balance.reversed. Every journal action has one movement event, so a participant or group balance mirror that applies every balance.* and transfer.completed event stays consistent with participant balance and statement reads. Program wallet balances cannot be reconstructed from webhooks; see Movement and lifecycle events. See Event payloads for each data object.

Time windows

The participant redemption list filters from and to by creation time, which is the authorization time for a pending redemption. Reporting recognizes redeemed value when capture succeeds, using captured_at. A redemption authorized in June and captured in July appears in a June-filtered redemption list and in July reporting. Use each surface for its stated purpose.

Redemptions

Instant redeem, catalog items, and reversals.

Webhooks

redemption.*, balance.held, balance.redeemed, and balance.released.

Lots and expiration

Reserved lots keep their original expiration.

Getting Started

Foundations

Earning

Participant State

Ledger & Balances

Spending

Operations

Advanced

Reference

Redemption lifecycle

Choose a fulfillment mode

Authorize a redemption

Track catalog inventory

Use the returned deadline

Resolve the redemption

Complete

Fail

Cancel

State transitions

Ledger entries

Expiration and reserved lots

Gift cards

Webhooks and balance mirrors

Time windows

Redemptions

Webhooks

Lots and expiration

​Choose a fulfillment mode

​Authorize a redemption

​Track catalog inventory

​Use the returned deadline

​Resolve the redemption

​Complete

​Fail

​Cancel

​State transitions

​Ledger entries

​Expiration and reserved lots

​Gift cards

​Webhooks and balance mirrors

​Time windows

Redemptions

Webhooks

Lots and expiration

Choose a fulfillment mode

Authorize a redemption

Track catalog inventory

Use the returned deadline

Resolve the redemption

Complete

Fail

Cancel

State transitions

Ledger entries

Expiration and reserved lots

Gift cards

Webhooks and balance mirrors

Time windows