Cancellations and Reinstatements

Note

This topic is about the latest version of Socotra’s support for cancellation and reinstatement operations. It takes the place of existing Lapse, Reinstatement, and Cancellation functionality which is in legacy status. Existing Grace Period functionality has not significantly changed.

The older Legacy Cancellations and Withdrawals and Legacy Lapsing and Reinstatement functionality will be deprecated and removed in the future.

Warning

If existing policies using Legacy Lapsing and Reinstatement have lapsed they cannot be reinstated with the newer reinstatement process. Reinstate all such policies before enabling this feature.

Overview

Cancellation and Reinstatement in Socotra are managed by the creation and lifecycle of cancellation and reinstatement objects.

The basic lifecycle for cancellations and reinstatements looks like this:

Cancellations can be created either manually, through the UI or API, or automatically, based on the expiration of a grace period.

When a cancellation object is issued, its policy becomes cancelled as of the effectiveTimestamp of the cancellation. A reinstatement object can be created as needed (which will remain associated with its specific cancellation instance) and when that reinstatement is issued, the policy will be brought back on risk as of the effectiveTimestamp of the reinstatement.

Before issuance, both cancellation and reinstatement objects can be in draft state, which will allow for changes before the data for the transaction is locked in. In addition, reinstatement provides for an accepted state, which will calculate and lock in invoices. The first invoice in this reinstatement series can be used to determine whether the reinstatement should be issued.

A draft cancellation that is no longer needed can be rescinded, and it will no longer be eligible for issuance.

Cancellation Types

You can configure multiple cancellation types (or, “names”), and choose any of these for executing a cancellation. Each name can be associated with a different set of documents to be rendered on the cancellation issue and reinstatement accept events.

Note

If there are large numbers of cancellations, the Cancellation Categories feature can help identify the correct type for different business scenarios. See the feature guide for details.

Cancellation Creation

Cancellations can be created with the create cancellation endpoint, and if they are still draft state can then be updated or rescinded.

If the issue property of the CancellationRequest is true, the cancellation will move to issued state immediately.

The cancellation object also has an optional cancellationComments property which can be used for free form text. The value of this property is available when rendering cancellation documents and is visible in the proration plugin. For technical integration, complex objects serialized to JSON can be stored as comments.

Note

The cancellationComments property is limited to 4096 characters.

When creating a cancellation, an HTTP 4xx error will be returned under any of these conditions:

The cancellation type is specified but not found
The requested effectiveTimestamp is outside the policy’s coverage time
If the policy is already cancelled as of the new cancellation effectiveTimestamp

Cancellation Issuance

The policy will become off-risk as of the cancellation effective time when the cancellation is issued.

An error will be returned if any of these are true:

The cancellation name is not found in the product’s configuration
The policy is already cancelled as of the new cancellation’s effective timestamp.
The requested effective timestamp is outside the policy’s coverage
The cancellation is not in draft state (i.e has already been issued, or has been rescinded)

Multiple Cancellations

It is possible for a policy to have more than one valid cancellation. For example, if a policy that originally ends on December 31 is cancelled as of December 15, a subsequent cancellation could have an effective date of December 1 and be legitimate. Each cancellation has the effect of truncating the following coverage as of a timestamp.

A cancellation cannot be created, updated, or issued if its effective date is later than an existing issued cancellation. In this case an HTTP 4xx error will be returned.

If there are multiple issued cancellations on a policy, only the one with the earliest effective date can have its reinstatement be accepted. This would mean we could reinstate the Dec 1 cancellation, which would then extend coverage to Dec 15. After this the Dec 15 cancellation could be reinstated to extend coverage back to Dec 31.

Reinstatement

Create a reinstatement for a cancellation by using the Create Reinstatement endpoint. To immediately issue the reinstatement, set the issue property of the ReinstatementCreateRequest to true, otherwise the reinstatement will be created in draft state and can be accepted and issued later.

When the reinstatement is accepted, its invoice will be issued. Usually you will want to wait for the reinstatement invoice to be paid, and then issue the reinstatement.

Reinstatement Deadlines

The reinstatement may include an optional reinstatementDeadlineTimestamp, after which the reinstatement may not be issued. If this property is not included, deadline will be calculated using the cancellation effective time plus the time period specified in defaultDeadlineDays property in the reinstatement section of the configuration in cancellations.json . If defaultDeadlineDays is also not specified, there will be no deadline for the reinstatement.

After the deadline passes, a non-issued reinstatement will take the state expired and cannot then be issued.

Note

The legacy version of lapsing and reinstatement has an option for reinstatementPeriodDays. This setting is not used for the current version of reinstatements.

Conflict Handling

Cancellation Conflicts

When a cancellation is being issued, it is not compatible with endorsements or renewals in quoted or accepted state. So, either the cancellation must remain unissued, or the conflicting endorsements and renewals must be invalidated. To control this, use the conflictHandling property of the cancellation. If it is set to block, then the cancellation issuance will fail if there are conflicts. If it is set to invalidate, then the other conflicting transactions will be automatically invalidated when the cancellation is issued. If no conflictHandling is specified, the default behavior is block.

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.

Reinstatement Conflicts

Reinstatement works in a similar way, except that:

Conflicts will be managed at the accepted stage of the reinstatement
While the reinstatement remains accepted, no endorsements or reinstatements may become quoted, accepted, or issued, and no new cancellations may become issued.

