> ## Documentation Index > Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # Update Policy Invoices > Applies one atomic keep/void/create plan to a policy's complete invoice set. This is the only document-write door for policy-linked invoices: the engine validates the plan against the policy's current pricing contract and commits every void and create together, or writes nothing. Existing active invoices omitted from `voidInvoices` are kept. Every void carries the `headJournalId` watermark from the read that the plan was based on; one stale head rejects the entire batch with `409`. The kept invoices plus `creates` must net every bound pricing component to exactly zero. The body is exactly a detached `PolicyInvoiceTransactionPlan`. `policyId` belongs only in the path. Dates, payees, lines, voids, and creates are never defaulted or inferred. **Required permission:** `company.payment:update` ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch: post: tags: - Financials summary: Update Policy Invoices description: > Applies one atomic keep/void/create plan to a policy's complete invoice set. This is the only document-write door for policy-linked invoices: the engine validates the plan against the policy's current pricing contract and commits every void and create together, or writes nothing. Existing active invoices omitted from `voidInvoices` are kept. Every void carries the `headJournalId` watermark from the read that the plan was based on; one stale head rejects the entire batch with `409`. The kept invoices plus `creates` must net every bound pricing component to exactly zero. The body is exactly a detached `PolicyInvoiceTransactionPlan`. `policyId` belongs only in the path. Dates, payees, lines, voids, and creates are never defaulted or inferred. **Required permission:** `company.payment:update` operationId: updatePolicyInvoices parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/policyIdPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PolicyInvoiceTransactionPlan' examples: replan: summary: Void one invoice and replace it with two installments value: incurredDate: '2026-08-01' voidInvoices: - invoiceId: 550e8400-e29b-41d4-a716-446655440700 headJournalId: 550e8400-e29b-41d4-a716-446655440900 creates: - group: Policy Invoice dueDate: '2026-08-01' payeeId: 550e8400-e29b-41d4-a716-446655440010 lineItems: - label: Policy Premium amountCents: 500000 - group: Policy Invoice dueDate: '2026-09-01' scheduledDate: '2026-08-02' payeeId: 550e8400-e29b-41d4-a716-446655440010 lineItems: - label: Policy Premium amountCents: 500000 responses: '200': description: The resulting policy invoice set. content: application/json: schema: $ref: '#/components/schemas/PolicyInvoiceBatchResponse' '400': description: Malformed plan, unknown field, or a policyId supplied in the body. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: The policy or an invoice referenced by the plan was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: At least one void watermark is stale; no action was applied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The plan failed policy-invoice binding, conservation, payment-lock, or other batch preconditions; no action was applied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier policyIdPath: name: policyId in: path required: true schema: type: string format: uuid description: Policy identifier schemas: PolicyInvoiceTransactionPlan: type: object additionalProperties: false required: - incurredDate - voidInvoices - creates properties: incurredDate: type: string format: date description: >- Explicit recognition date for non-scheduled creates. It is never inferred from a transaction effective date or the server clock. voidInvoices: type: array items: $ref: '#/components/schemas/PolicyInvoiceBatchVoid' creates: type: array items: $ref: '#/components/schemas/PolicyInvoiceBatchCreate' description: >- A fully explicit, detached policy-invoice batch. Existing invoices not named in voidInvoices are kept. The complete kept-plus-created set must conserve every bound component of the policy's current pricing contract. PolicyInvoiceBatchResponse: type: object additionalProperties: false required: - journalIds - invoices - scheduledDates properties: journalIds: type: array description: Journal ids emitted in execution order (voids, then creates). items: type: string format: uuid invoices: type: array description: >- All non-deleted policy invoices after the batch, voided rows included. items: $ref: '#/components/schemas/FinancialsV2Invoice' scheduledDates: type: object description: Sparse map from invoice id to its installment recognition date. additionalProperties: type: string format: date ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing PolicyInvoiceBatchVoid: type: object additionalProperties: false required: - invoiceId - headJournalId properties: invoiceId: type: string format: uuid headJournalId: type: string format: uuid description: >- The invoice watermark read while composing the plan. A stale watermark rejects the whole batch with 409. PolicyInvoiceBatchCreate: type: object additionalProperties: false required: - group - lineItems properties: group: type: string minLength: 1 description: Policy invoice type name, matching a pricing component group. dueDate: type: string format: date scheduledDate: type: string format: date description: >- Installment recognition anchor. When present, incurredDate for this invoice is this date and the invoice remains scheduled until it arrives. payeeId: type: string format: uuid description: Canonical Person, Organization, or Exposure entity billed or paid. memo: type: string lineItems: type: array minItems: 1 items: $ref: '#/components/schemas/PolicyInvoiceBatchCreateLine' FinancialsV2Invoice: type: object description: >- THE invoice representation — the same shape everywhere an endpoint returns an invoice (listing rows, the detail read, and every write's refreshed-row response). `headJournalId` is the invoice's current journal head — the optimistic-concurrency token subsequent writes echo back as `If-Match`. required: - id - invoiceNumber - categoryId - status - linkedEvent - linkedPolicy - linkedPayee - incurredDate - dueDate - memo - fieldData - lineItems - totalAmountCents - amountPaidCents - balanceDueCents - draftAmountPaidCents - paidDate - lastPaymentDate - voidedAt - deletedAt - approved - approvedAt - createdAt - updatedAt - headJournalId properties: id: type: string format: uuid description: The invoice's id invoiceNumber: type: string description: The invoice's system-minted display number categoryId: type: string format: uuid description: The transaction category the invoice belongs to status: type: string enum: - no_charges - owed - partially_paid - paid - voided - deleted description: >- Derived status, first match wins: `deleted` → `voided` → `no_charges` (every line item's amount is zero) → `paid` (every line item is settled — its amount minus its live marks is exactly zero) → `owed` (no live payment marks) → `partially_paid`. Settlement is per line: no scalar makes a document paid, and a zero-due document with unsettled lines still reads `owed` linkedEvent: type: object nullable: true description: >- The linked event, display-ready (the server resolves the display name), or `null` when not linked to an event required: - id - displayName properties: id: type: string format: uuid description: The linked event's id displayName: type: string description: The linked event's display name linkedPolicy: type: object nullable: true description: >- The linked policy, display-ready, or `null`. An invoice links to an event or a policy, never both required: - id - displayName properties: id: type: string format: uuid description: The linked policy's id displayName: type: string description: The linked policy's display name linkedPayee: type: object nullable: true description: >- The invoice's payee, display-ready, or `null` when none is set. `entityType` is an open string (e.g. `Person`, `Organization`) — the payee vocabulary is the entity module's, not part of this contract required: - id - entityType - displayName properties: id: type: string format: uuid description: The payee entity's id entityType: type: string description: The payee's entity type (e.g. Person, Organization) displayName: type: string description: The payee's display name incurredDate: type: string format: date nullable: true description: The date the charges were incurred (ISO `YYYY-MM-DD`), or `null` dueDate: type: string format: date nullable: true description: When payment is owed (display metadata only), or `null` memo: type: string nullable: true description: Free-text memo, or `null` fieldData: type: object nullable: true additionalProperties: true description: >- Values for the tenant-defined custom invoice fields, keyed by field referenceId — an opaque JSON object, or `null` lineItems: type: array description: The invoice's line items items: $ref: '#/components/schemas/FinancialsV2InvoiceLineItem' totalAmountCents: type: integer description: >- Sum of the ORIENTED line-item amounts (a payable-direction line counts +, a receivable-direction line counts −), in integer cents — the net cash the document commits to move amountPaidCents: type: integer description: >- Sum of the ORIENTED live payment marks, in integer cents — the net cash moved so far balanceDueCents: type: integer description: >- `totalAmountCents - amountPaidCents`, in integer cents — the net cash remaining to move: positive = out, negative = in. May move non-monotonically as opposite-direction lines settle draftAmountPaidCents: type: integer nullable: true description: >- A DRAFT's annex-derived paid total: the oriented net-cash sum of the payment marks the draft was born carrying (the same frame as `amountPaidCents`, which counts LIVE posted marks only and reads 0 while drafting) — what a draft's underlying payment picture will read once finalized. `null` on non-draft invoices (the annex is spent at finalize). Display-only — never a posted ledger amount paidDate: type: string format: date nullable: true description: >- Payment date of the mark that first made every line item settled; clears (`null`) whenever any line reopens lastPaymentDate: type: string format: date nullable: true description: Date of the most recent live payment, or `null` voidedAt: type: string format: date-time nullable: true description: When the invoice was voided, or `null` deletedAt: type: string format: date-time nullable: true description: When the invoice was deleted, or `null` approved: type: boolean description: >- The approval projection: `true` after `invoice.approved`, cleared only by `invoice.unapproved` — an edit never resets approval (the approval-relevant facts, line items and category, are immutable once posted). Only meaningful while the approvals feature is enabled; reads `false` otherwise approvedAt: type: string format: date-time nullable: true description: >- When the approval landed (`invoice.approved`), or `null` while unapproved — `approved` is exactly `approvedAt != null`. Like `approved`, only meaningful while the approvals feature is enabled; reads `null` otherwise createdAt: type: string format: date-time description: When the invoice was created updatedAt: type: string format: date-time description: When the invoice last changed headJournalId: type: string format: uuid description: >- The invoice's current journal head — send it as `If-Match` on the next write to this invoice; a mismatch is a `409` carrying the current row PolicyInvoiceBatchCreateLine: type: object additionalProperties: false required: - label - amountCents properties: label: type: string minLength: 1 description: Line-item label from the pricing contract and bound invoice type. amountCents: type: integer description: Signed integer cents in the configured line-item type's own frame. memo: type: string FinancialsV2InvoiceLineItem: type: object description: A stored invoice line item as rendered on invoice reads. required: - lineItemId - lineItemTypeId - memo - amountCents properties: lineItemId: type: string format: uuid description: The line item's id lineItemTypeId: type: string format: uuid description: >- The configured line item type this item cites — discover ids with `GET /api/v1/companies/{companyId}/financials/config/categories` memo: type: string nullable: true description: Free-text memo, or `null` amountCents: type: integer description: >- The line item's amount in integer cents — the magnitude a user would type; a negative amount is a credit within the item's own frame — it posts opposite the line item type's expected direction (e.g. a reversal or refund); the posting rule always comes from the type, never the sign responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action companyMismatch: summary: A valid API key naming another company in the URL value: error: code: AuthorizationError message: API key is not scoped to the requested company userMessages: - API key is not scoped to the requested company InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. ````