Invoicing

Overview

Invoicing lets you bundle one or more ledger entries on a policy into a single, immutable invoice with a renderable PDF, a well-defined status lifecycle, and standard events you can subscribe to.

Use invoicing when you need to present a policyholder (or, for commercial lines, a contractor or member) with a formal document for premiums, fees, and adjustments, and to track that document through to payment. An invoice ties together:

N ledger entries → 1 document. Each invoice line item references exactly one policy ledger entry. The ledger entry remains the source of truth for the amount and description; the invoice is the consolidating layer on top of it.
1 document → 1 payment. A pending invoice is picked up by the daily payment routine, which creates a payment to collect it. When that payment succeeds, the invoice is marked as paid.

📘
Invoicing is an opt-in feature

Invoicing is gated behind a feature flag and is off by default. It must be enabled per organization before the endpoints described in these pages will respond. Speak to your Root representative, or enable Invoicing under your organization's billing settings in the dashboard, before integrating.

🚧
Invoicing is distinct from collections and the ledger
Invoicing does not replace Collections or the policy ledger. It sits on top of them: the ledger records what is owed, collections move the money, and an invoice is the formal document that groups ledger entries and links them to a collection payment.

Key concepts

Concept	Description
Invoice	A first-class document raised against a single policy. Immutable once finalised.
Line item	A 1:1 link between an invoice and a policy ledger entry. A ledger entry can appear on at most one invoice.
Reference	A human-readable identifier, unique per organization. Supplied by you, or generated by Root as `INV-XXXXXXXX`.
Type	`proforma`, `receipted`, or `credit_note`. Your invoice template branches on the type to choose a layout.
Status	Where the invoice is in its lifecycle: `open`, `pending`, `sent`, `paid`, `void`, or `refunded`. See

What you can do

Create an invoice by selecting uninvoiced ledger entries on a policy.
List uninvoiced ledger entries to discover what is available to invoice on a policy.
Retrieve an invoice or list all invoices for a policy.
Issue a credit note to refund a previously raised invoice. See Credit notes and refunds .
React to invoice events such as invoice_created and invoice_paid. See Invoice events .

How an invoice flows through Root

Ledger entries are raised on a policy through your normal billing setup (premiums, fees, adjustments). 2. You create an invoice referencing one or more of those uninvoiced ledger entries. The invoice is finalised: a reference is allocated, the total is computed, and a PDF is queued for rendering. The invoice moves to pending and an invoice_created event fires. 3. The daily payment routine creates a payment for the pending invoice and moves it to sent (invoice_sent). 4. When the payment succeeds, the invoice moves to paid (invoice_paid). 5. If you later need to refund, you raise a credit_note invoice against the original. The original moves to refunded (invoice_refunded).