> ## 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.

# Invoice plans

> The plan that voids and creates a policy's invoices, the rule every plan meets, and each refusal with its fix

An invoice plan is one change to a policy's invoices: the invoices it voids
and the invoices it creates, applied together or not at all. Every door that
invoices a policy applies a plan, whether a quote's bind builds it or you send
it yourself ([Invoicing a policy](/api-reference/invoicing/overview)).

## Why invoices add up to billing

A policy's billing, its `fullTermBillingInfo`, is what the policy collects and
pays out, per line item: premium, taxes and fees in (`receivable` lines), and
payables such as broker or program commission out (`payable` lines). It states
what is owed, free of invoices. Invoices schedule each line: when each part is
billed or paid, and to whom.

So the two never disagree: **a policy's active invoices add up to its billing,
per line item, to the cent.** Each line distributes on its own, so premium in
four quarterly shares beside a fee billed once on the first invoice is one
billing and four invoices. A policy with no invoices meets the rule too:
invoices are optional until they exist. Billing states dollars; a plan states
cents, so a line of `"amount": 1200` is `120000` cents across its invoices.

## The shape

```json theme={null}
{
  "incurredDate": "2026-03-15",
  "voidInvoices": [
    { "invoiceId": "550e8400-e29b-41d4-a716-446655440702", "headJournalId": "550e8400-e29b-41d4-a716-446655440902" }
  ],
  "creates": [
    {
      "group": "Policy Invoice",
      "dueDate": "2026-04-01",
      "scheduledDate": "2026-04-01",
      "payeeId": "550e8400-e29b-41d4-a716-446655440010",
      "memo": "April installment",
      "lineItems": [{ "label": "Premium", "amountCents": 10000, "memo": "1 of 9" }]
    }
  ]
}
```

| Field | What it means |
| - | - |
| `incurredDate` | The date every create without a `scheduledDate` is recognized on. Required, and never taken from a transaction's effective date or the server clock. |
| `voidInvoices` | The policy's existing invoices to void. Every active invoice not named here is kept. |
| `voidInvoices[].invoiceId` | An invoice of this policy. |
| `voidInvoices[].headJournalId` | The invoice's version as you read it, from [List Invoices](/api-reference/financials/list-invoices) or [Get Invoice](/api-reference/financials/get-invoice). See [Version checks](#version-checks). |
| `creates` | The invoices to create. |
| `creates[].group` | The policy invoice type's name, such as `Policy Invoice`: a live type that allows each of the invoice's lines. |
| `creates[].dueDate` | When payment is due. |
| `creates[].scheduledDate` | An installment's send date, usually its due date minus the lead days: the invoice is recognized and sent on this date, and the invoice read shows it as its `incurredDate`. |
| `creates[].payeeId` | The person, organization or exposure of your company the invoice is issued to, of a kind its invoice type accepts. A create without one is refused. |
| `creates[].memo` | Free text on the invoice. |
| `creates[].lineItems` | One or more lines. |
| `lineItems[].label` | The line item's name on that invoice type: a line the policy's billing states or, with invoicing enabled, one a kept invoice carries. |
| `lineItems[].amountCents` | Signed integer cents in the line item's own direction. A negative amount is a credit on that line. |
| `lineItems[].memo` | Free text on the line. |

An empty plan (no voids, no creates) is valid: it keeps every invoice and
creates none.

## Kept and voided

A plan names what it voids. Every active invoice it does not name is kept,
and kept invoices count toward the total, so the invoices you create bill only
what the kept ones leave. Active means not voided and not deleted.

An invoice with payments, paid or partially paid, cannot be voided: the
policy transactions and the invoice batch refuse the plan with
`422 LIVE_PAYMENTS`, and a quote's plan names the invoice it cannot void. Keep
it; it counts toward its lines. To change what it covers, credit the line on a
new invoice.

## Credits

Credits follow the billing, in either of two forms:

* **A negative amount on an existing line.** When a change leaves less owed on
  a line than kept invoices bill (a cancellation of a paid policy, say), a
  create bills the difference as a negative amount on the same line. With
  invoicing enabled this works even for a line the new billing no longer
  states, such as a paid tax a flat cancellation drops: a line a kept invoice
  carries conserves at zero, so the credit takes it back to zero.
* **A billing line of its own.** State the credit in `fullTermBillingInfo` as
  its own line, with a negative `amount`, such as a return premium. It has its
  own line item type, so its own invoice types and schedule, and its invoices
  credit it like any other line.

The rule holds either way: kept and new invoices add up to the billing on
every line.

## Version checks

Each void names the `headJournalId` it read. If any invoice the plan voids
changed since (a payment, an approval, another plan), the whole plan is
refused with `409 finv2-invoice-head-conflict` and nothing is saved, so a
stale plan fails instead of overwriting a payment. Read the policy's invoices
again with `GET /api/v1/companies/{companyId}/financials/invoices?linkedPolicy={policyId}`
and rebuild the plan from their current `headJournalId`.

