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

# Rewards Catalog

> Define redeemable items with pricing, inventory limits, and availability windows

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.

```bash theme={null}
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"
}
```

| Field                 | Required | Description                                                                                                                                                            |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                | Yes      | Display name (1-255 characters, unique per program)                                                                                                                    |
| `description`         | No       | Additional context (max 1000 characters)                                                                                                                               |
| `category`            | No       | Grouping label (max 100 characters)                                                                                                                                    |
| `redemption_type`     | Yes      | `UNIT_BASED` or `AMOUNT_BASED`. Cannot be changed after creation.                                                                                                      |
| `asset_id`            | Yes      | Which asset this reward is priced in. Must be linked to the program. Cannot be changed after creation.                                                                 |
| `unit_cost`           | Yes      | Cost per unit (must be positive). For `AMOUNT_BASED` rewards, `unit_cost` is informational: the participant chooses the redemption amount, and no minimum is enforced. |
| `max_total`           | No       | Global inventory cap (`UNIT_BASED` only). Null means unlimited.                                                                                                        |
| `max_per_participant` | No       | Per-participant cap (`UNIT_BASED` only). Null means unlimited.                                                                                                         |
| `status`              | Yes      | Initial status. Most rewards start as `DRAFT` until configuration is finalized.                                                                                        |
| `available_from`      | No       | When the reward becomes redeemable (UTC timestamp)                                                                                                                     |
| `available_until`     | No       | When the reward stops being redeemable (UTC timestamp)                                                                                                                 |
| `metadata`            | No       | Arbitrary 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. See [Inventory Management](#inventory-management) for the `OUT_OF_STOCK` transition.

### 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

| Status         | Description                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------- |
| `DRAFT`        | Not yet available for redemption. Use while configuring.                                      |
| `ACTIVE`       | Available for redemption (subject to availability window).                                    |
| `OUT_OF_STOCK` | Set automatically when inventory runs out. See [Inventory Management](#inventory-management). |
| `ARCHIVED`     | Removed 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`.

```bash theme={null}
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`.

```bash theme={null}
# 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 updated at any time; the only validation is that it stays positive. Lowering it below the current `redeemed_count` does not retract past redemptions or change the reward's status, but new redemptions fail with `409 max_total_exceeded` while the count is at or above the cap
* Use `DRAFT` status while configuring, then switch to `ACTIVE` when ready
* When a redemption brings `redeemed_count` up to `max_total`, the reward transitions to `OUT_OF_STOCK` automatically
* `UNIT_BASED` reversals decrement `redeemed_count`. If this brings an `OUT_OF_STOCK` reward's inventory back below `max_total`, the reward returns to `ACTIVE`

See [Redemptions](/guides/redemptions) for how participants redeem catalog items and how reversals restore inventory.