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.


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


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

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