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. PENDING responses include reservation_id and expires_at. A successful completion adds capture_journal_entry_id, captured_at, and resolved_at. Failed and cancelled redemptions include resolved_at and can include failure_reason. 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.

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"

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

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"