Grace Periods and Policy Lapse

The Grace Period mechanism is a way to automatically create cancellations when invoices remain unpaid for a specified duration.

Socotra can be configured to automatically create grace periods if a lapse property containing a gracePeriodDays property is set in policy.json for the product.

If a policy has been issued, and an invoice for the policy becomes past due, the grace period will be created.

The grace period will become settled when either:

All past due invoices on the policy are paid

The end of the grace period passes

After a grace period reaches its endTimestamp, the cancellation named lapse will be automatically created and issued, effective immediately.

If no cancellation with the name lapse was originally created in configuration, one will be automatically generated.

Note

Lapses are cancellations that always use the invalidate strategy for conflictHandling, meaning that any non-issued endorsements or renewals will be invalidated upon lapse. There is no provision for blocking a lapse due to the existence of quoted or accepted endorsements or renewals.

Note

No lapse cancellation will be created if the policy has already expired or has another cancellation effective in the past.

Documents

A document will be rendered for the grace period if a template called gracePeriod.template.liquid has been included in the product configuration.

In the document template file the data object will be constructed with a data.policy object, a data.policyholder object, and a grace_period object. Note that gross premium and similar numbers on the data.policy object are the totals across all coverage terms.

"data": {
    "policyholder": {...},
    "policy": {...},
    "grace_period": {
        "locator": string
        "start_timestamp": long,
        "end_timestamp": long,
        "invoice": {
            "locator": string,
            "display_id": string,
            "total_due": number,
            "total_due_currency": string,
            "due_timestamp": long,
            "created_timestamp": long
        }
    }
}

Grace Expiration and Lapse Options

The duration of a grace period is set in policy.json. For example:

{
  // several omitted properties
  "lapse": {
     "gracePeriodDays": 30,
     "reinstatementPeriodDays": 90
  }
}

After a non-credit invoice reaches its due date without being settled, the grace period will be created and its endTimestamp will be set by adding the gracePeriodDays value to the invoice dueTimestamp. Before the grace period expires, the endTimestamp can be updated with the Update Grace Period endpoint.

The effective timestamp of a lapse is normally the same as the expiration time of the grace period, though it is possible to set a different time. To do this, update the grace period with the Update Grace Period endpoint and set the cancelEffectiveTimestamp property:

Tip

If you want to have the policy lapse immediately with no grace period when an invoice becomes past due, set the gracePeriodDays property to 0. If you want the policy to never enter grace or lapse, then remove the lapse property entirely from policy.json.

Update a Grace Period¶

PATCH /gracePeriod/{gracePeriodLocator}

Request:

Name	Position	Type	Required
gracePeriodLocator	path	string	required
gracePeriodUpdateRequest	body	GracePeriodUpdateRequest	required

Response: GracePeriodResponse

GracePeriodUpdateRequest¶

optional
endTimestamp timestamp
cancelEffectiveTimestamp timestamp
resetCancelEffectiveTimestamp boolean

Note

After being set, it not possible to reset the cancelEffectiveTimestamp back to null. To get the same result as if it was null, set the timestamp to be the same as the endTimestamp for the grace period.