Skip to main content
POST
Cancel a pending redemption
Marks a PENDING redemption as CANCELLED and returns the reserved value still in HELD to AVAILABLE in one RELEASE journal entry. Include an optional reason to record why fulfillment stopped. The response names that entry in release_journal_entry_id and the amount it returned in released_amount. Reserved LOT value can expire before cancellation. The RELEASE returns only the part still held and never recreates expired value. If all of the reserved value has expired, no RELEASE is created and both fields are null. Repeating cancellation returns the stored redemption; a different terminal outcome returns 409 redemption_already_resolved.
For expiration and terminal state 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

Cancellation details

idempotency_key
string

Reconciled with the Idempotency-Key header when both are supplied

Example:

"fail-12345"

reason
string

Optional fulfillment failure or cancellation reason (1-500 chars)

Required string length: 1 - 500
Example:

"provider_rejected"

Response

Redemption cancelled 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"

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"