Skip to main content
POST
Complete a pending redemption
Captures the reservation backing a PENDING redemption. The full authorized amount moves from the participant’s HELD balance to the stored redemption target, and the response changes to COMPLETED. Call this endpoint before the returned expires_at. A late request returns 409 reservation_expired. Repeating completion after it succeeds returns the stored redemption; a different terminal outcome returns 409 redemption_already_resolved.
For deadline selection, state transitions, and ledger 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

Body

application/json

Completion details

idempotency_key
string

Reconciled with the Idempotency-Key header when both are supplied

Example:

"complete-12345"

Response

Redemption completed or same-outcome replay

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"