Skip to main content
POST
/
v1
/
participants
/
{id}
/
redemptions
Redeem points/assets
curl --request POST \
  --url https://api.scrip.dev/v1/participants/{id}/redemptions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "amount": "1000.00",
  "asset_id": "550e8400-e29b-41d4-a716-446655440001",
  "description": "Cash out reward points",
  "program_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "redeem-12345"
}
'
{
  "amount": "1000.00",
  "asset_id": "550e8400-e29b-41d4-a716-446655440003",
  "created_at": "2024-01-15T10:30:00Z",
  "description": "Redeemed: Gift Card",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "journal_entry_id": "550e8400-e29b-41d4-a716-446655440005",
  "participant_id": "550e8400-e29b-41d4-a716-446655440002",
  "program_id": "550e8400-e29b-41d4-a716-446655440001",
  "quantity": 2,
  "reversed_amount": "0.00",
  "reversed_quantity": 0,
  "reward_id": "550e8400-e29b-41d4-a716-446655440004",
  "status": "COMPLETED",
  "unit_cost": "500.00",
  "updated_at": "2024-01-15T10:30:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt

Use this file to discover all available pages before exploring further.

Debits an arbitrary amount from a participant’s AVAILABLE balance for a given asset. This is a raw redemption, meaning it is not tied to any catalog item. You must provide program_id, asset_id, amount, and a description explaining the redemption. The participant must be active, the program must be ACTIVE (not archived or suspended), and the asset must be linked to the program. The call fails with 422 if the participant’s AVAILABLE balance is insufficient to cover the requested amount. On success, the debited amount is credited to the program’s configured redemption target account (default: SYSTEM_REDEMPTION). Use this endpoint for custom redemption flows that fall outside the reward catalog, such as pay-with-points at checkout or ad-hoc deductions. Pass an idempotency_key to safely retry requests. Duplicate requests return 200 with the existing redemption instead of 201.
For usage patterns and examples, see the Redemptions guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

​
id
string<uuid>
required

Participant ID

Body

application/json

Redemption details

​
amount
string
required

Amount to debit (decimal string)

Minimum string length: 1
Example:

"1000.00"

​
asset_id
string<uuid>
required

The asset to debit from the participant's balance

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
description
string
required

Context for this redemption, used in journal entries (1-500 chars)

Required string length: 1 - 500
Example:

"Cash out reward points"

​
program_id
string<uuid>
required

The program this redemption belongs to

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
idempotency_key
string

Prevents duplicate redemptions when retrying requests

Example:

"redeem-12345"

Response

Duplicate request (idempotency key matched, returns existing record)

​
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"

​
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"

​
id
string<uuid>

Unique identifier for this redemption

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
journal_entry_id
string<uuid>

The ledger journal entry created by this redemption

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

​
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
string

Current state: COMPLETED, PARTIALLY_REVERSED, or 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"