Redemptions

Complete a pending redemption

Capture the reservation backing a pending redemption before its effective deadline. Replaying an already-completed redemption returns the same record.

post/v1/redemptions/{redemption_id}/complete

Request

  • Base URL: https://api.scrip.dev
  • URL: https://api.scrip.dev/v1/redemptions/{redemption_id}/complete
  • Auth: HTTP bearer

Path parameters

redemption_idstring uuid required

The redemption's 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

idempotency_keystring

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

Example request

{
  "idempotency_key": "complete-12345"
}

Response

Redemption completed or same-outcome replay

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.