Invoice Aggregation
Invoice aggregation groups multiple regular invoices for one account into a single invoice that can be presented, paid, and tracked through a single bill. The system still generates regular invoices as it normally does. Aggregate invoices do not replace or change line items within regular invoices.
- Opt-in and manual. Nothing is aggregated unless a customer calls the API. Accounts that never use the feature behave exactly as before.
- One account, one currency. All regular invoices on an aggregate invoice belong to the same account and share one currency.
- No new charges. The aggregate invoice has no items of its own. Its total is the sum of the regular invoices it contains.
- Pay once, settle many. A payment applied to the aggregate invoice is spread across the regular invoices it contains, and the aggregate invoice is settled when all of them are settled.
Key Concepts
An aggregate invoice contains references to multiple regular invoices.
| Term | Meaning |
|---|---|
| Regular invoice | An invoice the system generates from the installments for a policy (invoiceType: normal). Unchanged by this feature. |
| Aggregate invoice | An account-level invoice with invoiceType: aggregate. It has no invoice items of its own. |
| Contained invoice | A regular invoice that is currently on an aggregate invoice. It reports the parent in aggregateInvoiceLocator. |
totalAmount | On an aggregate invoice, the sum of the invoice totals across all contained invoices. |
totalRemainingAmount | On an aggregate invoice, the sum of what is still unpaid across all contained invoices. |
Aggregate Invoice States
| State | When it applies |
|---|---|
open | At least one contained invoice is still open. |
settled | No contained invoice is open, including when it holds no invoices at all. settledTime is set. |
discarded | Manually discarded by API. It no longer appears in account invoice lists and cannot receive payments. |
State changes are automatic. When a payment, credit distribution, write-off, or reversal settles or reopens a contained invoice, the system re-evaluates the aggregate invoice and moves it between open and settled.
Membership Rules
- A regular invoice can be on at most one aggregate invoice at a time.
- Only regular invoices can be added. An aggregate invoice cannot contain another aggregate invoice.
- Open and settled regular invoices can both be added.
How It Works
The customer creates the aggregate invoice, manages which regular invoices it holds, and collects payment against it. The system keeps its totals and state in step with the regular invoices underneath.
- The system generates regular invoices as usual. Policies, installments, invoice generation, autopay, grace, and delinquency work exactly as they do today.
- The customer creates an aggregate invoice for an account with
POST /invoices, optionally listing up to 100 regular invoices to include. The system assigns an invoice number if invoice numbering is configured and emitsbilling.invoice.generate. - The system fills in the dates. Any of
startTime,endTime,dueTime, andtimezonenot available in the request is derived from the contained invoices: The earliest start, the latest end, the earliest due date, and their shared timezone (otherwise the account timezone, then the tenant default). - The document workflow is triggered. After an aggregate invoice is created, the policy document workflow is triggered.
- The Document Selection Plugin is notified that an aggregate invoice has been created.
- The Document Selection Plugin chooses whether to generate a document for the aggregate invoice or do nothing. No other actions are currently supported.
- If requested, invoice document generation is executed by the Document Data Snapshot Plugin.
- The customer adjusts membership as needed. Add or remove regular invoices with
PATCH /invoices/{locator}/aggregate, or move them to another aggregate invoice on the same account withPOST /invoices/{locator}/transfer. Each add emitsbilling.invoice.aggregate, and each removal emitsbilling.invoice.disaggregate. - The customer pays the aggregate invoice. A payment or credit distribution that targets the locator of the aggregate invoice is spread across its open contained invoices, earliest due date first, then smallest remaining amount.
- The system settles it. When the last open contained invoice is settled, the aggregate invoice moves to
settledand emitsbilling.invoice.settle. A later reversal that reopens a contained invoice moves it back toopenand emitsbilling.invoice.unsettle. - The customer discards it. An aggregate invoice that contains no invoices and has no credits recorded against it can be discarded with
PATCH /invoices/{locator}/discard.
The aggregate invoice never changes the amounts, items, or due dates of the regular invoices it contains. Removing a regular invoice simply returns it to standing on its own.
API Endpoints
The following API endpoints can be used to create and manage aggregate invoices:
| API Endpoint | Permissions | Purpose |
|---|---|---|
| Fetch Invoices for Aggregate Invoice | invoices.read, invoices.list | Fetch summaries of regular contained invoices. |
| Fetch Invoice Details for Aggregate Invoice | invoices.read, invoices.list | Fetch regular contained invoices with full details, including items. |
| Fetch Invoice Details | invoices.read | Fetch aggregate invoice details, including totalAmount and totalRemainingAmount. |
| Create Aggregate Invoice | invoices.write | Create an aggregate invoice that optionally contains regular invoices upon creation. |
| Update Aggregate Invoice | invoices.write | Change dates, currency, or timezone. Add or remove regular invoices. |
| Transfer Invoices Between Aggregate Invoices | invoices.write | Move regular invoices from an aggregate invoice to another within the same account. |
| Discard Aggregate Invoice | invoices.write | Discard an empty aggregate invoice with no credits. |
Events
| Event | Condition |
|---|---|
billing.invoice.generate | An aggregate invoice is created. |
billing.invoice.aggregate | A regular invoice is added to an aggregate invoice (one event per invoice, carrying aggregateInvoiceLocator). |
billing.invoice.disaggregate | A regular invoice is removed or transferred (one event per invoice). |
billing.invoice.settle | An aggregate invoice moves to the settled state. |
billing.invoice.unsettle | An aggregate invoice moves back to the open state. |
billing.invoice.discard | An aggregate invoice is discarded. |