> ## 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. # Update giving batch > Recalculates totals after amount, fee, or membership changes. SETTLED is an accounting-owned state and cannot be set here. ## OpenAPI ````yaml /openapi.json patch /api/v1/batches/{id} 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/{id}: patch: tags: - Giving Batches summary: Update giving batch description: >- Recalculates totals after amount, fee, or membership changes. SETTLED is an accounting-owned state and cannot be set here. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/PathId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateGivingBatch' responses: '200': description: Updated giving batch content: application/json: schema: $ref: '#/components/schemas/GivingBatch' '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 PathId: name: id in: path required: true schema: type: string description: Resource ID example: cm456def789ghi schemas: UpdateGivingBatch: type: object additionalProperties: false description: >- All fields are optional; null clears nullable fields. SETTLED is read-only. properties: externalBatchId: type: string externalReference: type: string batchDate: type: string format: date givingIntegrationId: type: string givingMerchantId: type: string nullable: true settlementId: type: string nullable: true contributionIds: type: array maxItems: 10000 items: type: string dimensions: type: array maxItems: 100 items: $ref: '#/components/schemas/DimensionInput' status: type: string enum: - OPEN - COMMITTED - FAILED errorMessage: type: string nullable: true GivingBatch: type: object description: >- Giving batch whose totals and donation count are derived from current contribution membership. Metadata and sync diagnostics are excluded. properties: id: type: string externalBatchId: type: string externalReference: type: string batchDate: type: string format: date-time description: Calendar day represented as a UTC-midnight ISO timestamp. totals: $ref: '#/components/schemas/GivingTotals' status: type: string enum: - OPEN - COMMITTED - SETTLED - FAILED 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 dimensions: type: array items: $ref: '#/components/schemas/DimensionAssignment' fundSplits: type: array readOnly: true items: $ref: '#/components/schemas/FundSplit' contributionIds: type: array items: type: string isFrozen: type: boolean readOnly: true createdAt: type: string format: date-time updatedAt: type: string format: date-time 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. DimensionInput: type: object additionalProperties: false required: - dimensionId - dimensionValueId properties: dimensionId: type: string minLength: 1 dimensionValueId: type: string minLength: 1 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 DimensionAssignment: type: object additionalProperties: false required: - dimensionId - dimensionValueId properties: dimensionId: type: string dimensionName: type: string nullable: true readOnly: true dimensionValueId: type: string dimensionValueName: type: string nullable: true readOnly: true FundSplit: type: object additionalProperties: false required: - fundId - fundName - amount properties: fundId: type: string fundName: type: string nullable: true amount: type: number 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) ````