Redemptions

Redeem a catalog item

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

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

Path parameters

participant_idstring required

The participant's id, or ext: followed by the participant's external_id.

Headers

Idempotency-Keystring

A key you choose to make this request safe to retry: 1 to 255 printable ASCII characters. Send the same key with the same request to get the first response again, marked Idempotent-Replayed: true. Routes that return a secret once, and claim links, do not replay a response. Event ingest uses the key as the event's identity.

Request body

amountstring

Asset amount for custom AMOUNT_BASED rewards. For managed rewards, supply fulfillment.face_value instead.

captureboolean

Whether to capture immediately. True completes instantly, false authorizes, and omission uses the program fulfillment_mode.

descriptionstring

Optional context for this redemption, used in journal entries (max 500 chars)

expected_amountstring

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_atstring 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.

idempotency_keystring

Your key for this redemption. You can send it in the Idempotency-Key header instead; when both are sent they must match.

program_idstring uuid required

The program this redemption belongs to

quantityinteger

Number of units to redeem. Defaults to 1; managed rewards require exactly 1.

reward_idstring uuid required

The reward catalog item to redeem

ttl_secondsinteger

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.

Example request

{
  "amount": "50.00",
  "description": "Gift card redemption",
  "expected_amount": "50.00",
  "expires_at": "2027-12-31T23:59:59Z",
  "fulfillment": {
    "face_value": {
      "amount_minor": 2500,
      "currency": "USD"
    }
  },
  "idempotency_key": "redeem-item-12345",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "quantity": 2,
  "reward_id": "2b7a9c4e-1f3d-4a8b-9e6c-5a1d3f7b8c08",
  "ttl_seconds": 3600
}

Response

Redemption created

amountstring

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

asset_idstring uuid

The asset that was debited

capture_journal_entry_idstring uuid

Ledger entry that captured a pending redemption

captured_atstring date-time

When the pending redemption was captured

created_atstring date-time

When this redemption was created

descriptionstring

Context for this redemption, used in journal entries

expires_atstring 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_reasonstring

Machine-readable or operator-supplied terminal failure detail

idstring uuid

Unique identifier for this redemption

journal_entry_idstring uuid

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

participant_idstring uuid

The participant who redeemed

program_idstring uuid

The program this redemption belongs to

quantityinteger

Number of units redeemed (catalog redemptions only)

release_journal_entry_idstring 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_amountstring

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_idstring uuid

Reservation backing a pending redemption

resolved_atstring date-time

When the pending redemption reached a terminal state

reversed_amountstring

Cumulative amount reversed so far (decimal string)

reversed_quantityinteger

Cumulative units reversed so far (UNIT_BASED catalog redemptions only)

reward_idstring 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_coststring

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

updated_atstring date-time

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

Example response

{
  "amount": "1000.00",
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "capture_journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "captured_at": "2027-01-15T10:30:00Z",
  "created_at": "2027-01-15T10:30:00Z",
  "description": "Redeemed: Gift Card",
  "expires_at": "2027-12-31T23:59:59Z",
  "failure_reason": "fulfillment_failed",
  "fulfillment": {
    "claim_url": "https://claim.example.com/abc123",
    "created_at": "2027-01-15T10:30:00Z",
    "face_value": {
      "amount_minor": 2500,
      "currency": "USD"
    },
    "failure_reason": "provider_permanent_error",
    "provider": "TREMENDOUS",
    "provider_order_id": "ord_abc123",
    "resolved_at": "2027-01-15T10:30:00Z",
    "status": "PROCESSING",
    "updated_at": "2027-01-15T10:30:00Z"
  },
  "id": "7f422b43-4ba2-41c7-b05d-e4e90b68e978",
  "journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "participant_id": "f7a8b9c0-1d2e-4f3a-b4c5-d6e7f8a9b006",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "quantity": 2,
  "release_journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "released_amount": "1000.00",
  "reservation_id": "5d1f8a26-3c79-4e0b-9a64-b2e7c1d85f10",
  "resolved_at": "2027-01-15T10:30:00Z",
  "reversed_amount": "0.00",
  "reward_id": "2b7a9c4e-1f3d-4a8b-9e6c-5a1d3f7b8c08",
  "status": "COMPLETED",
  "unit_cost": "500.00",
  "updated_at": "2027-01-15T10:30:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.