> ## 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 settlement > All relationship writes are tenant-scoped and atomic. Accounting-frozen settlements return 409. ## OpenAPI ````yaml /openapi.json patch /api/v1/settlements/{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/settlements/{id}: patch: tags: - Settlements summary: Update settlement description: >- All relationship writes are tenant-scoped and atomic. Accounting-frozen settlements return 409. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/PathId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSettlement' responses: '200': description: Updated settlement content: application/json: schema: $ref: '#/components/schemas/Settlement' '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: UpdateSettlement: type: object additionalProperties: false description: >- All fields are optional; null clears nullable fields. MATCHED and RECONCILED are read-only accounting states. properties: provider: type: string enum: - STRIPE - PUSHPAY - SUBSPLASH - TITHELY - PLANNING_CENTER - ROCK_RMS - RAMP - DIVVY - MANUAL externalId: type: string externalReference: type: string nullable: true estimatedArrivalDate: type: string format: date actualArrivalDate: type: string format: date nullable: true totalGross: type: number minimum: 0 totalFees: type: number minimum: 0 totalNet: type: number minimum: 0 currency: type: string minLength: 3 maxLength: 3 paymentCount: type: integer minimum: 0 settlementType: type: string nullable: true status: type: string enum: - PENDING - IN_TRANSIT - DEPOSITED - FAILED - CANCELLED errorMessage: type: string nullable: true failureCode: type: string nullable: true depositBasis: type: string nullable: true enum: - GROSS - NET givingIntegrationId: type: string nullable: true givingMerchantId: type: string nullable: true contributionIds: type: array maxItems: 10000 items: type: string givingBatchIds: type: array maxItems: 10000 items: type: string dimensions: type: array maxItems: 100 items: $ref: '#/components/schemas/DimensionInput' Settlement: type: object description: >- Recorded settlement values plus independently calculated linked-contribution totals. Accounting and bank-link state are read-only; raw provider metadata, sync diagnostics, accounting details, and fingerprints are excluded. required: - id - provider - externalId - estimatedArrivalDate - recordedTotals - linkedContributionTotals - currency - status - accounting - bankLink - isFrozen - createdAt - updatedAt properties: id: type: string provider: type: string enum: - STRIPE - PUSHPAY - SUBSPLASH - TITHELY - PLANNING_CENTER - ROCK_RMS - RAMP - DIVVY - MANUAL externalId: type: string externalReference: type: string nullable: true estimatedArrivalDate: type: string format: date-time description: Calendar day represented as a UTC-midnight ISO timestamp. actualArrivalDate: type: string format: date-time nullable: true description: Calendar day represented as a UTC-midnight ISO timestamp. recordedTotals: $ref: '#/components/schemas/GivingTotals' linkedContributionTotals: $ref: '#/components/schemas/GivingTotals' currency: type: string minLength: 3 maxLength: 3 settlementType: type: string nullable: true status: type: string enum: - PENDING - IN_TRANSIT - DEPOSITED - MATCHED - RECONCILED - FAILED - CANCELLED 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' dimensions: type: array items: $ref: '#/components/schemas/DimensionAssignment' batches: type: array items: $ref: '#/components/schemas/SettlementBatchSummary' 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 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 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 SettlementBatchSummary: type: object additionalProperties: false required: - id - externalReference - status - batchDate - totalNet properties: id: type: string externalReference: type: string status: type: string batchDate: type: string format: date-time 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 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) ````