Also, if there is currently an accepted reinstatement:

A cancellation cannot become issued unless its conflictHandling property is set to invalidate, which would automatically invalidate the accepted reinstatement.
No other reinstatement for other cancellations on the policy can become quoted or accepted.

Reinstatement Invalidation

If an accepted reinstatement is no longer needed, it can be invalidated, and it will revert to draft state. It can then be updated and accepted again if desired.

Reinstatement with a Gap

The effectiveTimestamp of a reinstatement can come after the effectiveTimestamp of its cancellation; in this case the policy will be brought on-risk with a gap, with no coverage between the effective timestamps. In this case, the overall premium for the policy will be less than when it was originally issued.

Note

On reinstatement with a gap, prorated fees will be restored in full; the insured will not have a credit for the gap period.

Pricing

Socotra can ensure the total premium, technical premium, and commissions are the same after reinstatement as they were immediately before the associated cancellation. To enable this, set the property.reinstatement.constant.premium.enabled feature flag. This flag is set to true for new tenants but must be enabled for tenants created before October 2023. Enable this flag in config.json, for example:

{
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "features":
    { "property.reinstatement.constant.premium.enabled": true }
}

If the feature flag is set, on reinstatement, the algorithm for ensuring constant premium will be applied:

Upon reinstatement, for each peril being rated, Socotra will identity (1) the original characteristics object that was replaced, (2) the “pre-split” characteristics object created on the cancellation, and (3) the “post-split” object created on reinstatement. The (3) segment is the one that will be rated; (1) and (2) have been rated previously.
If the monthPremium amount is the same on (1) and (3), and there is no gap in coverage between (2) and (3), then constant premium should be enforced
Socotra will then set the premium for (3) to be equal to that for (1) minus (2), instead of using the normal calculation.
The process will then repeat for commissions and technical premium.

Documents

Any number of documents may be configured to be rendered when cancellations and reinstatements are issued, and can be defined separately for each cancellation type. See the Configuration section for details.

Configuration

To use this new version of cancellations, add the file cancellations.json to the policy folder in your configuration:

{
  "cancellationTypes": [
    {
      "name": "customer_request",
      "title": "Customer Request",
      "documents": [
        {
          "displayName": "Cancellation Details",
          "fileName": "customer_request_cancellation.pdf",
          "templateName": "customer_request_cancellation.template.liquid"
        },
        {
          "displayName": "Cancellation Disclosure",
          "fileName": "cancellation_disclosure.pdf",
          "templateName": "cancellation_disclosure.template.liquid"
        }
      ],
      "reinstatement":
      {
        "defaultDeadlineDays": 14,
        "documents": [
          {
            "displayName": "Reinstatement Details",
            "fileName": "customer_request_reinstatement.pdf",
            "templateName": "customer_request_reinstatement.template.liquid",
            "generatingEvent": "issue"
          }
        ]
      },
      "cancellationCategories": ["customer_request", "general"]
    }
  ]
}

Each named type in the cancellationTypes property includes document templates to be rendered on cancellation issuance and reinstatement acceptance. Reinstatements configurations also include a default deadline for reinstatements to be issued before they will become expired.

Note

See Policy Change Management for information about the generatingEvent property, which controls when documents are created for the reinstatement.

Document Templates

For document rendering the data object will be constructed with a data.policy object and a data.policyholder object. Cancellations will also include a data.cancellation property, and for reinstatements gracePeriod and reinstatement objects are included as well.

"data": {
  "policyholder": {...},
  "policy": {...},
  "cancellation": {...},
  "grace_period": {
    "locator": string
    "start_timestamp": long,
    "end_timestamp": long,
    "invoice": {...}
  },
  "lapse": {
    "locator": string,
    "lapse_timestamp": long,
    "reinstatement_period_end_timestamp": long,
    "created_timestamp": long
  },
  "reinstatement": {
    "locator": string,
    "current_status": string,
    "invoice": {...},
    "reinstatement_timestamp": long,
    "issued_timestamp": long,
    "created_timestamp": long
  }
}

`data.cancellation`

{
  "locator": string,
  "name": string,
  "title": string,
  "policyholder_locator": string,
  "state": string,
  "created_timestamp": long,
  "effective_timestamp": long,
  "policy_modification_locator": string,
  "conflict_handling": string,
  "issued_timestamp": long,
  "cancellation_category": long,
  "cancellation_comments": long,
  "invoice_locator": long,
  "price": {...}
}

Note

data.lapse is included only for Legacy Lapsing and Reinstatement.

The invoice objects above look like this:

"invoice": {
    "locator": string,
    "display_id": string,
    "created_timestamp": long,
    "current_status": string,
    "due_timestamp": string,
    "total_due": number,
    "total_due_currency": string
}

API Support

See Cancellations API and Reinstatements API for information about performing cancellation and reinstatement operations through the API.

Cancellations and Reinstatements

Overview

Cancellation Types

Cancellation Creation

Cancellation Issuance

Multiple Cancellations

Reinstatement

Reinstatement Deadlines

Conflict Handling

Cancellation Conflicts

Reinstatement Conflicts

Reinstatement Invalidation

Reinstatement with a Gap

Pricing

Documents

Configuration

Document Templates

data.cancellation

API Support

`data.cancellation`