# Excess Credits



Overview [#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 [#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:

<ApiSchema name="ExcessCreditPlanRef" />

The `disbursementType` property should be set to one of the [disbursement types](/features/billing/disbursements#disbursementConfig) 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 [#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 <ApiLink name="DisbursementResponse">disbursement entity</ApiLink>.

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.

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

Automatic Disbursement Handling [#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.

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

<span id="NegativeInvoiceProcessing" />

Negative Invoice Processing [#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 [#configuration-1]

Negative invoice handling behavior can be configured through the <ApiLink name="NegativeInvoiceHandlingRef" /> configuration object within each <ApiLink name="ExcessCreditPlanRef" /> configuration object for an account.

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

```json
{
	"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 [#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](/api/billing/credit-distribution) 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.

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

Reversal [#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 [#api-endpoints]

The <ApiLink name="settleNegativeOrZeroInvoice" /> API endpoint can be used to manually settle negative invoices. The invoice `state` cannot be `settled`, and the `remainingAmount` must be negative.

The <ApiLink name="fetchDebitsForAnInvoice" /> API endpoint can be used to fetch all debits associated with a negative invoice.

See Also [#see-also]

* [Disbursements](/features/billing/disbursements)
* [Credit Balances](/features/billing/credit-balances)
* [Credits from Policy Transactions and Billing Changes](/features/billing/credits-from-policy-transactions)
* [Disbursements API](/api/billing/disbursements)
* [Invoices API](/api/billing/invoices)
* [Credit Distribution API](/api/billing/credit-distribution)


## API Reference

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