# Payment Shortfall Handling



Overview [#overview]

On occasion, customers will make payments towards invoices with amounts that are near to, but slightly less than, the amount needed to settle an invoice. You can use *Shortfall Credits* to automatically settle these invoices when the shortfall amount is less than what would justify the effort of collecting the difference.

Configuration and Plans [#configuration-and-plans]

Shortfall tolerances are configured in <ApiLink name="ShortfallTolerancePlanRef">Shortfall Tolerance Plans</ApiLink>, and each <ApiLink name="AccountResponse">Socotra Account</ApiLink> can be assigned a plan. For those accounts that aren't given a plan, each product configuration may specify a plan, and the default shortfall tolerance plan is configured at the tenant level.

The shortfall thresholds are specified in the `currencyTolerances` property of the plan. This property has type `map<string, number>`, and the key for each threshold is a string that specifies the currency, such as `USD` or `CAN`.

So the configuration might look something like this:

```json
{
  "shortfallTolerancePlans": {
    "basicPlan": {
      "USD": 1.00,
      "CAD": 1.50,
      "EUR": 0.80
    },
    "nonStandardPlan": {
      "USD": 0.20,
      "CAD": 0.30,
      "EUR": 0.15
  }
}
```

In this case, customers assigned the `basicPlan` are treated more leniently than those assigned the `nonStandardPlan`.

<Callout>
  If a shortfall plan does not contain the currency for a given invoice, then shortfall credits will not be generated for that invoice.
</Callout>

Plan Selection [#plan-selection]

When a plan is to be identified for an account, the system will check the `shortfallTolerancePlanName` on the <ApiLink name="AccountResponse">account</ApiLink>. If there is none, it will then check each product being billed on the invoice being processed to check for a `defaultShortfallTolerancePlan`. If none exist, then the `defaultShortfallTolerancePlan` at the tenant level will be used. If no plans are found, or the shortfall tolerance for the given invoice's currency is zero, then shortfall processing will not be performed.

Application [#application]

When a payment is made on an invoice but the invoice remains unsettled, the system will check to see if all the following are true:

* There is a shortfall tolerance plan available to the account (either specified directly on the account, or on the product or tenant)
* The currency for the invoice is represented on the shortfall plan
* The remaining unsettled amount is less than or equal to the specified tolerance

If all the conditions are met, then the system will generate a shortfall credit in the amount of the shortfall, and apply the credit to the invoice. The invoice will then be settled. If the payment's amount is less than the unsettled amount of the invoice minus the shortfall plan threshold, then no credit will be generated.

The new <ApiLink name="ShortfallCreditResponse">shortfall credit's</ApiLink> locator will be stored in the <ApiLink name="PaymentResponse">payment's</ApiLink> `shortfallCreditLocators` array.

The shortfall credits themselves (not just the locators) for a payment can be retrieved with the <ApiLink name="listShortfallCredits" /> API endpoint.

Each shortfall credit will be a credit of type `shortfallWriteoff`.

<Callout>
  If more than one invoice is targeted by the payment, the thresholds are applied *per invoice*. This means the total shortfall credit amount may exceed the specified threshold for these payments. This is true for typical payments that target more than one invoice within a single account, and also for [Aggregate Payments](/features/billing/payments#aggregate-payments).
</Callout>

Payment Reversal [#payment-reversal]

If a payment that created a shortfall credit is reversed, then that credit will be reversed as well, and the unsettled amount on the invoice will revert to the amount before the payment was made (assuming no other payments or credits have been applied or reversed.)

See Also [#see-also]

* [Payments Feature Guide](/features/billing/payments)
* [Payments API](/api/billing/payments)