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

# Create a reward

> Create a new reward in the program's catalog.

Creates a new reward in a program's catalog. A reward requires a `name`, `redemption_type`, `asset_id`, `unit_cost`, and `status`. You can also include `description`, `category`, and a freeform `metadata` object.

The `asset_id` must reference an asset that is linked to the program. `unit_cost` must be a positive decimal string. Both `redemption_type` and `asset_id` are immutable after creation.

`redemption_type` controls how participants redeem: `UNIT_BASED` rewards are redeemed in discrete quantities with optional inventory caps (`max_total`, `max_per_participant`), while `AMOUNT_BASED` rewards allow variable amounts with no inventory limits.

Set `available_from` and `available_until` to define a redemption window (`available_from` must be before `available_until`). Most rewards should start in `DRAFT` status until configuration is finalized, then transition to `ACTIVE` when ready.

Reward names must be unique within a program. A `409` is returned with code `name_exists` if the name is already taken. Rewards cannot be created in archived programs.

<Note>
  For usage patterns and examples, see the [Rewards Catalog guide](/guides/rewards-catalog).
</Note>


## OpenAPI

````yaml POST /v1/programs/{programId}/rewards
openapi: 3.0.3
info:
  contact:
    email: support@scrip.dev
    name: Scrip Support
    url: https://scrip.dev/support
  description: >-
    Universal Incentive Infrastructure API for managing loyalty programs,
    rewards, and participant balances.


    Scrip provides a complete backend for building incentive and loyalty
    programs. Core concepts:

    - **Programs**: Containers for incentive logic (e.g., "Q1 Sales Bonus",
    "Customer Loyalty")

    - **Assets**: The currency or points being tracked (e.g., "Bonus Points",
    "Cash Rewards")

    - **Participants**: Users who earn and spend assets (identified by
    external_id)

    - **Groups**: Collections of participants for team-based incentives

    - **Rules**: Automated reward logic triggered by events

    - **Events**: Actions that trigger rule evaluation (e.g., "purchase",
    "referral")


    Response formats:

    - **Collection endpoints** return: {"data": [...], "pagination":
    {"has_more": true, "next_cursor": "..."}}

    - **Single-resource endpoints** return the resource directly

    - **Errors** return: {"code": "...", "message": "...", "details": {...}} —
    `details` is an optional object, present on input errors only
  license:
    name: Proprietary
    url: https://scrip.dev/license
  termsOfService: https://scrip.dev/terms
  title: Scrip API
  version: '1.0'
servers:
  - url: https://api.scrip.dev
security: []
tags:
  - description: >-
      Manage incentive programs. Programs are the top-level container for all
      incentive logic.
    name: Programs
  - description: >-
      Manage asset types (currencies, points). Assets define what participants
      can earn and spend.
    name: Assets
  - description: >-
      Manage participants and their balances. Participants are identified by
      external_id from your system.
    name: Participants
  - description: Manage participant groups for team-based incentives.
    name: Groups
  - description: >-
      Manage automated reward rules. Rules define conditions and actions
      triggered by events.
    name: Rules
  - description: Ingest events that trigger rule evaluation and reward distribution.
    name: Events
  - description: Transfer assets between participants.
    name: Transfers
  - description: Access ledger summaries and program activity reports.
    name: Reporting
  - description: >-
      Redeem participant balances for rewards. Supports raw amount redemptions
      and catalog item redemptions.
    name: Redemptions
  - description: >-
      Manage the reward catalog. Create and manage redeemable items with
      inventory tracking.
    name: Rewards
  - description: >-
      Schedule and manage automated event dispatching. Automations generate
      events on cron schedules, at specific times, or by evaluating participant
      state.
    name: Automations
  - description: >-
      Manage tier types and levels within programs. Tiers define status
      hierarchies that participants progress through based on qualification
      rules.
    name: Tiers
  - description: Inspect double-entry ledger records for auditing and reconciliation.
    name: Journal Entries
  - description: >-
      Manage webhook endpoints and delivery logs. Webhooks notify your
      application of real-time events via HTTP POST with HMAC-SHA256 signatures.
    name: Webhooks
