> ## 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 settlements > Returns recorded totals and independently calculated totals from linked contributions. dateFrom/dateTo filter the UTC calendar arrival day; dateTo is inclusive to callers. ## OpenAPI ````yaml /openapi.json get /api/v1/settlements 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/settlements: get: tags: - Settlements summary: List settlements description: >- Returns recorded totals and independently calculated totals from linked contributions. dateFrom/dateTo filter the UTC calendar arrival day; dateTo is inclusive to callers. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/GivingLimit' - name: provider in: query schema: type: string enum: - STRIPE - PUSHPAY - SUBSPLASH - TITHELY - PLANNING_CENTER - ROCK_RMS - RAMP - DIVVY - MANUAL - name: status in: query schema: type: string enum: - PENDING - IN_TRANSIT - DEPOSITED - MATCHED - RECONCILED - FAILED - CANCELLED - 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: sortBy in: query schema: type: string enum: - estimatedArrivalDate - totalGross - totalNet - createdAt default: estimatedArrivalDate - name: sortOrder in: query schema: type: string enum: - asc - desc default: desc responses: '200': description: Paginated settlements content: application/json: schema: $ref: '#/components/schemas/SettlementListResponse' examples: default: $ref: '#/components/examples/SettlementListExample' '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: SettlementListResponse: type: object properties: settlements: type: array items: $ref: '#/components/schemas/SettlementSummary' 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. SettlementSummary: type: object description: >- Compact settlement identity, lifecycle, recorded totals, linked-contribution totals, and accounting/bank-link state. properties: id: type: string provider: type: string externalId: type: string externalReference: type: string nullable: true estimatedArrivalDate: type: string format: date-time actualArrivalDate: type: string format: date-time nullable: true recordedTotals: $ref: '#/components/schemas/GivingTotals' linkedContributionTotals: $ref: '#/components/schemas/GivingTotals' currency: type: string settlementType: type: string nullable: true status: type: string errorMessage: type: string nullable: true failureCode: type: string nullable: true depositBasis: type: string nullable: true enum: - GROSS - NET givingIntegration: $ref: '#/components/schemas/GivingIntegrationSummary' nullable: true merchant: $ref: '#/components/schemas/MerchantRelationshipSummary' nullable: true accounting: $ref: '#/components/schemas/SettlementAccountingSummary' bankLink: $ref: '#/components/schemas/SettlementBankLinkSummary' 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 SettlementAccountingSummary: type: object additionalProperties: false readOnly: true required: - disposition - reason - journalEntry properties: disposition: type: string enum: - ELIGIBLE - NEEDS_REVIEW - RECORDED_EXTERNALLY reason: type: string nullable: true journalEntry: $ref: '#/components/schemas/JournalEntryRelationshipSummary' nullable: true SettlementBankLinkSummary: type: object additionalProperties: false readOnly: true required: - isLinked - transaction properties: isLinked: type: boolean transaction: type: object nullable: true additionalProperties: false required: - id - date - amount - description properties: id: type: string date: type: string format: date-time amount: type: number description: type: string JournalEntryRelationshipSummary: type: object additionalProperties: false required: - id - entryNumber - referenceNumber properties: id: type: string entryNumber: type: string nullable: true referenceNumber: type: string nullable: true examples: SettlementListExample: value: settlements: - id: settlement_1 provider: MANUAL externalId: api-example externalReference: August online giving estimatedArrivalDate: '2026-08-21T00:00:00.000Z' actualArrivalDate: null recordedTotals: gross: 1025 fees: 25 net: 1000 paymentCount: 8 linkedContributionTotals: gross: 1025 fees: 25 net: 1000 paymentCount: 8 currency: USD settlementType: null status: PENDING accounting: disposition: ELIGIBLE reason: null journalEntry: null bankLink: isLinked: false transaction: null dimensions: [] batches: [] isFrozen: false createdAt: '2026-08-21T12:00:00.000Z' updatedAt: '2026-08-21T12: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) ````