# Delinquency



Overview [#overview]

*Delinquency* is a process that includes a workflow to manage actions to be taken when the insured has one or more invoices that are past due, i.e. invoices that have a `dueTime` in the past and are not yet fully settled with [payments](/features/billing/payments) or applied [credits](/features/billing/credit-balances).

Delinquencies can be used to create policy *lapses*, which are policy cancellation transactions that are created and issued automatically based on configuration and plan settings.

Configuration [#configuration]

Delinquency is set up using configuration *Delinquency Plans*. When policy becomes delinquent, the system looks for the delinquency plan that governs that policy, and uses the settings on that plan to create and manage the delinquency. Each plan has the following settings:

* `gracePeriodDays`: An integer value that sets the timespan in days between the onset of the delinquency and the time at which the policy system will be signalled to cancel the policy.
* `lapseTransactionType`: The type of the transaction that will be created for the delinquency if it reaches the lapse time. This must be a policy transaction of category `cancellation`.
* `delinquencyLevel`: Either `policy` or `invoice`. If the setting is `policy`, then when other invoices for that policy become past due, they will be managed with the existing workflow. If the level is `invoice` then a new delinquency workflow will be spawned for each invoice.
* `advanceLapseTo`: The state to which the system should automatically advance the lapse transaction. If this is not `issued`, then the lapse will have to be manually issued for cancellation to be effective.
* `events`: A set of custom delinquency events that can be added to the delinquency workflow. See *Delinquency Events*, below.

Delinquency Onset [#delinquency-onset]

A policy becomes *Past Due* when any invoice which contains any invoice item for that policy reaches its `dueTime` without being fully settled. When that happens, the system will look for a delinquency plan, in this order:

* The `delinquencyPlanName` on the policy
* The `delinquencyPlanName` on the account
* The `defaultDelinquencyPlan` in configuration

If a delinquency plan is found, then a <ApiLink name="DelinquencyResponse">delinquency workflow</ApiLink> is created, and the delinquency workflow begins. Using the plan settings and past-due data, the delinquency will have the following settings established:

* The `accountLocator` for the involved insured account
* The `graceStartedAt` time, which is usually the time the delinquency is created
* The `graceEndsAt` time, when the policy will lapse, based on the `gracePeriodDays` setting
* `references`, which describe the policies and invoices that are involved in the delinquency.
* `settings` are stored for reference: `advanceLapseTo`, `gracePeriodDays`, `lapseTransactionType`, and `delinquencyLevel`

<Callout>
  Before a lapse occurs, you may change the lapse time using the <ApiLink name="updateDelinquency" /> endpoint.
</Callout>

Lapse [#lapse]

When the `graceEndsAt` time arrives for an unsettled delinquency, the system will create a cancellation transaction if the `lapseTransactionType` is set on the delinquency plan. This transaction will automatically advance to the state given on the `advanceLapseTo` setting, and after that the cancellation may be managed manually if it is not yet `issued`.

If not changed by the client, the lapse will become at the end of the day calculated using the `gracePeriodDays` setting.

<Callout>
  In addition to the lapse event, you can add custom events. See the [Delinquency Events Feature Guide](/features/billing/delinquency-events) for details.
</Callout>

See Also [#see-also]

* [Delinquency Events Feature Guide](/features/billing/delinquency-events)
* [Delinquency API](/api/billing/delinquency)