Invoicing

Overview

Invoicing is the process of taking planned receivables, in the form of installments and creating actual receivables in the form of invoices. As part of this, the installment items from the installments are used to create invoice items on the corresponding invoices.

After being generated (based on the generateTime of the installment), the invoices are eligible to be paid using either payments or by drawing funds from a credit balance.

Structure

Each quote or policy transaction, when invoiced, 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 tracability for each item on each invoice back to the installments, transactions, and charges that it reflects.

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, 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 configuration 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 preseentation 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.

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

To generate invoice documents:

From this point forward, invoices generated for the specific accounts will be retrievable via the Fetch Invoice Document endpoint.

Invoice Fees

Socotra provides a convenient way to automatically add flat fees to invoices. Such fees can be added to a quote or policy with no prior configuration via the Update Invoice Fee Amount and Update Policy Invoice Fee Amount endpoints, respectively.

Note

Updating a quote invoice fee after quote issuance will have no effect.

You can also designate automatic additions of such fees to invoices. First, configure an invoice fee in top-level configuration by adding an 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

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:

{
    // ...,
    "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 InvoiceItemSummary item in invoiceItemSummaries like this:

{
    "invoiceItemLocator": "01JTNK29A2X5TDZ3Q0W2MYBQ4Z",
    "chargeType": "InvoiceFee",
    "chargeCategory": "invoiceFee",
    "amount": 5.00,
    "remainingAmount": 5.00
}

As mentioned above, you could override the default invoice fee plan for an account by setting the invoicingPlanName on AccountCreateRequest or AccountUpdateRequest. You can also set an arbitrary invoice fee amount for quotes or policies via the two dedicated endpoints Update Invoice Fee Amount and Update Policy Invoice Fee Amount.

See Also