---
title: "Redeem a catalog item"
method: POST
path: "/v1/participants/{participant_id}/redemptions/items"
tags: ["Redemptions"]
---

# Redeem a catalog item

`POST /v1/participants/{participant_id}/redemptions/items`

## Request

- Base URL: `https://api.scrip.dev`
- URL: `https://api.scrip.dev/v1/participants/{participant_id}/redemptions/items`
- Auth: HTTP bearer

Redeem a reward catalog item for a participant. Capture immediately or authorize into a PENDING redemption backed by a ledger reservation.

## Path parameters

- `participant_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- RedeemItemRequest: Redeems a catalog reward for a participant.
  - `amount` string: Asset amount for custom AMOUNT_BASED rewards. For managed rewards, supply fulfillment.face_value instead.
  - `capture` boolean: Whether to capture immediately. True completes instantly, false authorizes, and omission uses the program fulfillment_mode.
  - `description` string: Optional context for this redemption, used in journal entries (max 500 chars)
  - `expected_amount` string: Expected total cost in asset units. If the current cost differs, no redemption is created (409 reward_price_changed). Retries compare against the original redemption's amount.
  - `expires_at` string, date-time: Absolute pending-redemption deadline (RFC3339); alternative to ttl_seconds and limited to one year. If no request or program deadline is set, the authorization defaults to 90 days.
  - `fulfillment` RedeemItemFulfillmentRequest: The gift-card details for a catalog item redemption, such as the face value.
    - `face_value` Money: A fiat amount: an integer count of the currency's minor units, such as cents, and the ISO 4217 currency code.
      - `amount_minor` integer, required: Amount in the currency's minor units, such as cents for USD
      - `currency` string, required: ISO 4217 currency code
  - `idempotency_key` string: Your key for this redemption. You can send it in the Idempotency-Key header instead; when both are sent they must match.
  - `program_id` string, uuid, required: The program this redemption belongs to
  - `quantity` integer: Number of units to redeem. Defaults to 1; managed rewards require exactly 1.
  - `reward_id` string, uuid, required: The reward catalog item to redeem
  - `ttl_seconds` integer: Relative pending-redemption deadline in seconds; alternative to expires_at and limited to one year. If no request or program deadline is set, the authorization defaults to 90 days.

## Response `201`

Redemption created

- RedemptionResponse: A redemption: value a participant spent, with its status and fulfillment.
  - `amount` string: Total amount debited from the participant's balance (decimal string)
  - `asset_id` string, uuid: The asset that was debited
  - `capture_journal_entry_id` string, uuid: Ledger entry that captured a pending redemption
  - `captured_at` string, date-time: When the pending redemption was captured
  - `created_at` string, date-time: When this redemption was created
  - `description` string: Context for this redemption, used in journal entries
  - `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.
  - `failure_reason` string: Machine-readable or operator-supplied terminal failure detail
  - `fulfillment` RedemptionFulfillmentSummary: The current fulfillment outcome of a redemption, such as the provider order and any failure reason.
    - `claim_url` string: Usable claim link, when available on the catalog redemption creation response. Omitted on GET/list; use POST /v1/redemptions/{id}/claim-link to retrieve a link.
    - `created_at` string, date-time: When this fulfillment was created
    - `face_value` Money: A fiat amount: an integer count of the currency's minor units, such as cents, and the ISO 4217 currency code.
      - `amount_minor` integer, required: Amount in the currency's minor units, such as cents for USD
      - `currency` string, required: ISO 4217 currency code
    - `failure_reason` string: Bounded terminal failure reason, present only when FAILED
    - `provider` string: The gift-card provider that fulfills the redemption.
    - `provider_order_id` string: Provider's order identifier, present once an order has been placed
    - `resolved_at` string, date-time: When this fulfillment reached a terminal state
    - `status` 'PENDING' | 'PROCESSING' | 'SUCCEEDED' | 'FAILED' | 'AWAITING_FUNDS': Fulfillment lifecycle status
    - `updated_at` string, date-time: When this fulfillment was last updated
  - `id` string, uuid: Unique identifier for this redemption
  - `journal_entry_id` string, uuid: Immutable ledger anchor: the hold entry for pending redemptions, otherwise the instant redemption entry
  - `participant_id` string, uuid: The participant who redeemed
  - `program_id` string, uuid: The program this redemption belongs to
  - `quantity` integer: Number of units redeemed (catalog redemptions only)
  - `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).
  - `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.
  - `reservation_id` string, uuid: Reservation backing a pending redemption
  - `resolved_at` string, date-time: When the pending redemption reached a terminal state
  - `reversed_amount` string: Cumulative amount reversed so far (decimal string)
  - `reversed_quantity` integer: Cumulative units reversed so far (UNIT_BASED catalog redemptions only)
  - `reward_id` string, uuid: The reward catalog item that was redeemed (catalog redemptions only)
  - `status` 'PENDING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'PARTIALLY_REVERSED' | 'FULLY_REVERSED': Current lifecycle and reversal state
  - `unit_cost` string: Cost per unit at the time of redemption (catalog redemptions only, decimal string)
  - `updated_at` string, date-time: When this redemption was last updated (e.g., after a reversal)

## Other responses

- `400`: Validation failed (code: validation_error | invalid_json)
- `401`: The API key is missing or not valid. See [Authentication](https://docs.scrip.dev/authentication).
- `403`: The caller is not allowed to do this.
- `404`: Participant, program, or reward not found (code: participant_not_found | program_not_found | reward_not_found)
- `409`: Reward price changed, reward inactive or outside its availability window, inventory limit exceeded, participant inactive, or another request changed the same balance at the same time (code: reward_price_changed | reward_not_active | reward_not_yet_available | reward_no_longer_available | max_total_exceeded | max_per_participant_exceeded | participant_inactive | idempotency_conflict | retryable_conflict | program_inactive)
- `422`: Insufficient balance, invalid fulfillment window, unsupported reservation mode, archived asset, unavailable fulfillment account, or fulfillment risk cap exceeded (code: insufficient_funds | fulfillment_window_too_short | fulfillment_window_too_long | asset_not_reservable | asset_archived | provider_connection_unavailable | fulfillment_face_value_cap_exceeded | fulfillment_participant_count_cap_exceeded | fulfillment_participant_amount_cap_exceeded | fulfillment_cap_window_invalid)
- `429`: Too many requests. Wait the number of seconds in the `Retry-After` header, then retry. See [Limits and durations](https://docs.scrip.dev/limits#rate-limits).
- `500`: Something failed on Scrip's side. Retry the request, and quote `request_id` if it keeps failing. [Errors](https://docs.scrip.dev/errors) lists every code, and the [API introduction](https://docs.scrip.dev/api-reference/introduction) describes the error format.

---

[API](https://skmtc.dev/scrip/apis/scrip-api.md) · [All operations](https://skmtc.dev/scrip/apis/scrip-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrip/apis/scrip-api/revisions/c52d35da8d97?raw)