# Invoicing



Overview [#overview]

*Invoicing* is the process of taking *planned* receivables, in the form of [installments](/features/billing/installments-and-installment-lattices) and creating *actual* receivables in the form of <ApiLink name="InvoiceResponse">invoices</ApiLink>. As part of this, the <ApiLink name="InstallmentItem">installment items</ApiLink> from the installments are used to create <ApiLink name="InvoiceItemResponse">invoice items</ApiLink> on the corresponding invoices.

After being generated (based on the `generateTime` of the installment), the invoices are eligible to be paid using either [payments](/features/billing/payments) or by drawing funds from a [credit balance](/features/billing/credit-balances).

Structure [#structure]

Each quote or policy transaction, when issued, results in a set of *installments* that sum to the full amount of the billable charges for that transaction. Each installment is specific to that transaction; installments never contain items that relate to more than one transaction.

When it becomes time to invoice one or more installments, those installments are grouped so that, for example, all installments with common values for `generateTime`, `dueTime` etc. are the same for each installment in the group. Then, all the installment items within a group are combined when they have the same charge type and are associated with the same policy element. For example, there may be three installments, with each containing an installment item for *premium* on a particular *vehicle*. These three items are combined into a single invoice item that has an amount equal to the sum of the amounts of those items. The `generateTime` will be adjusted if needed so that it is the start of the day that contains the time.

The installments are updated so that their `invoiceLocator` refers to the new invoice being generated. Likewise, its installment items are then updated so that their `invoiceItemLocator` properties are no longer null; each now refers to the locator of the new invoice item that contains its billable amount. In this way, there is traceability for each item on each invoice back to the installments, transactions, and charges that it reflects.

Each invoice item will assume the `timezone` of its associated policy. Any invoice item generated for an <ApiLink name="addCharges">ad-hoc flat charge</ApiLink> with no `policyLocator` provided in the charge creation request will be set to the tenant's `defaultTimezone`. If all invoice items share the same timezone, the invoice `timezone` will be set to that timezone. Otherwise, the invoice `timezone` will be set to UTC.

Due Times [#due-times]

Invoices each have a `dueTime` property, which reflects the time that the invoice is expected to be fully settled, usually by having payments applied. If the invoice remains unsettled after this time, then it is past due, and will invoke [delinquency](/features/billing/delinquency), either by being added to an existing delinquency process or by spawning a new delinquency.

The due time will always be adjusted as needed so that invoices are due at the end of the day for the timezone of the invoice. This is calculated by subtracting 1 millisecond from midnight at the end of the day.

If the <ApiLink name="ConfigurationRef">configuration</ApiLink> property `defaultBackdatedInstallmentsBilling` is set to `deferDueDate` and the invoice's `generateTime` is in the past, then the `dueTime` will be advanced by the difference between the `generateTime` and the current time, so that the expected duration between invoice presentation and its due time is preserved.

Invoices can become settled, and then *unsettled* due to a payment becoming reversed. In this case, if the `dueTime` is in the past, the system will behave as if the invoice had become past due in the usual way.

<span id="installmentTiming" />

Updating Installment Timing [#updating-installment-timing]

The <ApiLink name="updateInstallments" /> API endpoint can be used to modify the `generateTime`, `dueTime`, and `autopayTime` of uninvoiced installments. This endpoint does not modify installments that have already been used to generate an invoice.

Here's an example request:

```json
{
	"installmentLocators": [
		"01J5R7B8K3A8WVRNE0G2W7H1ZP",
		"01J5R7B8K3A8WVRNE0G2W7H1ZQ"
	],
	"generateTime": "2026-06-15T00:00:00Z",
	"dueTime": "2026-07-01T00:00:00Z",
	"autopayTime": "2026-06-29T00:00:00Z"
}
```

This endpoint can be used to modify one or more of the specified timing fields for up to 100 installments per request. All installments specified in the request must belong to the same [account](/features/accounts). The `dueTime` and `autopayTime` values, if specified, must be equal to or later than the `generateTime`.

If the request fails for any of the specified installments, no installments will be modified.

<span id="invoiceRendering" />

Invoice Rendering [#invoice-rendering]

Invoice rendering (the creation of a document that reflects the contents of the invoice) can be done by configuring a document to be rendered for the account. This includes both document rendering data and metadata, similar to how [policy documents](/configuration/resources/documents) are managed.

To generate invoice documents:

* Create one or more document resources (either with a template or pre-rendered document) using [resources configuration](/configuration/resources/documents).
* Upload template or rendered document instances for those resources.
* Set the `defaultInvoiceDocument` property in configuration either at the <ApiLink name="ConfigurationRef">global (tenant) level</ApiLink>, or for <ApiLink name="AccountRef">specific account types</ApiLink>.

From this point forward, invoices generated for the specific accounts will be retrievable via the <ApiLink name="fetchInvoiceDocument" /> endpoint.

<span id="invoice-fees" />

Invoice Fees [#invoice-fees]

Socotra provides a convenient way to automatically add [flat fees](/features/billing/flat-charges) to invoices. Such fees can be added to a quote or policy with no prior configuration via the <ApiLink name="updateQuoteInvoiceFeeAmount" /> and <ApiLink name="updatePolicyInvoiceFeeAmount" /> endpoints, respectively.

<Callout>
  Updating a quote invoice fee after quote issuance will have no effect.
</Callout>

You can also designate automatic additions of such fees to invoices. First, configure an invoice fee in <ApiLink name="ConfigurationRef">top-level configuration</ApiLink> by adding an <ApiLink name="InvoicingPlanRef" /> entry to `invoicingPlans`. After that, you may designate a `defaultInvoicingPlan` to take effect for all policies across all accounts. You can also set the `invoicingPlanName` on accounts, which would override the tenant-level `defaultInvoicingPlan`.

Only one such invoice fee may be added to a given invoice, with the following order of precedence:

* The invoice fee set explicitly on the quote or policy via dedicated API endpoints
* The `invoicingPlanName` set on the account
* The tenant-level `defaultInvoicingPlan`

If an invoice consists of charges from two or more policies with conflicting invoice fees, the account's `invoiceFeeHandling` setting will be used to determine the actual invoice fee amount. If `invoiceFeeHandling` is set to `waive`, then no invoice fees will be added to that account's invoices.

When an invoice is generated, an invoice fee will be added with `chargeType: InvoiceFee` and `chargeCategory: invoiceFee`. These charges will not appear in installment listings, but will be visible on invoice previews.

There are two special cases in which an invoice fee will not be added to an invoice, even if all other conditions are met:

1. An invoice of flat charges exclusively
2. A net-zero invoice

Example [#example]

Suppose you would like a $5.00 invoice fee added to all typical invoices. In your top-level configuration, define an invoicing plan and set the default:

```json
{
    // ...,
    "invoicingPlans": {
        "CustomerFee": {
        "displayName": "Customer Fee",
        "invoiceFeeHandling": "max",
        "invoiceFeeAmounts": {
            "USD": 5.00
        }
    },
    "defaultInvoicingPlan": "CustomerFee",
    // ...,
}
```

If you were to deploy this configuration update and issue a policy, you would see the fee amount reflected in invoice summaries, and listed as a distinct <ApiLink name="InvoiceItemResponse" /> in the <ApiLink name="InvoiceResponse" /> like this:

```json
{
	"locator": "01JTNK29A2X5TDZ3Q0W2MYBQ4Z",
	"chargeType": "InvoiceFee",
	"chargeCategory": "invoiceFee",
	"amount": 5.0
}
```

As mentioned above, you could override the default invoice fee plan for an account by setting the `invoicingPlanName` on <ApiLink name="AccountCreateRequest" /> or <ApiLink name="AccountUpdateRequest" />. You can also set an arbitrary invoice fee amount for quotes or policies via the two dedicated endpoints <ApiLink name="updateQuoteInvoiceFeeAmount" /> and <ApiLink name="updatePolicyInvoiceFeeAmount" />.

<span id="InvoiceConsolidation" />

Invoice Consolidation on Cancellation [#invoice-consolidation-on-cancellation]

When a cancellation [transaction](/features/policy-management/policy-transactions) is issued, the system can be configured to consolidate all remaining uninvoiced installments for the cancelled period into the next eligible invoice for that period. If enabled in the configuration, this consolidation logic will also be reflected in invoice [previews](/features/preview-operations). In past versions of the platform, when a cancellation transaction was issued, the system could continue to generate installments with small amounts, such as 1 cent, after cancellation.

All remaining uninvoiced installments for the cancelled period will be included in the consolidated invoice, with the following exceptions:

* Installments covered by a moratorium will not be included.
* If a reinstatement transaction is issued after a policy is cancelled, only installments prior to the reinstatement effective date will be included.

Configuration [#configuration]

This functionality can be configured through the `consolidateInvoicesOnCancellation` field in each <ApiLink name="InvoicingPlanRef" /> tenant [configuration](/configuration/general-topics/deployment) object.

The `consolidateInvoicesOnCancellation` field accepts the following values:

* `all` - All uninvoiced installments for the cancelled period are added to the consolidated invoice when a cancellation transaction is issued. This is the default value.
* `none` - No uninvoiced installments are consolidated when a cancellation transaction is issued. The cancellation invoice only contains the installment that results from the cancellation. All remaining uninvoiced installments will continue to be scheduled as expected based on the configured [installment settings](/features/billing/installment-settings). This effectively disables invoice consolidation on cancellation behavior.
* `future` - Only uninvoiced installments with a `generateTime` equal to or after the time the cancellation transaction issuance is processed are added to the consolidated invoice when a cancellation transaction is issued. All uninvoiced installments with a `generateTime` prior to this time will continue to be scheduled as expected based on the configured [installment settings](/features/billing/installment-settings).

Here's an example configuration featuring 3 separate `invoicingPlans` with different `consolidateInvoicesOnCancellation` values:

```json
{
	"invoicingPlans": {
		"ConsolidateAll": {
			"displayName": "Consolidate all uninvoiced installments on cancellation",
			"consolidateInvoicesOnCancellation": "all"
		},
		"NoConsolidation": {
			"displayName": "No invoice consolidation on cancellation",
			"consolidateInvoicesOnCancellation": "none"
		},
		"ConsolidateFuture": {
			"displayName": "Consolidate future uninvoiced installments only",
			"consolidateInvoicesOnCancellation": "future"
		}
	}
}
```

See Also [#see-also]

* [Installments and Installment Lattices](/features/billing/installments-and-installment-lattices)
* [Invoices API](/api/billing/invoices)
* [Installments API](/api/billing/installments)
* [Payments](/features/billing/payments)
* [Credit Balances](/features/billing/credit-balances)
* [Delinquency](/features/billing/delinquency)
* [Documents Configuration Guide](/configuration/resources/documents)