Cancellations and Reinstatements

Note

This is 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 deprected 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:

../_images/lifecycle.png

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 associtated with its specific canellation 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 avaialable 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 canellation 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.

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.

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.

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"
          }
        ]
      },
      "categories": ["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.

For document template 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, lapse, 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
    }
}

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.