A plan saved on a quote is checked again when the quote binds, against the
invoices current then.

## Where a plan goes

| Where | How | What happens |
| - | - | - |
| On a quote | [Attach Quote Invoice Plan](/api-reference/invoicing/attach-quote-invoice-plan), or let [Generate Quote Invoices](/api-reference/invoicing/generate-quote-invoices) write it | Checked as it is saved. A bind with `invoices: "saved"` applies it, after checking it again. |
| With a change | `invoicePlan` on a policy transaction or on bind by value | Commits with the policy version, or neither commits. |
| On its own | [Update Policy Invoices](/api-reference/invoicing/update-policy-invoices), whose body is the plan | Re-plans a policy's invoices without changing the policy. It may void every unpaid invoice. |

## Refusals

A refused plan saves nothing. Each message names its fix, and any path it
names carries your request's ids. Codes and statuses are the contract;
messages may be reworded.

| Code | What it means | The fix |
| - | - | - |
| `403 finv2-policy-invoicing-disabled` | Policy invoicing is not enabled for your company. | Ask support to enable it. |
| `422 finv2-policy-restates-invoices` | A transaction moves the billing of a policy that has active invoices, and says nothing about them. | Send an `invoicePlan` with the change that voids the invoices it replaces and creates what it adds, so kept plus new invoices add up to the new billing. A quote's bind instead binds with `invoices: "generate"`, or attaches a plan and binds with `invoices: "saved"`. |
| `409 finv2-invoice-head-conflict` | An invoice the plan voids changed after you read it. | Read the policy's invoices again and rebuild the plan from their current `headJournalId`. |
| `404 finv2-invoice-not-found` | A void names an invoice that is not one of the policy's. | Read the policy's invoices again and rebuild the plan from them. |
| `422 LIVE_PAYMENTS` | A void names an invoice with payments. | Keep that invoice, and credit its line on a new invoice if the billing moved. |
| `422 finv2-policy-invoice-not-conserved` | Kept and new invoices do not add up to the billing. The message names each line and says which way the plan misses it, for example "the plan bills 1 cent too much". | Change the plan so kept plus new invoices add up to the billing on each line named. |
| `422 finv2-policy-batch-unpriced-charge` | A create invoices a line the policy's billing does not state. | Invoice only the lines the policy's billing states, or, with invoicing enabled, lines its kept invoices carry. |
| `422 finv2-policy-invoice-missing-aggregate` | The policy states no `fullTermBillingInfo`, so there is nothing to add up to. | State the policy's `fullTermBillingInfo` with a policy transaction first, or with the change that carries the plan. |
| `422 finv2-policy-batch-no-pricing` | The billing states nothing owed, and the plan creates invoices. | State the billing lines with a policy transaction first, or create no invoices. |
| `422 finv2-policy-invoice-binding-refused` | A billing line matches no policy invoice type in your financials configuration. | Export the financials configuration ([Export Financials Configuration](/api-reference/financials/export-financials-configuration)) to see which lines each type allows, fix the configuration, then retry. |
| `400 finv2-policy-invoices-required` | A same-term change voids every invoice while the billing still owes. | Keep or create invoices for what the billing still owes. To remove every invoice, use the invoice batch. |
| `422 finv2-policy-create-payee-invalid` | A create has no payee, or one that is not your company's or of a kind its type does not accept. | The message names the field and the kinds the invoice type accepts; choose one of them. |
| `400 finv2-policy-billing-required` | A same-term change states no billing on a term that has it. | State `fullTermBillingInfo` again, changed or unchanged. A quote's bind says the quote's billing calculation produced none: rate and save the quote so it states `fullTermBillingInfo`, or check its billing conditions in the configuration export. |
| `400 finv2-policy-billing-checksum` | The billing's `receivable` lines do not add up to the price. | Restate `fullTermBillingInfo` to match `fullTermPricingInfo.total`, or re-rate the quote. |
| `422 finv2-quote-invoices-do-not-match-pricing` | A quote's plan does not add up to the quote's billing and the policy's invoices. The message names each line and which way the plan misses it. | Generate the plan again, attach a corrected one, or bind with `invoices: "generate"`. If the quote states no billing at all, rate and save it again so it states `fullTermBillingInfo`. |
| `409 finv2-quote-has-invoice-plan` | A bind names no invoices while the quote holds a plan. | Bind with `invoices: "saved"`, or clear the plan. |
| `409 finv2-quote-invoice-plan-missing` | A bind names `invoices: "saved"` on a quote with no plan. | Generate or attach a plan, or bind with `invoices: "generate"`. |
| `422 finv2-payment-generation-refused` | Generating from a quote cannot run. | The message names what to change: the quote's invoice settings, through `PUT …/invoicing/settings`, or its `fullTermBillingInfo`, by rating and saving the quote again. |

[Quote invoicing](/api-reference/invoicing/quote-invoicing) covers a quote's
settings, generating and endorsement handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.