Excess Credits

Overview

Typically, funds flow in one direction only within an insured’s billing account: inward. Customers accrue charges based on provided coverage, and they send payments to cover those charges. Occasionally the funds can move in the other direction, where the carrier must send a disbursement back to the insured. This can happen in situations like:

  • Return premium from policy changes that reduce overall premium

  • Cancellations

  • Overpayments

  • Erroneously sent or applied payments

  • Reallocating payments such that greater amounts are allocated to credit balances

  • Ad-hoc credits

To avoid accrual of too much credit for any particular account, you can use rules about when and how credits beyond a desired threshold are to be returned or otherwise used.

Configuration

Automatic handling of excess credits requires creating one or more Excess Credit Plans, each of which describe the rules for handling excess credits. Each insured account in the system can be assigned an excess credit plan, and then the rules for that plan will be activated for that account.

An excess credit plan looks like this:

ExcessCreditPlanRef
required
advanceDisbursementTo Enum draft | validated | approved | executed | reversed | rejected | discarded
autoApplyExcessToInvoicesEnabled boolean
disburseExcess boolean
Set to true to enable excess funds handling for the plan.
disbursementType string
The type of the disbursement to be automatically created.
excludeDebits Enum none | pastDueInvoices | allInvoices | invoicesAndUnbilledInstallments
Which pending debits should be considered for determining how much of the credit to retain
negativeInvoiceHandling NegativeInvoiceHandlingRef
disbursementThresholds map<string,number>

The disbursementType property should be set to one of the disbursement types configured in the system.

The advanceDisbursementTo property allows you to specify the state the system should advance automatic disbursements to, enabling a step for review or custom processes before the disbursement state is progressed further via API. This property should be set to draft, validated, approved, or executed, and defaults to executed if not provided.

Process

If an excess credit plan is assigned to an account and that plan has disburseExcess: true, then each time that account’s credit balance is increased, the system will do the following:

  • Start with the new credit balance amount.

  • Reduce it as indicated with the excludeDebits property.

  • Create a disbursement to the insured as given by the disbursementType property on the plan.

  • Advance the disbursement to the state indicated by the advanceDisbursementTo property. If not specified, the disbursement is executed and funds distributed.

  • The details about the disbursement, including its credit balance source, will be available on the newly-created disbursement entity.

For example, if excludeDebits is allInvoices, the sum of the unsettled amount for all outstanding invoices should be deducted from the credit balance amount. If the remainder is greater than zero, create a disbursement with amount equal to this remainder, and advance it to the state specified by advanceDisbursementTo.

For accounts with credit balances in multiple currencies, a separate disbursement will be created for each currency.

Note

It is possible in some cases for the excess amount (as it would be calculated above) to increase even if the credit balance itself does not increase, such as when payments are received while funds remain in a credit balance. Excess credits handling is not automatically triggered in those cases.

Automatic Disbursement Handling

Account credit balance amounts are only reserved when a disbursement transitions to an approved state. When advanceDisbursementTo is set to draft or validated, the system-generated disbursement waits for API approval. During this waiting period, the credit balance may change due to payments, reversals, new invoices settled, or other activity.

To accommodate these changes, the following processing rules apply:

  • The amount of a disbursement is updated to reflect the current credit balance of the account, with updates occurring at the same frequency as automatic disbursement creation.

  • When a disbursement is approved, the approved amount is treated as an upper limit. Upon advancement to executed, the amount is recalculated and the lesser of the recalculated and approved amounts is distributed.

  • If the recalculated amount for a disbursement becomes zero, the disbursement is discarded. A new disbursement will be created when additional funds become available for distribution.

  • A disbursement in an approved or executed state is never modified. A new disbursement will be created when additional funds become available for distribution.

  • A disbursement in a validated state is validated again each time it is updated.

Note

The advanceDisbursementTo property and its processing apply only to system-generated automatic disbursements and do not affect disbursements created via API.

Negative Invoice Processing

Credit amounts may originate from invoices with negative amounts that were generated for a coverage period. By default, these credit amounts are added to the credit balance for the account. Each account can be configured to automatically settle open, unsettled invoices with non-negative amounts using these credit amounts or direct the system to leave such credit amounts in the original negative invoices.

Negative invoice processing logic is executed when invoices are generated.

Configuration

Negative invoice handling behavior can be configured through the NegativeInvoiceHandlingRef configuration object within each ExcessCreditPlanRef configuration object for an account.

