Invoice plans

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

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

{
  "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 or Get Invoice. See 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, or let 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, 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) 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 covers a quote’s settings, generating and endorsement handling.

Getting Started

User

Companies

Entities

Submission and Quote Lifecycle

Event Lifecycle

OFAC Screening

Policy Transactions

Policy Invoicing

Financials

Rating

Notes

Tasks

Configuration Management

Company Files

Forms

Document Generation

Submission Parsing

Reference

Why invoices add up to billing

The shape

Kept and voided

Credits

Version checks

Where a plan goes

Refusals

​Why invoices add up to billing

​The shape

​Kept and voided

​Credits

​Version checks

​Where a plan goes

​Refusals

Why invoices add up to billing

The shape

Kept and voided

Credits

Version checks

Where a plan goes

Refusals