Skip to main content
The rewards catalog defines items that participants can redeem with their balance. 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.

​
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. Scrip commits inventory when it authorizes or instantly captures the redemption. See Inventory management for the inventory measures and OUT_OF_STOCK transitions.

​
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

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.
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.
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. Reward detail and list responses expose these measures: AMOUNT_BASED rewards return null for all three quantities and both caps. The keys are always present. Inventory changes with the fulfillment lifecycle:
  • Authorization increments committed_units and pending_units
  • Capture moves units from pending_units to delivered_units. committed_units stays unchanged
  • Failure, cancellation, and timeout decrement pending_units and committed_units. delivered_units stays unchanged
  • Instant redemption increments committed_units and delivered_units
  • Reversal of a completed redemption decrements committed_units and delivered_units
Scrip applies the same commitment lifecycle to the per-participant count used by max_per_participant.
  • max_total can be updated at any time; the only validation is that it stays positive. Lowering it below the current committed_units does not retract past redemptions or change the reward’s status, but new redemptions fail with 409 max_total_exceeded while committed inventory is at or above the cap
  • Use DRAFT status while configuring, then switch to ACTIVE when ready
  • When authorization or instant redemption brings committed_units up to max_total, the reward transitions to OUT_OF_STOCK automatically
  • OUT_OF_STOCK is a live inventory state. The reward returns to ACTIVE when failure, cancellation, timeout, or reversal brings committed_units below max_total
Track these automatic transitions with reward.status_changed. See Redemptions for how participants redeem catalog items and how reversals restore inventory.