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

# Apply a rule-configuration change set

> Apply the exact server-stored preview plan in one transaction after checking token, request hash, actor, organization, program, expiry, dependency drift, and base configuration version. The version increments exactly once.

Applies the exact server-stored plan identified by `preview_token` and `request_hash`. The body cannot replace or modify the proposal.

Scrip verifies the actor, organization, program, expiry, request hash, base version, and referenced dependencies before committing the plan in one transaction. Success increments `rule_configuration_version` exactly once.

Create a new preview when a token is expired, already applied, based on a stale version, or invalidated by dependency drift.


## OpenAPI

````yaml POST /v1/programs/{programId}/rule-configuration/apply
openapi: 3.0.3
info:
  contact:
    email: support@scrip.dev
    name: Scrip Support
  description: >-
    Scrip is the operating system for rewards programs. Use this REST API to
    define earn and redemption rules, issue and redeem assets, and track every
    movement in a double-entry ledger. Full guides and reference:
    https://docs.scrip.dev


    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
  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}/rule-configuration/apply:
    post:
      tags:
        - Rules
      summary: Apply an atomic rule-configuration change set
      description: >-
        Apply the exact server-stored preview plan in one transaction after
        checking token, request hash, actor, organization, program, expiry,
        dependency drift, and base configuration version. The version increments
        exactly once.
      operationId: applyRuleConfiguration
      parameters:
        - description: Program ID
          in: path
          name: programId
          required: true
          schema:
            format: uuid
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handlers.ApplyRuleConfigurationRequest'
        description: Preview capability and integrity hash
        required: true
        x-originalParamName: request
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ApplyRuleConfigurationResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrNotFoundResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrConflictResponse'
          description: Conflict
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnsupportedMediaTypeResponse'
          description: Unsupported Media Type
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnprocessableResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrInternalResponse'
          description: Internal Server Error
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    handlers.ApplyRuleConfigurationRequest:
      additionalProperties: false
      properties:
        preview_token:
          description: Short-lived opaque capability returned by preview.
          minLength: 1
          type: string
        request_hash:
          description: SHA-256 request hash returned by the same preview.
          maxLength: 64
          minLength: 64
          pattern: ^[A-Fa-f0-9]{64}$
          type: string
      required:
        - preview_token
        - request_hash
      type: object
    handlers.ApplyRuleConfigurationResponse:
      properties:
        change_id:
          description: Applied preview/change identifier.
          format: uuid
          type: string
        rule_configuration:
          allOf:
            - $ref: '#/components/schemas/handlers.RuleConfigurationResponse'
          description: Complete applied configuration at its new revision.
      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.ErrForbiddenResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: forbidden
          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: Insufficient permissions for this action
          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.ErrUnprocessableResponse:
      properties:
        code:
          description: Code is the machine-readable error code
          example: unprocessable
          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: Business rule violation
          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.RuleConfigurationResponse:
      properties:
        program_id:
          description: Program whose configuration was read.
          format: uuid
          type: string
        rule_configuration_version:
          description: >-
            Program rule-configuration version. Pass it to version-guarded
            writes to reject conflicting edits.
          example: 4
          type: integer
        rule_sets:
          description: >-
            Rule sets in execution order, each with its ACTIVE and SUSPENDED
            rules in local order.
          items:
            $ref: '#/components/schemas/handlers.RuleSetConfigurationResponse'
          type: array
      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.RuleSetConfigurationResponse:
      properties:
        rule_set:
          allOf:
            - $ref: '#/components/schemas/handlers.RuleSetResponse'
          description: Rule-set metadata and position.
        rules:
          description: >-
            ACTIVE and SUSPENDED rules in execution order. Archived rules are
            excluded.
          items:
            $ref: '#/components/schemas/handlers.RuleResponse'
          type: array
      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
    handlers.RuleSetResponse:
      properties:
        created_at:
          description: When this rule set was created.
          example: '2026-07-16T10:30:00Z'
          format: date-time
          type: string
        id:
          description: Stable rule-set identifier.
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        key:
          description: Immutable program-scoped key.
          example: holiday-promo
          type: string
        name:
          description: Operator-facing display name.
          example: Holiday Promotion
          type: string
        order:
          description: >-
            Execution position among participating sets; lower executes first.
            This does not control participation, stacking, replacement, or
            suppression.
          example: 1
          type: integer
        program_id:
          description: Program that owns this rule set.
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        rule_configuration_version:
          description: >-
            Resulting program rule-configuration revision. Present on mutation
            responses.
          example: 4
          type: integer
        updated_at:
          description: When this rule set was last modified.
          example: '2026-07-16T10:30:00Z'
          format: date-time
          type: string
      type: object
    handlers.RuleResponse:
      properties:
        actions:
          description: Actions to execute when the condition matches
          example:
            - amount: ${{ event.amount * 10 }}
              asset_id: 550e8400-e29b-41d4-a716-446655440002
              type: CREDIT
          items:
            type: object
          type: array
        active_from:
          description: >-
            Start of the rule's active window (RFC 3339, null if always active).
            Checked against the event's event_timestamp, inclusive.
          example: '2024-01-01T00:00:00Z'
          format: date-time
          type: string
        active_to:
          description: >-
            End of the rule's active window (RFC 3339, null if no end date).
            Checked against the event's event_timestamp, exclusive.
          example: '2024-12-31T23:59:59Z'
          format: date-time
          type: string
        budgets:
          description: Budget constraints applied to this rule
          items:
            $ref: '#/components/schemas/handlers.BudgetResponse'
          type: array
        condition:
          description: CEL expression that determines when the rule fires
          example: event.type == 'purchase' && event.amount > 0
          type: string
        created_at:
          description: When this rule was created (RFC 3339)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        deleted_at:
          description: When this rule was archived (null if not archived)
          example: '2024-06-01T00:00:00Z'
          format: date-time
          type: string
        description:
          description: Human-readable summary of what this rule does
          example: Awards 10 points per dollar spent
          type: string
        id:
          description: Unique identifier for this rule
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        name:
          description: Display name
          example: Purchase Reward
          type: string
        order:
          description: >-
            Evaluation position within the containing rule set (lower = first;
            ACTIVE and SUSPENDED rules occupy unique positions)
          example: 1
          type: integer
        program_id:
          description: Program this rule belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        rule_configuration_version:
          description: >-
            Resulting program rule-configuration revision. Present on mutation
            responses.
          example: 4
          type: integer
        rule_set_id:
          description: >-
            Rule set that contains this rule and scopes its order and
            stop_after_match behavior
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        status:
          description: 'Lifecycle status: ACTIVE, SUSPENDED, or ARCHIVED'
          example: ACTIVE
          type: string
        stop_after_match:
          description: >-
            When true, no subsequent rules in this set evaluate after this one
            matches; other sets continue
          example: false
          type: boolean
        updated_at:
          description: When this rule was last modified (RFC 3339)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        warnings:
          description: >-
            Non-blocking advisories about the rule's condition or action
            expressions,

            such as unknown state-key typos or deprecated CEL aliases. Present
            on

            create/update only; never blocks the save.
          items:
            $ref: '#/components/schemas/models.RuleWarning'
          type: array
      type: object
    handlers.BudgetResponse:
      properties:
        asset_id:
          description: Asset this budget constrains
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        consumed:
          description: Amount consumed so far in the current period
          example: '4500.00'
          type: string
        cron_expression:
          description: Cron expression for CRON-based resets (e.g., first of every month)
          example: 0 0 1 * *
          type: string
        interval:
          description: Duration for INTERVAL-based resets
          example: 720h
          type: string
        limit:
          description: Maximum allowed spend for this budget period
          example: '10000.00'
          type: string
        next_reset_at:
          description: When the budget next resets (null for lifetime budgets)
          example: '2026-03-01T00:00:00Z'
          format: date-time
          type: string
        schedule_type:
          description: 'Reset schedule type: CRON or INTERVAL (null for lifetime budgets)'
          example: CRON
          type: string
      type: object
    models.RuleWarning:
      properties:
        code:
          description: >-
            Machine-readable warning category, e.g.
            RuleWarningCodeUnknownStateKey.
          example: unknown_state_key
          type: string
        key:
          description: The referenced key, as written in the condition.
          example: purchaseCnt
          type: string
        kind:
          description: >-
            State kind: StateKindCounter, StateKindTag, StateKindAttribute, or
            StateKindAlias.
          example: counter
          type: string
        message:
          description: >-
            Human-readable explanation (includes the suggestion when one
            exists).
          example: >-
            unknown counter "purchaseCnt" — no rule in this program writes it;
            did you mean "purchase_count"?
          type: string
        scope:
          description: >-
            State scope of the reference: StateScopeParticipant,
            StateScopeProgram, or StateScopeGroup.
          example: participant
          type: string
        suggestion:
          description: Closest known key, when a near-match exists. Empty otherwise.
          example: purchase_count
          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

````