Rewards

Create a reward

Create a new reward in the program's catalog.

post/v1/programs/{program_id}/rewards

Request

Base URL: https://api.scrip.dev
URL: https://api.scrip.dev/v1/programs/{program_id}/rewards
Auth: HTTP bearer

Path parameters

program_idstring uuid required

The program'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

asset_idstring uuid required

Asset used to price this reward (must be linked to the program). Immutable after creation.

available_fromstring date-time

Start of the availability window (RFC 3339, null if always available)

available_untilstring date-time

End of the availability window (RFC 3339, null if no end date)

categorystring

Grouping label for organizing rewards in the catalog

descriptionstring

Details about the reward

max_per_participantinteger

Per-participant redemption limit (UNIT_BASED only, null = unlimited)

max_totalinteger

Global inventory limit (UNIT_BASED only, null = unlimited)

metadataobject

Custom key-value data attached to this reward

namestring required

The name people see for the reward in the catalog.

redemption_type'UNIT_BASED' | 'AMOUNT_BASED' required

How the reward is redeemed: UNIT_BASED (discrete quantities) or AMOUNT_BASED (variable amounts). Immutable after creation.

status'DRAFT' | 'ACTIVE' | 'OUT_OF_STOCK' | 'ARCHIVED' required

Lifecycle status: DRAFT, ACTIVE, OUT_OF_STOCK, or ARCHIVED

unit_coststring required

Cost per unit in the reward's asset (decimal string for precision, must be positive)

Example request

{
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "available_from": "2027-01-01T00:00:00Z",
  "available_until": "2027-12-31T23:59:59Z",
  "category": "Gift Cards",
  "description": "Redeemable for a $10 gift card",
  "max_per_participant": 2,
  "max_total": 100,
  "name": "$10 Gift Card",
  "redemption_type": "UNIT_BASED",
  "status": "DRAFT",
  "unit_cost": "1000.00"
}

Response

Reward created

asset_idstring uuid

Asset used to price this reward

auto_managedboolean

Whether the catalog sync manages this item's lifecycle automatically

available_fromstring date-time

Start of the availability window (RFC 3339, null if always available)

available_untilstring date-time

End of the availability window (RFC 3339, null if no end date)

categorystring

Grouping label for organizing rewards in the catalog

committed_unitsinteger nullable

UNIT_BASED units currently consuming inventory. Includes delivered and pending units. Null for AMOUNT_BASED rewards.

created_atstring date-time

When this reward was created (RFC 3339)

delivered_unitsinteger nullable

UNIT_BASED units whose redemption has been captured. Null for AMOUNT_BASED rewards.

descriptionstring

Details about the reward

face_currencystring

ISO 4217 currency of the face value (PROVIDER items only)

fulfillment_product_idstring uuid

Product ordered when this reward is redeemed. Present for managed rewards (kind PROVIDER).

idstring uuid

Unique identifier for this reward

kindstring

Whether you created the reward directly (CUSTOM) or Scrip manages it through a reward source (PROVIDER)

max_per_participantinteger nullable

Per-participant redemption limit (UNIT_BASED only, null = unlimited)

max_totalinteger nullable

Global inventory limit (UNIT_BASED only, null = unlimited)

metadataobject

Custom key-value data attached to this reward

namestring

The name people see for the reward in the catalog.

pending_unitsinteger nullable

UNIT_BASED units awaiting fulfillment. Null for AMOUNT_BASED rewards.

program_idstring uuid

Program this reward belongs to

redemption_type'UNIT_BASED' | 'AMOUNT_BASED'

Whether the reward is redeemed in discrete units or in variable amounts.

reward_source_idstring uuid

Reward source that supplies this managed reward

status'DRAFT' | 'ACTIVE' | 'OUT_OF_STOCK' | 'ARCHIVED'

The reward's lifecycle state.

unit_coststring

Fixed price per unit. For variable-value managed rewards, use fulfillment.rate to calculate the charge.

updated_atstring date-time

When this reward was last modified (RFC 3339)

Example response

{
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "available_from": "2027-01-01T00:00:00Z",
  "available_until": "2027-12-31T23:59:59Z",
  "category": "Gift Cards",
  "committed_units": 42,
  "created_at": "2027-01-15T10:30:00Z",
  "delivered_units": 39,
  "description": "Redeemable for a $10 gift card",
  "display": {
    "description_html": "<p>Use this gift card online or in store.</p>",
    "disclosure_html": "<p>Valid in the United States.</p>",
    "image_url": "https://images.example.com/gift-card.png",
    "instructions_html": "<p>Present the gift card at checkout.</p>"
  },
  "face_currency": "USD",
  "face_value": {
    "amount_minor": 2500,
    "currency": "USD"
  },
  "fulfillment": {
    "account_status": "ACTIVE",
    "asset_scale": 2,
    "countries": [
      "US"
    ],
    "currencies": [
      "USD"
    ],
    "delivery_method": "claim_link",
    "denominations": [
      {
        "amount_minor": 2500,
        "currency": "USD"
      }
    ],
    "rate": "1.5",
    "value_max": {
      "amount_minor": 2500,
      "currency": "USD"
    },
    "value_min": {
      "amount_minor": 2500,
      "currency": "USD"
    }
  },
  "fulfillment_product_id": "3f5b7d91-a2c4-4e68-8a0d-f1b3c5e7d927",
  "id": "2b7a9c4e-1f3d-4a8b-9e6c-5a1d3f7b8c08",
  "kind": "CUSTOM",
  "max_per_participant": 2,
  "max_total": 100,
  "name": "$10 Gift Card",
  "pending_units": 3,
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "redemption_type": "UNIT_BASED",
  "reward_source_id": "9a0c2e4b-6d81-4f35-a7c9-1b3d5f7e9a14",
  "status": "ACTIVE",
  "unit_cost": "1000.00",
  "updated_at": "2027-01-15T10:30:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.