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

# Get event impact

> Returns the full causal chain for a processed event: rule evaluations, journal entries with postings, state changes, and per-entity balance impact.

Returns the full causal chain for a processed event. The response includes rule evaluations, journal entries with their double-entry postings, state changes (tags, counters, attributes, tiers), and an aggregated per-entity balance impact summary.

Use this to understand exactly what an event did: which rules matched, what ledger movements occurred, what state changed, and the net effect on each entity's balance. State changes include the `rule_id` that caused them, linking every tag, counter, attribute, and tier change back to the specific rule.

The `balance_impact` array aggregates all postings into net changes per entity, asset, and bucket. Zero-sum entries (where credits and debits cancel out) are omitted. System accounts (`SYSTEM_ISSUANCE`, `SYSTEM_BREAKAGE`, `SYSTEM_REDEMPTION`) appear as counterparties to participant and group movements.

<Note>
  Events still in `PENDING` or `PROCESSING` status return the event metadata with empty arrays for all impact fields. This endpoint is most useful once the event reaches `COMPLETED` or `FAILED`.

  For usage patterns and examples, see the [Event Processing guide](/guides/event-processing).
</Note>


## OpenAPI

````yaml GET /v1/events/{id}/impact
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/events/{id}/impact:
    get:
      tags:
        - Events
      summary: Get event impact
      description: >-
        Returns the full causal chain for a processed event: rule evaluations,
        journal entries with postings, state changes, and per-entity balance
        impact.
      operationId: getEventImpact
      parameters:
        - description: Event ID
          in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.EventImpactResponse'
          description: Event impact details
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: 'Invalid ID format (code: bad_request)'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrUnauthorizedResponse'
          description: 'Missing or invalid credentials (code: unauthorized)'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrForbiddenResponse'
          description: 'Insufficient permissions (code: forbidden)'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrNotFoundResponse'
          description: 'Resource not found (code: not_found)'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrInternalResponse'
          description: 'Internal server error (code: internal_error)'
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    handlers.EventImpactResponse:
      properties:
        balance_impact:
          description: Net balance impact per entity/asset/bucket
          items:
            $ref: '#/components/schemas/handlers.BalanceImpactResponse'
          type: array
        created_at:
          description: When this event was created
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        error_code:
          description: >-
            Machine-readable failure code for a terminal FAILED event, when one
            is available

            (e.g. program_not_found, participant_suspended,
            participant_inactive). NULL when

            the event did not fail or the failure carried no stable code.
          example: program_not_found
          type: string
        error_message:
          description: Error details if the event failed during processing
          example: rule condition evaluation failed
          type: string
        event_data:
          description: Original event data payload
          type: object
        event_timestamp:
          description: When the event occurred (from the ingestion request)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        event_type:
          description: 'Event type: EXTERNAL (API-ingested) or SYSTEM (internally generated)'
          example: EXTERNAL
          type: string
        external_id:
          description: >-
            Your system's identifier for the participant (the value provided at
            ingestion)
          example: user_abc123
          type: string
        id:
          description: Unique identifier for this event
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        idempotency_key:
          description: Client-provided unique key for deduplication
          example: order-12345-completed
          type: string
        journal_entries:
          description: >-
            Journal entries created by this event with their double-entry
            postings
          items:
            $ref: '#/components/schemas/handlers.JournalEntryResponse'
          type: array
        participant_id:
          description: >-
            Participant UUID, resolved from external_id if one was provided at
            ingestion
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        processed_at:
          description: >-
            When the event finished processing (null while pending or
            processing)
          example: '2024-01-15T10:30:02Z'
          format: date-time
          type: string
        program_id:
          description: Program this event belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        received_at:
          description: When Scrip received the event
          example: '2024-01-15T10:30:01Z'
          format: date-time
          type: string
        recipient_id:
          description: Reward recipient UUID, if different from the triggering participant
          example: 550e8400-e29b-41d4-a716-446655440003
          format: uuid
          type: string
        rule_evaluations:
          description: Rules that were evaluated and their outcomes
          items:
            $ref: '#/components/schemas/handlers.RuleEvaluationResponse'
          type: array
        state_changes:
          description: >-
            State changes (tags, counters, attributes, tiers) caused by this
            event
          items:
            $ref: '#/components/schemas/handlers.StateChangeResponse'
          type: array
        status:
          description: >-
            Processing status: RECEIVED, PENDING, PROCESSING, COMPLETED, or
            FAILED
          example: COMPLETED
          type: string
        updated_at:
          description: When this event was last updated
          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.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.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.BalanceImpactResponse:
      properties:
        amount:
          description: Net amount change (positive = credit, negative = debit)
          example: '200'
          type: string
        asset_symbol:
          description: Asset being affected
          example: PTS
          type: string
        bucket:
          description: 'Balance bucket: AVAILABLE, HELD, or DEFERRED'
          example: AVAILABLE
          type: string
        entity_id:
          description: Public UUID of the entity (null for SYSTEM_* types)
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        entity_type:
          description: >-
            Entity type: PARTICIPANT, GROUP, PROGRAM, SYSTEM_ISSUANCE,
            SYSTEM_BREAKAGE, SYSTEM_REDEMPTION
          example: PARTICIPANT
          type: string
      type: object
    handlers.JournalEntryResponse:
      description: A journal entry with its metadata and double-entry postings
      properties:
        action_type:
          description: Ledger action type (e.g. CREDIT, DEBIT, HOLD, RELEASE, FORFEIT)
          example: HOLD
          type: string
        created_at:
          description: When this entry was created (RFC 3339)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        description:
          description: Human-readable explanation of the entry's purpose
          example: 'Purchase reward: 10 POINTS'
          type: string
        entry_hash:
          description: SHA-256 hash sealing this entry into the organization's hash chain
          example: b3a1d9f8c2e4a7b6d1e3f5a8c9b2d4e6f7a1b3c5d7e9f2a4b6c8d0e1f3a5b7c9
          type: string
        event_id:
          description: >-
            Event that triggered this entry (null if created via direct API
            call)
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        id:
          description: Unique identifier for this journal entry
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        postings:
          description: >-
            Double-entry postings (always sum to zero). Omitted in list
            responses.
          items:
            $ref: '#/components/schemas/handlers.PostingResponse'
          type: array
        program_id:
          description: Program this entry belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        program_name:
          description: Display name of the program
          example: Q1 Sales Bonus
          type: string
        reference_id:
          description: Correlation ID linking holds to releases
          example: auth_12345
          type: string
        rule_id:
          description: >-
            Rule that triggered this entry (null for direct API calls or
            worker-generated entries)
          example: 950e8400-e29b-41d4-a716-446655440004
          format: uuid
          type: string
      type: object
    handlers.RuleEvaluationResponse:
      properties:
        created_at:
          description: When the evaluation occurred
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        error_message:
          description: Error details if the rule failed during execution
          example: condition evaluation failed
          type: string
        id:
          description: Unique identifier for this evaluation record
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        reason:
          description: Why the rule was skipped (only present for SKIPPED status)
          example: OUTSIDE_TIME_WINDOW
          type: string
        rule_history_id:
          description: >-
            Snapshot of the rule version that was active when this evaluation
            occurred
          example: 550e8400-e29b-41d4-a716-446655440003
          format: uuid
          type: string
        rule_id:
          description: Rule that was evaluated
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        rule_name:
          description: Display name of the rule
          example: Welcome Bonus
          type: string
        status:
          description: 'Evaluation result: SUCCESS, FAILED, or SKIPPED'
          example: SUCCESS
          type: string
        stopped_by_rule_id:
          description: The rule whose stop_after_match caused this rule to be skipped
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
      type: object
    handlers.StateChangeResponse:
      properties:
        changed_at:
          description: When the change occurred (RFC 3339)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        entity_id:
          description: Public UUID of the affected entity
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        entity_type:
          description: 'Entity type affected: PARTICIPANT, GROUP, or PROGRAM'
          example: PARTICIPANT
          type: string
        key:
          description: The key that changed
          example: lifetime_spend
          type: string
        new_value:
          description: New value (null for deletes)
          example: '575'
          type: string
        old_value:
          description: Previous value (null for new keys)
          example: '500'
          type: string
        operation:
          description: 'What happened: set, delete, or auto_reset'
          example: set
          type: string
        program_id:
          description: Program scope for tier changes
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        rule_id:
          description: Rule that caused this change
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        state_type:
          description: 'Type of state: tag, counter, attribute, or tier'
          example: counter
          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.PostingResponse:
      description: >-
        A single line in a journal entry representing one side of a double-entry
        transaction
      properties:
        amount:
          description: Posting amount (positive = credit, negative = debit)
          example: '100.00'
          type: string
        asset_symbol:
          description: Asset being transacted
          example: POINTS
          type: string
        bucket:
          description: 'Balance bucket affected: AVAILABLE, HELD, or DEFERRED'
          example: AVAILABLE
          type: string
        created_at:
          description: When this posting was created (RFC 3339)
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        entity_type:
          description: >-
            Account owner type: PARTICIPANT, PROGRAM, GROUP, PROGRAM_TEST,
            SYSTEM_ISSUANCE, SYSTEM_BREAKAGE, or SYSTEM_REDEMPTION
          example: PARTICIPANT
          type: string
        group_id:
          description: Group that owns this account (set when entity_type is GROUP)
          example: 550e8400-e29b-41d4-a716-446655440011
          format: uuid
          type: string
        id:
          description: Unique identifier for this posting
          example: 550e8400-e29b-41d4-a716-446655440003
          format: uuid
          type: string
        participant_id:
          description: >-
            Participant who owns this account (set when entity_type is
            PARTICIPANT)
          example: 550e8400-e29b-41d4-a716-446655440010
          format: uuid
          type: string
        program_id:
          description: Program that owns this account (set when entity_type is PROGRAM)
          example: 550e8400-e29b-41d4-a716-446655440012
          format: 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

````