Payment Shortfall Handling

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

Shortfall tolerances are configured in Shortfall Tolerance Plans, and each Socotra Account 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:

{
  "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.

Note

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

Plan Selection

When a plan is to be identified for an account, the system will check the shortfallTolerancePlanName on the account. 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

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 specifiedd 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 shortfall credit's locator will be stored in the payment's shortfallCreditLocators array.

The shortfall credits themselves (not just the locators) for a payment can be retrieved with the List Shortfall Credits API endpoint.

Each shortfall credit will be a credit of type shortfallWriteoff.

Note

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.

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.)