Skip to main content
Every request that invoices a policy says where its invoices come from. You either drive a saved quote through the same steps as the app, or you state the invoices yourself. Either way, a policy’s invoices always add up to its billing.

​
Three doors

​
Nothing applies silently

Invoice behavior lives in the request, so the request you send predicts the invoices you get. No invoices apply that the request does not name:
  • A quote’s saved plan applies only when its bind names it with invoices: "saved". A bind that names no invoices while the quote holds a plan is refused (409 finv2-quote-has-invoice-plan) rather than applying it. A saved quote’s bind binds the quote’s state, so it never takes an invoicePlan: a plan you wrote goes on the quote first, where Check Bind Conditions can check it before anything commits.
  • A value door creates exactly the invoices its invoicePlan creates and voids exactly the invoices it names. Without a plan it creates none.
  • A refusal commits nothing and names its fix, with the ids of your request in any path it names. Invoice plans lists them.
Invoices need policy invoicing enabled for your company. With it disabled, a request that names invoices (an invoicePlan, a bind’s invoices, the invoice batch or the quote invoicing endpoints) returns 403 finv2-policy-invoicing-disabled and saves nothing.

​
The rule

A policy’s active invoices add up to its billing, per line item, to the cent. A plan names the invoices it voids; every invoice it does not name is kept and counts toward the total. Invoice plans explains the plan’s shape, why the rule holds, credits, and how a stale plan is refused.

​
Five flows

All five use one policy: a year from 2026-01-01 whose billing states one line, Premium on the Policy Invoice type, of 1,200.00. Billing states dollars ("amount": 1200); a plan states cents ("amountCents": 120000). Every invoice is issued to the same payee, an organization of the company. The names (the Policy Invoice type, the Premium line item and its premium classification) are this example company’s. Use your company’s own, which Export Financials Configuration lists. The request bodies show what invoicing needs; your company’s policy configuration may require more in data, such as a policy number, a time zone or the insured.

​
1. Review, then bind

Quote door. You prepare the quote’s invoices, review them, then bind exactly what you reviewed.
  1. Save the quote (for example with Update Entity after rating it). Its billing calculation states fullTermBillingInfo.
  2. Choose the schedule, payees and endorsement handling.
    PUT /api/v1/companies/{companyId}/quotes/{quoteId}/invoicing/settings
  3. Generate the invoices onto the quote: POST /api/v1/companies/{companyId}/quotes/{quoteId}/invoicing/generate, with no body. The quote’s plan now creates four Premium invoices of 30000 cents, due 2026-01-01, 2026-04-01, 2026-07-01 and 2026-10-01.
  4. Review them with GET /api/v1/companies/{companyId}/quotes/{quoteId}/invoicing. Optionally, check the bind you are about to send: GET /api/v1/companies/{companyId}/quotes/{quoteId}/bind-conditions?invoices=saved answers "readyToBind": true.
  5. Bind the plan you reviewed.
    POST /api/v1/companies/{companyId}/quotes/{quoteId}/bind
Outcome: the new policy has the four invoices of the plan, 30000 cents each, 120000 in all, which is its billing.

​
2. Generate at bind

Quote door. You let the bind build the invoices from the quote’s settings.
  1. Save the quote, as in flow 1. Choose its settings first if the company’s payment defaults are not what you want.
  2. Bind, generating as you go.
    POST /api/v1/companies/{companyId}/quotes/{quoteId}/bind
Outcome: the policy’s invoices are the ones Generate Quote Invoices would build from the quote’s saved settings at that moment: four quarterly invoices of 30000 cents with the settings of flow 1. The quote keeps no plan of them, and a plan already saved on the quote is not applied.

​
3. New business with a plan

Value door. You create the policy and state its twelve monthly invoices in the same request.
POST /api/v1/companies/{companyId}/policies/transaction/new-business
Outcome: the policy and its twelve invoices commit together, 10000 cents each, 120000 in all. Each invoice is sent on its scheduledDate.

​
4. Mid-term endorsement

Value door. On 2026-10-15 the premium rises to 1,320.00. The ten invoices due through October stay; the last two are replaced.
  1. Read the policy’s invoices and note the id and headJournalId of the two you will replace: GET /api/v1/companies/{companyId}/financials/invoices?linkedPolicy={policyId}.
  2. Endorse, stating the new price and billing and the invoices that change.
    POST /api/v1/companies/{companyId}/policies/{policyId}/transaction/endorse
Outcome: kept plus new add up to the new billing: ten kept invoices of 10000 and two new ones of 16000 make 132000 cents, which is 1,320.00. The version and its invoices commit together. Had an invoice changed since you read it, the endorsement would have been refused with 409 finv2-invoice-head-conflict and nothing saved; read the invoices again and rebuild the plan.

​
5. Switch to monthly

After the bind. The policy of flow 1 has four quarterly invoices, and the first is paid. On 2026-03-15 the insured asks to pay the rest monthly.
  1. Read the policy’s invoices, as in flow 4.
  2. Void the three unpaid quarterly invoices and create nine monthly ones.
    POST /api/v1/companies/{companyId}/financials/policies/{policyId}/invoices/batch
Outcome: the same total on a new schedule: the paid quarterly invoice of 30000 is kept, and nine monthly invoices of 10000 replace the three voided ones, 120000 cents in all. The policy itself does not change.

​
Where to go next

  • Invoice plans: the plan’s fields, the add-up rule, credits, version checks and every refusal with its fix.
  • Quote invoicing: a quote’s settings, where payees and defaults come from, generating versus attaching, and endorsement handling.
  • Policy Transactions: the five transactions and the policy’s billing.