Socotra
Feature GuideBilling

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.

TermMeaning
Regular invoiceAn invoice the system generates from the installments for a policy (invoiceType: normal). Unchanged by this feature.
Aggregate invoiceAn account-level invoice with invoiceType: aggregate. It has no invoice items of its own.
Contained invoiceA regular invoice that is currently on an aggregate invoice. It reports the parent in aggregateInvoiceLocator.
totalAmountOn an aggregate invoice, the sum of the invoice totals across all contained invoices.
totalRemainingAmountOn an aggregate invoice, the sum of what is still unpaid across all contained invoices.

Aggregate Invoice States

StateWhen it applies
openAt least one contained invoice is still open.
settledNo contained invoice is open, including when it holds no invoices at all. settledTime is set.
discardedManually 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.

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

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

API EndpointPermissionsPurpose
Fetch Invoices for Aggregate Invoiceinvoices.read, invoices.listFetch summaries of regular contained invoices.
Fetch Invoice Details for Aggregate Invoiceinvoices.read, invoices.listFetch regular contained invoices with full details, including items.
Fetch Invoice Detailsinvoices.readFetch aggregate invoice details, including totalAmount and totalRemainingAmount.
Create Aggregate Invoiceinvoices.writeCreate an aggregate invoice that optionally contains regular invoices upon creation.
Update Aggregate Invoiceinvoices.writeChange dates, currency, or timezone. Add or remove regular invoices.
Transfer Invoices Between Aggregate Invoicesinvoices.writeMove regular invoices from an aggregate invoice to another within the same account.
Discard Aggregate Invoiceinvoices.writeDiscard an empty aggregate invoice with no credits.

Events

EventCondition
billing.invoice.generateAn aggregate invoice is created.
billing.invoice.aggregateA regular invoice is added to an aggregate invoice (one event per invoice, carrying aggregateInvoiceLocator).
billing.invoice.disaggregateA regular invoice is removed or transferred (one event per invoice).
billing.invoice.settleAn aggregate invoice moves to the settled state.
billing.invoice.unsettleAn aggregate invoice moves back to the open state.
billing.invoice.discardAn aggregate invoice is discarded.

See Also

On this page