Skip to main content

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.

The rewards catalog defines items that participants can redeem with their points. Each reward belongs to a program, has a cost denominated in a specific asset, and can optionally enforce inventory limits and availability windows. You might use it for gift cards, merchandise, cashback tiers, or charitable donation options.

​
Creating a Reward

Rewards are scoped to a program and priced in a linked asset. 
POST /v1/programs/{programId}/rewards
{
  "name": "$10 Gift Card",
  "redemption_type": "UNIT_BASED",
  "asset_id": "points-uuid",
  "unit_cost": "1000",
  "max_total": 100,
  "max_per_participant": 2,
  "status": "ACTIVE"
}
FieldRequiredDescription
nameYesDisplay name (1-255 characters, unique per program)
descriptionNoAdditional context (max 1000 characters)
categoryNoGrouping label (max 100 characters)
redemption_typeYesUNIT_BASED or AMOUNT_BASED. Cannot be changed after creation.
asset_idYesWhich asset this reward is priced in. Must be linked to the program. Cannot be changed after creation.
unit_costYesCost per unit (must be positive). For AMOUNT_BASED rewards, this is the minimum redemption amount.
max_totalNoGlobal inventory cap (UNIT_BASED only). Null means unlimited.
max_per_participantNoPer-participant cap (UNIT_BASED only). Null means unlimited.
statusYesInitial status. Most rewards start as DRAFT until configuration is finalized.
available_fromNoWhen the reward becomes redeemable (UTC timestamp)
available_untilNoWhen the reward stops being redeemable (UTC timestamp)
metadataNoArbitrary JSON for your own use

​
Reward Types

​
UNIT_BASED

Discrete quantities with a fixed cost per unit. Use for items like gift cards, merchandise, or experiences. When a participant redeems, the total cost is quantity * unit_cost. Inventory is tracked: each redemption increments redeemed_count globally and per participant. When redeemed_count reaches max_total, the reward status automatically changes to OUT_OF_STOCK.

​
AMOUNT_BASED

Flexible amounts without inventory tracking. Use for cashback, statement credits, or charitable donations. Participants specify an amount when redeeming. max_total and max_per_participant are not supported for this type.

​
Reward Status

StatusDescription
DRAFTNot yet available for redemption. Use while configuring.
ACTIVEAvailable for redemption (subject to availability window).
OUT_OF_STOCKSet automatically when redeemed_count reaches max_total. Reversals can restore inventory and revert the status to ACTIVE.
ARCHIVEDRemoved from default listings. Cannot be redeemed. Historical data remains.
Only ACTIVE rewards can be redeemed.

​
Availability Windows

Restrict when a reward is redeemable by setting available_from and available_until. Both are optional. If both are set, available_from must be before available_until. 
POST /v1/programs/{programId}/rewards
{
  "name": "Holiday Special",
  "redemption_type": "UNIT_BASED",
  "asset_id": "points-uuid",
  "unit_cost": "500",
  "available_from": "2025-12-01T00:00:00Z",
  "available_until": "2025-12-31T23:59:59Z",
  "status": "ACTIVE"
}
A redemption attempt outside the window returns a 409 error.

​
Managing Rewards

You can list, inspect, and update rewards through the API. Archived rewards are hidden from list results by default but can be included with include_archived=true. 
# List catalog items
GET /v1/programs/{programId}/rewards

# Get a specific item (includes archived)
GET /v1/programs/{programId}/rewards/{rewardId}

# Update an item
PATCH /v1/programs/{programId}/rewards/{rewardId}
{"max_total": 200}
redemption_type and asset_id cannot be changed after creation. All other fields can be updated.

​
Inventory Management

Inventory tracking applies to UNIT_BASED rewards only. Scrip maintains a global redeemed_count and a per-participant count, both updated atomically during redemptions and reversals.
  • max_total can be increased but not decreased below the current redeemed_count
  • Use DRAFT status while configuring, then switch to ACTIVE when ready
  • When redeemed_count reaches max_total, the reward transitions to OUT_OF_STOCK automatically
  • UNIT_BASED reversals decrement redeemed_count. If this brings inventory back below max_total, the reward returns to ACTIVE
See Redemptions for how participants redeem catalog items and how reversals restore inventory.