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

1. **The system generates regular invoices as usual.** Policies, installments, invoice generation, autopay, grace, and delinquency work exactly as they do today.
2. **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 emits `billing.invoice.generate`.
3. **The system fills in the dates.** Any of `startTime`, `endTime`, `dueTime`, and `timezone` not 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).
4. **The document workflow is triggered.** After an aggregate invoice is created, the [policy document workflow](/configuration/resources/documents#policy-document-workflow) is triggered.
   * The [Document Selection Plugin](/configuration/plugins/document-selection) 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](/configuration/plugins/document-data-snapshot).
5. **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 with `POST /invoices/{locator}/transfer`. Each add emits `billing.invoice.aggregate`, and each removal emits `billing.invoice.disaggregate`.
6. **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.
7. **The system settles it.** When the last open contained invoice is settled, the aggregate invoice moves to `settled` and emits `billing.invoice.settle`. A later reversal that reopens a contained invoice moves it back to `open` and emits `billing.invoice.unsettle`.
8. **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 [#api-endpoints]

The following API endpoints can be used to create and manage aggregate invoices:

| API Endpoint                                                                                                    | Permissions                      | Purpose                                                                              |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------ |
| <ApiLink name="fetchInvoicesForAggregateInvoice">Fetch Invoices for Aggregate Invoice</ApiLink>                 | `invoices.read`, `invoices.list` | Fetch summaries of regular contained invoices.                                       |
| <ApiLink name="getInvoiceDetailsAttachedToAggregate">Fetch Invoice Details for Aggregate Invoice</ApiLink>      | `invoices.read`, `invoices.list` | Fetch regular contained invoices with full details, including items.                 |
| <ApiLink name="fetchInvoiceDetails">Fetch Invoice Details</ApiLink>                                             | `invoices.read`                  | Fetch aggregate invoice details, including `totalAmount` and `totalRemainingAmount`. |
| <ApiLink name="createAggregateInvoice">Create Aggregate Invoice</ApiLink>                                       | `invoices.write`                 | Create an aggregate invoice that optionally contains regular invoices upon creation. |
| <ApiLink name="patchAggregateInvoice">Update Aggregate Invoice</ApiLink>                                        | `invoices.write`                 | Change dates, currency, or timezone. Add or remove regular invoices.                 |
| <ApiLink name="transferInvoicesBetweenAggregateInvoices">Transfer Invoices Between Aggregate Invoices</ApiLink> | `invoices.write`                 | Move regular invoices from an aggregate invoice to another within the same account.  |
| <ApiLink name="discardAggregateInvoice">Discard Aggregate Invoice</ApiLink>                                     | `invoices.write`                 | Discard an empty aggregate invoice with no credits.                                  |

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

See Also [#see-also]

* [Invoice Aggregation API](/api/billing/invoice-aggregation)
* [Invoicing](/features/billing/invoicing)
* [Payments](/features/billing/payments)
* [Policy Document Workflow](/configuration/resources/documents#policy-document-workflow)
* [Document Selection Plugin](/configuration/plugins/document-selection)
* [Document Data Snapshot Plugin](/configuration/plugins/document-data-snapshot)
