Skip to main content
GET
Get redemption
Returns a single redemption by its ID. The response includes the asset, amount, description, associated reward for catalog redemptions, fulfillment fields, and reversal state. journal_entry_id is the HOLD entry for a pending redemption, or the REDEMPTION entry for an instant one. PENDING responses include reservation_id and expires_at. A successful completion adds capture_journal_entry_id, which is the REDEMPTION entry, plus captured_at and resolved_at. Failed and cancelled redemptions include resolved_at and can include failure_reason. A timeout sets failure_reason to expired. When value was released, they also carry release_journal_entry_id, the RELEASE entry, and released_amount, the amount it returned to AVAILABLE. Both are null when all of the reserved value had expired, because there is no RELEASE. Check reversed_amount only for COMPLETED and PARTIALLY_REVERSED redemptions when deciding whether another reversal is valid.
For state transitions and deadline behavior, see the Redemption lifecycle guide.

Gift-card fulfillment

Gift-card redemptions include a nested fulfillment object describing the order. The redemption’s own status describes the balance spend. This endpoint never returns a claim link; use Create a claim link after fulfillment succeeds. The redemption stays PENDING while fulfillment is in progress. Successful fulfillment captures the held balance. Failure releases the live reserved balance and changes the redemption to FAILED, or CANCELLED when you cancelled it. The AWAITING_FUNDS window is set by awaiting_funds_window_hours and defaults to 24 hours. If that window expires before the account is funded, fulfillment fails with insufficient_funds. The reservation’s deadline can end fulfillment sooner. Funding can move the order back to PROCESSING or directly to SUCCEEDED.

Failure reasons

Completion, cancellation, and reversal

Scrip completes gift-card redemptions automatically after the order succeeds. Calling complete on a pending one returns 409 fulfillment_managed. Calling it again after completion returns the existing record with 200. You can fail or cancel a gift-card redemption only while fulfillment.status is PENDING or AWAITING_FUNDS and no vendor order has been placed. Otherwise, those endpoints return 409 fulfillment_in_progress. Once the card is delivered, reversal returns 409 fulfillment_delivered.

Authorizations

X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

id
string<uuid>
required

Redemption ID

Response

Redemption details

amount
string

Total amount debited from the participant's balance (decimal string)

Example:

"1000.00"

asset_id
string<uuid>

The asset that was debited

Example:

"550e8400-e29b-41d4-a716-446655440003"

capture_journal_entry_id
string<uuid>

Ledger entry that captured a pending redemption

Example:

"550e8400-e29b-41d4-a716-446655440007"

captured_at
string<date-time>

When the pending redemption was captured

Example:

"2024-01-15T10:45:00Z"

created_at
string<date-time>

When this redemption was created

Example:

"2024-01-15T10:30:00Z"

description
string

Context for this redemption, used in journal entries

Example:

"Redeemed: Gift Card"

expires_at
string<date-time>

Effective deadline of the backing reservation. Always present for pending redemptions; defaults to 90 days and may be configured up to one year.

Example:

"2024-01-15T11:30:00Z"

failure_reason
string

Machine-readable or operator-supplied terminal failure detail

Example:

"fulfillment_failed"

fulfillment
object

Gift-card vendor order status, present only for provider-backed (fulfillment) redemptions

id
string<uuid>

Unique identifier for this redemption

Example:

"550e8400-e29b-41d4-a716-446655440000"

journal_entry_id
string<uuid>

Immutable ledger anchor: the hold entry for pending redemptions, otherwise the instant redemption entry

Example:

"550e8400-e29b-41d4-a716-446655440005"

participant_id
string<uuid>

The participant who redeemed

Example:

"550e8400-e29b-41d4-a716-446655440002"

program_id
string<uuid>

The program this redemption belongs to

Example:

"550e8400-e29b-41d4-a716-446655440001"

quantity
integer

Number of units redeemed (catalog redemptions only)

Example:

2

release_journal_entry_id
string<uuid>

Ledger entry that released a pending redemption's reserved value back to AVAILABLE. Present only on FAILED and CANCELLED redemptions whose reservation resolved RELEASED; null while PENDING, after capture (see capture_journal_entry_id), and when every reserved lot had already expired before release (the reservation resolved EXPIRED and no release entry was posted).

Example:

"550e8400-e29b-41d4-a716-446655440008"

released_amount
string

Amount the release entry returned to AVAILABLE (decimal string). Equals the authorized amount unless part of the reserved value expired before release, in which case only the live remainder is reported. Present exactly when release_journal_entry_id is present.

Example:

"1000.00"

reservation_id
string<uuid>

Reservation backing a pending redemption

Example:

"550e8400-e29b-41d4-a716-446655440006"

resolved_at
string<date-time>

When the pending redemption reached a terminal state

Example:

"2024-01-15T10:45:00Z"

reversed_amount
string

Cumulative amount reversed so far (decimal string)

Example:

"0.00"

reversed_quantity
integer

Cumulative units reversed so far (UNIT_BASED catalog redemptions only)

Example:

0

reward_id
string<uuid>

The reward catalog item that was redeemed (catalog redemptions only)

Example:

"550e8400-e29b-41d4-a716-446655440004"

status
enum<string>

Current lifecycle and reversal state

Available options:
PENDING,
COMPLETED,
FAILED,
CANCELLED,
PARTIALLY_REVERSED,
FULLY_REVERSED
Example:

"COMPLETED"

unit_cost
string

Cost per unit at the time of redemption (catalog redemptions only, decimal string)

Example:

"500.00"

updated_at
string<date-time>

When this redemption was last updated (e.g., after a reversal)

Example:

"2024-01-15T10:30:00Z"