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

> ## Agent Instructions
> Before planning an integration, read https://docs.scrip.dev/which-endpoints-you-need.md. It lists the calls an app makes as users earn and redeem, such as sending and reversing events, reading balances, and redeeming rewards. Every other endpoint creates or changes the program itself, and the dashboard at https://app.scrip.dev is the usual place for that work.
> Gift cards are rewards in the program's rewards catalog, next to custom rewards. Redeem one with `POST /v1/participants/{id}/redemptions/items` and a `fulfillment` object. When the order succeeds, show the participant the claim link from `fulfillment.claim_url` in the redemption response or from `POST /v1/redemptions/{id}/claim-link`. An order can finish after the request returns, so handle the `redemption.fulfillment_succeeded` and `redemption.fulfillment_failed` webhooks. See https://docs.scrip.dev/guides/gift-cards.md.
> Give every event, redemption, and transfer an `idempotency_key` built from your own data, such as an order ID, so retries are safe. Keep API keys on your server.
> Request and response schemas are in https://docs.scrip.dev/openapi.json. Add `.md` to any docs URL to get the page as Markdown.

# Get participant rollforward

> Returns one participant's period rollforward per asset: opening balance, closing balance, and the movement decomposed by journal action type (issued, redeemed, expired, transfers, and so on). Lines are netted per journal entry and sum exactly to closing minus opening, with no residual plug. These are the figures a card program prints in the rewards box of a statement. Balances cover all buckets (AVAILABLE, HELD, DEFERRED). The window selects entries by posting time (the journal entry's created_at), inclusive on both bounds, the same as the participant statement. The echoed `from` and `to` preserve the request's fractional seconds, so replaying them returns identical figures.

Returns how one participant's balance changed between `from` and `to`. The response has one row for each asset the participant has used by `to`. Each row gives `opening_balance`, `closing_balance`, and how the balance changed, split into named amounts such as `issued`, `redeemed`, `redemption_reversals`, and `expired`. Use it to print the rewards summary on a cardholder's statement for one billing cycle without classifying statement rows yourself.

`from` and `to` are required. Both bounds are inclusive and select entries by the posting's `created_at`, the same way the [participant statement](/api-reference/participants/get-participant-statement) does. The response repeats `from` and `to` exactly as you sent them, including fractional seconds. Pass `asset_id` to return one asset.

For every row, the amounts add up to `closing_balance - opening_balance`. Every change is counted in one of them, and if the ledger contains activity they cannot cover, the request fails instead of returning a wrong figure. Balances include `AVAILABLE`, `HELD`, and `DEFERRED`, so `bucket_movements_net` is always `0`, while `transfers_net` can be positive or negative. A settlement for less than the pending amount shows the difference in `issuance_returns`; it does not count as `issued` and then returned.

