> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grainledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List giving batches

> Returns giving batches, not pledge-card review batches. Totals are derived from current contribution membership.



## OpenAPI

````yaml /openapi.json get /api/v1/batches
openapi: 3.0.3
info:
  title: Grain API
  description: >-
    Church accounting and donor management API. Use an organization API key for
    server automation or OAuth 2.1 (Sign in with Grain) for applications acting
    on behalf of users. OAuth requests require X-Organization-Id; API keys infer
    it.
  version: 1.1.0
servers:
  - url: https://api.grainledger.com
    description: API Server
security:
  - ApiKeyAuth: []
  - GrainOAuth2: []
  - BearerAuth: []
tags:
  - name: Transactions
    description: Bank transactions and reconciliation
  - name: Bills
    description: Vendor bills from creation through payment
  - name: Donors
    description: Donor records and household relationships
  - name: Contributions
    description: Giving records with fund assignment and settlement
  - name: Giving Batches
    description: Contribution groups with derived totals and lifecycle state
  - name: Settlements
    description: Provider deposits with recorded and linked-contribution totals
  - name: Pledges
    description: Pledge campaigns and fulfillment tracking
  - name: Pledge Card Imports
    description: Submit structured pledge card data for review
  - name: Households
    description: Household groupings and primary contacts
paths:
  /api/v1/batches:
    get:
      tags:
        - Giving Batches
      summary: List giving batches
      description: >-
        Returns giving batches, not pledge-card review batches. Totals are
        derived from current contribution membership.
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/GivingLimit'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - OPEN
              - COMMITTED
              - SETTLED
              - FAILED
        - name: dateFrom
          in: query
          schema:
            type: string
            format: date
        - name: dateTo
          in: query
          schema:
            type: string
            format: date
        - name: givingIntegrationId
          in: query
          schema:
            type: string
        - name: givingMerchantId
          in: query
          schema:
            type: string
        - name: settlementId
          in: query
          schema:
            type: string
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - batchDate
              - totalGross
              - totalNet
              - createdAt
            default: batchDate
        - name: sortOrder
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: Paginated giving batches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GivingBatchListResponse'
              examples:
                default:
                  $ref: '#/components/examples/GivingBatchListExample'
        '400':
          description: Bad request (missing header or invalid input)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (missing or invalid Bearer token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden (no access to organization or action)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Conflict (duplicate, cross-resource ownership conflict, concurrent
            change, or accounting-frozen resource)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    OrganizationId:
      name: X-Organization-Id
      in: header
      required: false
      schema:
        type: string
      description: >-
        Required with OAuth access tokens. Optional with organization API keys;
        if supplied, it must match the key's organization.
      example: cm123abc456def
    Page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
      description: Page number (1-based)
    GivingLimit:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
      description: Giving records per page
  schemas:
    GivingBatchListResponse:
      type: object
      properties:
        batches:
          type: array
          items:
            $ref: '#/components/schemas/GivingBatchSummary'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Error:
      type: object
      description: >-
        Every error response is valid JSON with this shape. The HTTP status code
        carries the outcome; `code` is a stable machine-readable form of it.
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - bad_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - unprocessable_entity
            - payload_too_large
            - rate_limited
            - internal_server_error
          example: forbidden
        message:
          type: string
          example: You do not have access to this organization.
        error:
          type: string
          deprecated: true
          description: Deprecated alias for `message`. Read `message` instead.
          example: You do not have access to this organization.
    GivingBatchSummary:
      type: object
      description: >-
        Compact giving batch identity, calendar date, derived totals, lifecycle,
        and linked settlement summary.
      properties:
        id:
          type: string
        externalBatchId:
          type: string
        externalReference:
          type: string
        batchDate:
          type: string
          format: date-time
        totals:
          $ref: '#/components/schemas/GivingTotals'
        status:
          type: string
        isCommitted:
          type: boolean
        committedAt:
          type: string
          format: date-time
          nullable: true
        processedAt:
          type: string
          format: date-time
          nullable: true
        errorMessage:
          type: string
          nullable: true
        givingIntegration:
          $ref: '#/components/schemas/GivingIntegrationSummary'
          nullable: true
        merchant:
          $ref: '#/components/schemas/MerchantRelationshipSummary'
          nullable: true
        settlement:
          $ref: '#/components/schemas/BatchSettlementSummary'
          nullable: true
        journalEntry:
          $ref: '#/components/schemas/JournalEntryRelationshipSummary'
          nullable: true
          readOnly: true
        isFrozen:
          type: boolean
          readOnly: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 142
        totalPages:
          type: integer
          example: 8
    GivingTotals:
      type: object
      properties:
        gross:
          type: number
        fees:
          type: number
        net:
          type: number
        paymentCount:
          type: integer
        donationCount:
          type: integer
    GivingIntegrationSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - provider
        - name
      properties:
        id:
          type: string
        provider:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
    MerchantRelationshipSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - campusId
        - dimensionValueId
      properties:
        id:
          type: string
        name:
          type: string
        campusId:
          type: string
          nullable: true
        dimensionValueId:
          type: string
          nullable: true
    BatchSettlementSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - provider
        - externalReference
        - status
        - totalNet
      properties:
        id:
          type: string
        provider:
          type: string
        externalReference:
          type: string
          nullable: true
        status:
          type: string
        totalNet:
          type: number
    JournalEntryRelationshipSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - entryNumber
        - referenceNumber
      properties:
        id:
          type: string
        entryNumber:
          type: string
          nullable: true
        referenceNumber:
          type: string
          nullable: true
  examples:
    GivingBatchListExample:
      value:
        batches:
          - id: batch_1
            externalBatchId: api-example
            externalReference: Sunday online gifts
            batchDate: '2026-08-16T00:00:00.000Z'
            totals:
              gross: 1025
              fees: 25
              net: 1000
              donationCount: 8
            status: OPEN
            isCommitted: false
            committedAt: null
            processedAt: null
            dimensions: []
            fundSplits:
              - fundId: fund_1
                fundName: General
                amount: 1025
            contributionIds:
              - contribution_1
            isFrozen: false
            createdAt: '2026-08-16T12:00:00.000Z'
            updatedAt: '2026-08-16T12:00:00.000Z'
        pagination:
          page: 1
          limit: 20
          total: 1
          totalPages: 1
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: grain_live_… or grain_test_…
      description: >-
        Organization API key created in Grain Settings → API. The key determines
        the organization and is limited to its assigned resource scopes. Write
        scopes imply the corresponding read scope.
    GrainOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.grainledger.com/auth/v1/oauth/authorize
          tokenUrl: https://auth.grainledger.com/auth/v1/oauth/token
          scopes:
            openid: OpenID Connect
            email: Email address
            profile: Profile information
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth access token (JWT)

````