# Delinquency Events



Overview [#overview]

In addition to the built-in delinquency lapse event, you can add any number of custom events for delinquencies. This is done by adding <ApiLink name="DelinquencyEventConfiguration">delinquency events</ApiLink> to the <ApiLink name="DelinquencyPlanRef">delinquency plan</ApiLink>.

Delinquency events are configurable events that are based on the delinquency workflow, based on offsets from either the start or end of the grace period for the delinquency.

Any number of named event types can be added to a delinquency configuration. Each event fires a plugin.

Delinquency events are useful for things like:

* Notifying affected parties on the policy, such as additional named insureds
* Notifying mortgagees
* Triggering external generation of documents, such as a Notice of Intent to Cancel or a billing dunning notice.
* Creating manual activities for review
* Adding additional custom logic

<Callout>
  Future releases will support built-in document generation and activity creation.
</Callout>

Configuration [#configuration]

Events are added to <ApiLink name="DelinquencyPlanRef">delinquency plans</ApiLink>, with a named set of <ApiLink name="DelinquencyEventConfiguration">event definitions</ApiLink>. Each event definition has an `offsetBasis` and an `offsetDays` property.

If the delinquency is still unsettled, then the event will fire using the offset basis (either the `gracePeriodStart` or `gracePeriodEnd`), and adding the offset days value. Negative offsets are possible, which cause the event to fire before the basis time. For example, to fire an event three days before the end of the grace period, use `gracePeriodEnd` for `offsetBasis` and `-3` for `offsetDays`.

<Callout type="warn">
  The `delinquencyCreation` offset basis will be removed; use `gracePeriodStart` instead.
</Callout>

When a delinquency is created, its `configuredDelinquencyEvents` property will contain information about how events are configured for that delinquency plan. These may differ from the actual `delinquencyEvents` if they are modified in the delinquency pre-commit plugin or by using the API.

Operation [#operation]

When the delinquency is created, usually the grace period will start immediately and delinquency events will be created at that time. If there is a [delinquency hold](/features/billing/billing-holds) on an account when it becomes past due, events will not be created because the delinquency will remain in `preGrace` state. When the hold is released, then grace will start and events will then be created.

If a hold is placed on a delinquent account, the delinquency will revert to `preGrace` state, but any existing events will remain in place and trigger as scheduled. These events can be adjusted as needed based on business requirements. The transition back to grace when the hold is released will not update events or create new ones.

When the delinquency event fires, the delinquency event plugin fires, and any needed custom logic can be added to that plugin.

To interact with events directly, including direct update of trigger times, use the <ApiLink name="fetchDelinquencyEvents" /> and <ApiLink name="updateDelinquencyEvent" /> endpoints.

<Callout>
  If the delinquency's `graceEndsAt` property is changed, this will not change the time when custom events based on lapse will fire. These can be updated manually with the <ApiLink name="updateDelinquencyEvent" /> endpoint.
</Callout>

See Also [#see-also]

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