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

# List group lots

> List lots for a group wallet by asset. Only applicable to `LOT` inventory mode assets. When program_id is provided, lots are scoped to original issuer lineage for that program.

Returns individual lots for one `LOT` mode asset held by a group. The `asset_id` query parameter is required. For `SIMPLE` mode assets, use the [group balances endpoint](/api-reference/groups/get-group-balances).

Pass `program_id` to return only lots whose original economic issuance came from that program. This filter follows the lot's issuer lineage, including after lot splits or transfers. It does not filter by the program associated with later ledger activity.

Each lot includes its original `amount`, current `remaining` amount, status, lifecycle timestamps, and `reference_id`. You can filter by `status`, `expires_before`, `expires_after`, or `reference_id`.

A successful response contains a `data` array and `pagination` metadata. Treat a missing or malformed response envelope as an error, not as confirmed empty inventory.

<Note>
  For lot lifecycle and expiration behavior, see the [Lots and expiration guide](/guides/lots-and-expiration).
</Note>


## OpenAPI

````yaml GET /v1/groups/{id}/balances/lots
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/groups/{id}/balances/lots:
    get:
      tags:
        - Groups
      summary: List group lots
      description: >-
        List lots for a group wallet by asset. Only applicable to `LOT`
        inventory mode assets. When program_id is provided, lots are scoped to
        original issuer lineage for that program.
      operationId: listGroupLots
      parameters:
        - description: Group ID
          in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
        - description: Scope lots to original economic issuance by this program
          in: query
          name: program_id
          schema:
            format: uuid
            type: string
        - description: Asset ID
          in: query
          name: asset_id
          required: true
          schema:
            format: uuid
            type: string
        - description: 'Filter by status: AVAILABLE, HELD, DEFERRED, CONSUMED, EXPIRED'
          in: query
          name: status
          schema:
            type: string
        - description: Filter lots expiring on or before this time (RFC 3339)
          in: query
          name: expires_before
          schema:
            type: string
        - description: Filter lots expiring on or after this time (RFC 3339)
          in: query
          name: expires_after
          schema:
            type: string
        - description: Filter lots by reference_id correlation key
          in: query
          name: reference_id
          schema:
            type: string
        - description: Maximum number of results (default 50, max 200)
          in: query
          name: limit
          schema:
            default: 50
            minimum: 1
            type: integer
        - description: Pagination cursor from previous response
          in: query
          name: cursor
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/handlers.ListResponse-handlers_LotResponse
          description: List of group lots
        '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: 'Group, program, 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.ListResponse-handlers_LotResponse:
      properties:
        data:
          description: Data contains the list of items
          items:
            $ref: '#/components/schemas/handlers.LotResponse'
          type: array
        pagination:
          allOf:
            - $ref: '#/components/schemas/handlers.PaginationResponse'
          description: Pagination contains cursor information for fetching more results
      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.LotResponse:
      properties:
        amount:
          description: Original amount credited
          example: '100.00'
          type: string
        asset_id:
          description: Asset this lot belongs to
          example: 550e8400-e29b-41d4-a716-446655440001
          format: uuid
          type: string
        created_at:
          description: When this lot was created
          example: '2024-01-15T10:30:00Z'
          format: date-time
          type: string
        expires_at:
          description: >-
            When this lot expires. Always present; null when the lot has no
            expiry
          example: '2025-12-31T23:59:59Z'
          format: date-time
          nullable: true
          type: string
        id:
          description: Lot ID
          example: 550e8400-e29b-41d4-a716-446655440002
          format: uuid
          type: string
        matures_at:
          description: >-
            When this lot becomes spendable. Always present; null when the lot
            has no maturity
          example: '2024-06-01T00:00:00Z'
          format: date-time
          nullable: true
          type: string
        reference_id:
          description: Correlation ID linking this held lot to a hold operation
          example: auth_12345
          type: string
        remaining:
          description: Amount still available
          example: '75.50'
          type: string
        status:
          description: Lot status
          example: AVAILABLE
          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)
          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

````