The following configuration example highlights the default value for each property:

{
  "excessCreditPlans": {
    "ExamplePlanName": {
      "negativeInvoiceHandling": {
        "automaticallySettleNegativeInvoices": "toCreditBalance", // toOpenInvoices | toCreditBalance | never
        "prioritizeOverlappingCoveragePeriods": true, // true | false
        "targetInvoices": "allOpenInvoices", // overlappingCoveragePeriodsOnly | overlappingCoverageAndEarlier | allOpenInvoices
        "targetInvoicePriority": "smallestFirst", // smallestFirst | earliestFirst | byAmount
        "processingMode": "accountLevel", // accountLevel | policyLevel
        "yieldExcessToCreditBalance": true // true | false
      }
    }
  }
}

The automaticallySettleNegativeInvoices property indicates whether negative invoice credits should be applied to open invoices, added to the credit balance for the account, or if they should remain within the original negative invoices.

Currently, the system only supports account-level processing. If processingMode is set to policyLevel instead of accountLevel, configuration deployment will fail.

The remaining properties are used to adjust the following processing logic when automaticallySettleNegativeInvoices is set to toOpenInvoices.

Processing Logic

The system executes the following processing logic when automaticallySettleNegativeInvoices is set to toOpenInvoices.

The system will first fully settle the negative invoice if yieldExcessToCreditBalance is set to true or partially settle the negative invoice if yieldExcessToCreditBalance is set to false. Credits will be stored in a temporary invoiceCreditBalance.

If the invoiceCreditBalance is 0.00, processing will stop.

Otherwise, the system will then fetch all open invoices with non-negative amounts, and group them based on the following criteria:

  • Group 1: If prioritizeOverlappingCoveragePeriods is set to true, or targetInvoices is set to overlappingCoveragePeriodsOnly, add invoices where the startTime and endTime exactly match the startTime and endTime of the negative invoice. Otherwise, the group will be empty.

  • Group 2: If targetInvoices is set to overlappingCoverageAndEarlier or allOpenInvoices, add invoices where the startTime is before the endTime of the negative invoice, excluding invoices in group 1.

  • Group 3: If targetInvoices is set to allOpenInvoices, add invoices where the startTime is later than or equal to the endTime of the negative invoice, excluding invoices in group 1 and group 2.

The system will then sort the invoices in each group based on the following criteria:

  • If targetInvoicePriority is set to byAmount, add invoices where the absolute amount (not the remainingAmount) exactly matches the remainingAmount of the negative invoice, and sort by [remainingAmount, startTime, generateTime, locator]. Then add the remaining invoices sorted by the same keys.

  • If targetInvoicePriority is set to smallestFirst, sort invoices by [remainingAmount, startTime, generateTime, locator].

  • If targetInvoicePriority is set to earliestFirst, sort invoices by [startTime, generateTime, locator].

The system will then examine each invoice in order, beginning with group 1, then group 2, then finally group 3, selecting invoices that can be fully or partially paid until the negative invoice amount is exhausted or the system runs out of invoices to process.

The system will then process credit distributions based on the following logic:

  • Create a draft CreditDistribution with an amount equal to the minimum of invoiceCreditBalance and the sum of the remaining amounts for the invoices. Only targets that can consume credit will be included in the distribution. If yieldExcessToCreditBalance is set to true, the full invoiceCreditBalance will be included in the distribution.

  • Execute the distribution.

  • Continue to create distributions until distribution is complete.

If credit remains, the system will execute the following logic:

  • If yieldExcessToCreditBalance is set to true, keep the remaining credit in the credit balance for the account.

  • Otherwise, keep the remaining credit in the negative invoice. The negative invoice will be partially settled.

If no eligible open invoices are found, the full invoiceCreditBalance will be added to the credit balance for the account.

Note

The system does not currently support settling negative invoices by a specific amount. Settled negative invoices cannot be unsettled, but the associated CreditDistribution can be reversed.

Reversal

Any CreditDistribution that is created as a result of a negative invoice can be reversed, which will unsettle any non-negative invoiceItems and invoices. The amount will be added to the invoiceCreditBalance, which can be used later to target a different set of non-negative invoices using another CreditDistribution.

API Endpoints

The Settle Negative Invoice API endpoint can be used to manually settle negative invoices. The invoice state cannot be settled, and the remainingAmount must be negative.

The Fetch Debits for an Invoice API endpoint can be used to fetch all debits associated with a negative invoice.

See Also