<Note>
  For what each amount counts and how they add up, see [Participant rollforward](/guides/reporting#participant-rollforward) in the Reporting guide.
</Note>


## OpenAPI

````yaml GET /v1/participants/{id}/rollforward
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/participants/{id}/rollforward:
    get:
      tags:
        - Participants
      summary: Get participant rollforward
      description: >-
        Returns one participant's period rollforward per asset: opening balance,
        closing balance, and the movement decomposed by journal action type
        (issued, redeemed, expired, transfers, and so on). Lines are netted per
        journal entry and sum exactly to closing minus opening, with no residual
        plug. These are the figures a card program prints in the rewards box of
        a statement. Balances cover all buckets (AVAILABLE, HELD, DEFERRED). The
        window selects entries by posting time (the journal entry's created_at),
        inclusive on both bounds, the same as the participant statement. The
        echoed `from` and `to` preserve the request's fractional seconds, so
        replaying them returns identical figures.
      operationId: getParticipantRollforward
      parameters:
        - description: Participant ID
          in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - description: Period start (inclusive, RFC 3339)
          in: query
          name: from
          required: true
          schema:
            format: date-time
            type: string
        - description: Period end (inclusive, RFC 3339)
          in: query
          name: to
          required: true
          schema:
            format: date-time
            type: string
        - description: Filter to a single asset
          in: query
          name: asset_id
          schema:
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ParticipantRollforwardResponse'
          description: Participant rollforward
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ErrBadRequestResponse'
          description: 'Invalid query parameters (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: 'Participant or asset 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.ParticipantRollforwardResponse:
      description: >-
        Period rollforward of one participant's balances, one row per asset.
        Every line is attributed to journal action types; lines sum exactly to
        closing − opening per row (no plug line).
      properties:
        data:
          description: >-
            Rollforward rows, one per asset the participant has ledger activity
            in at or before `to`
          items:
            $ref: '#/components/schemas/handlers.ParticipantRollforwardRowResponse'
          type: array
        from:
          description: >-
            Period start (inclusive, RFC 3339), echoed from the request with any
            fractional seconds preserved, so replaying the echoed bounds returns
            the same figures
          example: '2026-01-01T00:00:00Z'
          type: string
        pagination:
          allOf:
            - $ref: '#/components/schemas/handlers.PaginationResponse'
          description: Pagination metadata for list responses
        participant_id:
          description: Participant the rollforward covers
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        to:
          description: >-
            Period end (inclusive, RFC 3339), echoed from the request with any
            fractional seconds preserved, so replaying the echoed bounds returns
            the same figures
          example: '2026-01-31T23:59:59.999999Z'
          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.ParticipantRollforwardRowResponse:
      description: >-
        One asset row of a participant's period rollforward. Lines sum exactly
        to closing_balance − opening_balance; there is no plug line.
      properties:
        asset_id:
          description: Unique identifier for this asset
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        asset_name:
          description: Display name for this asset
          example: Loyalty Points
          type: string
        asset_symbol:
          description: Ticker or symbol for this asset (e.g., `POINTS`)
          example: POINTS
          type: string
        bucket_movements_net:
          description: >-
            HOLD/RELEASE/MATURITY entries: signed net effect. These move value
            between buckets of the same participant, so this is 0; reported so
            the decomposition is complete
          example: '0.00'
          type: string
        closing_balance:
          description: >-
            Participant balance for this asset across all buckets at the end of
            the period (ledger time <= to)
          example: '1295.00'
          type: string
        debited:
          description: >-
            DEBIT entries: value debited from the participant (manual API debits
            and rule-driven debits)
          example: '40.00'
          type: string
        expired:
          description: >-
            EXPIRATION entries: value expired out of the participant's lots
            during the period
          example: '0.00'
          type: string
        forfeited:
          description: >-
            FORFEIT entries: value forfeited from the participant during the
            period
          example: '15.00'
          type: string
        holds_voided:
          description: >-
            VOID_HOLD entries: provisionally held value voided back to the
            issuance source during the period
          example: '0.00'
          type: string
        issuance_returns:
          description: >-
            CREDIT entries: value returned to the issuance source during the
            period, produced by settling a provisional (HELD) credit for less
            than the held amount
          example: '30.00'
          type: string
        issued:
          description: >-
            CREDIT entries: value issued to the participant during the period
            (each entry's net movement across the participant's accounts, when
            positive)
          example: '300.00'
          type: string
        opening_balance:
          description: >-
            Participant balance for this asset across all buckets (AVAILABLE,
            HELD, DEFERRED) immediately before the period (ledger time < from)
          example: '1250.00'
          type: string
        redeemed:
          description: >-
            REDEMPTION entries: gross value redeemed out of the participant's
            accounts during the period (immediate redemptions and captured
            pending redemptions)
          example: '150.00'
          type: string
        redemption_receipts:
          description: >-
            REDEMPTION entries: value received INTO this participant's accounts
            because it is a program's configured redemption target. Zero for
            ordinary participants
          example: '0.00'
          type: string
        redemption_reversals:
          description: >-
            REVERSAL entries: value credited back to the participant by
            redemption reversals during the period
          example: '20.00'
          type: string
        reversal_clawbacks:
          description: >-
            REVERSAL entries: value taken back from the participant by reversals
            during the period. Covers event (award) reversals via `POST
            /v1/events/{id}/reverse` that recover previously issued value, and
            clawbacks of redemptions this participant had received as a
            program's redemption target
          example: '100.00'
          type: string
        scale:
          description: >-
            Number of decimal places for this asset; every amount in this row is
            rendered with exactly this many decimals
          example: 2
          type: integer
        transfers_net:
          description: >-
            TRANSFER entries: signed net effect of transfers on this participant
            (incoming minus outgoing)
          example: '-20.00'
          type: string
      type: object
    handlers.PaginationResponse:
      properties:
        has_more:
          description: Whether more results are available beyond this page
          example: true
          type: boolean
        next_cursor:
          description: Cursor to fetch the next page. Absent when there are no more results
          example: YWJjMTIz
          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)
          type: string
        field:
          description: Field name that caused the error (non-validation input errors)
          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)
          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
          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
          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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.