paths:
  /v1/programs/{programId}/rewards:
    post:
      tags:
        - Rewards
      summary: Create a reward
      description: Create a new reward in the program's catalog.
      operationId: createReward
      parameters:
        - description: Program ID
          in: path
          name: programId
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.CreateRewardRequest'
        description: Reward details
        required: true
        x-originalParamName: request
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.RewardResponse'
          description: Reward created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: 'Validation failed (code: validation_error | bad_request)'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnauthorizedResponse'
          description: 'Missing or invalid credentials (code: unauthorized)'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrNotFoundResponse'
          description: 'Program or asset not found (code: not_found)'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrConflictResponse'
          description: >-
            Reward name already exists in program or program is archived (code:
            name_exists | program_archived)
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnsupportedMediaTypeResponse'
          description: 'Content-Type must be application/json (code: unsupported_media_type)'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrInternalResponse'
          description: 'Internal server error (code: internal_error)'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    handlers.CreateRewardRequest:
      additionalProperties: false
      properties:
        asset_id:
          description: >-
            Asset used to price this reward (must be linked to the program).
            Immutable after creation.
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        available_from:
          description: >-
            Start of the availability window (RFC 3339, null if always
            available)
          example: '2024-01-01T00:00:00Z'
          format: date-time
          type: string
        available_until:
          description: End of the availability window (RFC 3339, null if no end date)
          example: '2024-12-31T23:59:59Z'
          format: date-time
          type: string
        category:
          description: Grouping label for organizing rewards in the catalog
          example: Gift Cards
          maxLength: 100
          type: string
        description:
          description: Details about the reward
          example: Redeemable for a $10 gift card
          maxLength: 1000
          type: string
        max_per_participant:
          description: Per-participant redemption limit (UNIT_BASED only, null = unlimited)
          example: 2
          type: integer
        max_total:
          description: Global inventory limit (UNIT_BASED only, null = unlimited)
          example: 100
          type: integer
        metadata:
          description: Custom key-value data attached to this reward
          type: object
        name:
          description: Display name for the reward
          example: $10 Gift Card
          maxLength: 255
          minLength: 1
          type: string
        redemption_type:
          description: >-
            How the reward is redeemed: UNIT_BASED (discrete quantities) or
            AMOUNT_BASED (variable amounts). Immutable after creation.
          enum:
            - UNIT_BASED
            - AMOUNT_BASED
          example: UNIT_BASED
          type: string
        status:
          description: 'Lifecycle status: DRAFT, ACTIVE, OUT_OF_STOCK, or ARCHIVED'
          enum:
            - DRAFT
            - ACTIVE
            - OUT_OF_STOCK
            - ARCHIVED
          example: DRAFT
          type: string
        unit_cost:
          description: >-
            Cost per unit in the reward's asset (decimal string for precision,
            must be positive)
          example: '1000.00'
          minLength: 1
          type: string
      required:
        - asset_id
        - name
        - redemption_type
        - status
        - unit_cost
      type: object
    handlers.RewardResponse:
      description: A reward with its pricing, inventory, availability, and metadata
      properties:
        asset_id:
          description: Asset used to price this reward
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        available_from:
          description: >-
            Start of the availability window (RFC 3339, null if always
            available)
          example: '2024-01-01T00:00:00Z'
          format: date-time
          type: string
        available_until:
          description: End of the availability window (RFC 3339, null if no end date)
          example: '2024-12-31T23:59:59Z'
          format: date-time
          type: string
        category:
          description: Grouping label for organizing rewards in the catalog
          example: Gift Cards
          type: string
        created_at:
          description: When this reward was created (RFC 3339)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        description:
          description: Details about the reward
          example: Redeemable for a $10 gift card
          type: string
        id:
          description: Unique identifier for this reward
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        max_per_participant:
          description: Per-participant redemption limit (UNIT_BASED only, null = unlimited)
          example: 2
          type: integer
        max_total:
          description: Global inventory limit (UNIT_BASED only, null = unlimited)
          example: 100
          type: integer
        metadata:
          description: Custom key-value data attached to this reward
          type: object
        name:
          description: Display name for this reward
          example: $10 Gift Card
          type: string
        program_id:
          description: Program this reward belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        redeemed_count:
          description: Total number of times this reward has been redeemed
          example: 42
          type: integer
        redemption_type:
          description: >-
            How the reward is redeemed: UNIT_BASED (discrete quantities) or
            AMOUNT_BASED (variable amounts)
          example: UNIT_BASED
          type: string
        status:
          description: 'Lifecycle status: DRAFT, ACTIVE, OUT_OF_STOCK, or ARCHIVED'
          example: ACTIVE
          type: string
        unit_cost:
          description: Cost per unit in the reward's asset (decimal string for precision)
          example: '1000.00'
          type: string
        updated_at:
          description: When this reward was last modified (RFC 3339)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
      type: object
    handlers.ErrBadRequestResponse:
      additionalProperties: false
      properties:
        code:
          description: Code is the machine-readable error code
          example: bad_request
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: >-
            Details provides optional structured error context (field errors,
            etc.)
        message:
          description: Message is the human-readable error description
          example: Invalid request parameters
          type: string
      type: object
    handlers.ErrUnauthorizedResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: unauthorized
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Missing or invalid credentials
          type: string
      type: object
    handlers.ErrNotFoundResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: not_found
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Resource not found
          type: string
      type: object
    handlers.ErrConflictResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: conflict
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Resource already exists or state conflict
          type: string
      type: object
    handlers.ErrUnsupportedMediaTypeResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: unsupported_media_type
          type: string
        details:
          allOf:
            - $ref: '#/components/schemas/handlers.ErrorDetails'
          description: Details provides optional structured error context
        message:
          description: Message is the human-readable error description
          example: Content-Type must be application/json
          type: string
      type: object
    handlers.ErrInternalResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: internal_error
          type: string
        message:
          description: Message is the human-readable error description
          example: An internal error occurred
          type: string
      type: object
    handlers.ErrorDetails:
      description: >-
        Optional structured details about the error. Always a JSON object: a
        `fields` array for validation errors, or flat
        field/reason/expected/received properties for other input errors.
      properties:
        expected:
          description: Expected value or format (non-validation input errors)
          example: uuid
          type: string
        field:
          description: Field name that caused the error (non-validation input errors)
          example: asset_id
          type: string
        fields:
          description: >-
            Fields lists each offending input field on validation_error
            responses.
          items:
            $ref: '#/components/schemas/handlers.ErrorFieldDetail'
          type: array
        reason:
          description: Machine-readable reason code (non-validation input errors)
          example: invalid
          type: string
        received:
          description: Value that was received (non-validation input errors)
          example: not-a-uuid
          type: string
      type: object
    handlers.ErrorFieldDetail:
      description: >-
        A single field-level error: which input field failed, why, and (where
        known) the expected and received values.
      properties:
        expected:
          description: >-
            Expected value or format. Usually a string; for "one of" constraints
            it

            is an array of the allowed values.
        field:
          description: Field name that caused the error
          example: amount
          type: string
        message:
          description: Human-readable explanation (validation errors only)
          example: This field is required
          type: string
        reason:
          description: Machine-readable reason code
          example: required
          type: string
        received:
          description: Value that was received
          example: '-10.00'
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: API key passed in the X-API-Key header.
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: Bearer token passed in the Authorization header (e.g. "Bearer sk_...").
      in: header
      name: Authorization
      type: apiKey

````