Renewals

Socotra supports Renewals of arbitrary length. All policy and exposure details can be changed during renewal. Along with the extension of the policy, the policy itself, including its exposures and perils, can be changed much like in an endorsement.

See the Renewals API topic more details.

Note

Further important information about renewal lifecycle and pricing can be found in Policy Change Management.

Renewal Documents

You may configure any number of documents to be generated when a renewal is quoted or accepted. These templates have access to the same data available to other Document Templates, as well as data.renewal (see Data Object, below.)

Peril Handling on Renewal

When a policy is renewed, the perils that were active before the renewal are duplicated. This means that each peril object is contained within a single policy term. To associate perils across terms, use the renewalGroup property of the peril; it will remain the same from term to term.

Configuration

The file policy/renewals.json specifies one or more documents to be generated at the time of policy renewal. If this file is empty or doesn’t exist, no document will be generated during policy renewal.

Example renewals.json:

{
   "documents": [
     {
        "displayName": "Updated Policy Schedule",
        "fileName": "renewal_schedule.pdf",
        "templateName": "renewalSchedule.template.liquid",
        "generatingEvent": "accept"
     },
     {
        "displayName": "Renewal Email",
        "fileName": "renewal_email.html",
        "templateName": "renewalEmail.template.liquid",
        "type": "html",
        "generatingEvent": "quote"
     }
   ]
}

Notes

• Renewals can be processed on any issued policies, even if the term is expired.

• Any coverage active at the end of the policy is carried forward into the renewal term unless changed by the renewal.

• The policy’s effectiveContractEndTimestamp will be advanced to match the end of the new renewal term.

• The payment schedule for the renewal term will match that for the previous policy term, unless a new one is specified using the newPaymentScheduleName property of the renewal request.

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

Note

Installment fees are not visible in the planned invoices set for renewals that have not yet been issued.

Policy Calculations

Fees will be charged during a renewal, and the configuration file policy.calculations.liquid should take this into account. Note that gross premium and similar values on the data.policy object are the totals across all coverage terms.

For more details, see Fees.

Example policy.calculations.liquid that charges different fees for a renewal:

{% assign policy_char = data.policy.characteristics[0] %}

{% unless data.renewal %}
  {{ policy_char.gross_premium | times: 0.03 | add_fee: "transaction", "3% Transaction fee" }}
  {{ 10 | add_fee: "underwriting", "Underwriting fee" }}
{% else %}
  {{ 100 | add_fee: "transaction", "$100 Renewal fee" }}
{% endunless %}

Data Object

Renewals add the following data object, which is available for document rendering or premium calculations.

Note

The policy_updates field is not available in the rating calculation context, but is available for document generation.

data.renewal: {
  locator: locator,
  display_id: string,
  start_timestamp: long,
  issued_timestamp: long,
  effective_contract_end_timestamp: RenewedTimeValue,
  policy_updates: {
    all_exposures: map<ExposureName, [RenewedExposure]>,
    updated_exposures: map<ExposureName, [RenewedExposure]>,
    all_field_values: map<FieldName, RenewedFieldValue>,
    updated_field_values: map<FieldName, RenewedFieldValue>,
    all_field_groups: map<FieldName, [RenewedFieldGroup]>,
    updated_field_groups: map<FieldName, [RenewedFieldGroup]>
  }
}

RenewalEffect: Supported Transaction Values are "unchanged", "added", "removed", or "updated"

RenewedTimeValue: {
  renewal_effect: RenewalEffect,
  old_value: string or [string],
  new_value: string or [string]
}

RenewedFieldValue: {
  title: string,
  renewal_effect: RenewalEffect,
  old_value: string or [string],
  new_value: string or [string]
}

RenewedFieldGroup: {
  locator: string,
  title: string,
  renewal_effect: RenewalEffect,
  all_field_values: map<FieldName, RenewedFieldValue>,
  updated_field_values:: map<FieldName, RenewedFieldValue>
}

RenewedExposure: {
  locator: locator,
  display_id: string,
  name: ExposureName,
  display_name: string,
  renewal_effect: RenewalEffect,
  all_perils: map<PerilName, [RenewedPeril]>,
  updated_perils: map<PerilName, [RenewedPeril]>,
  all_field_values: map<FieldName, RenewedFieldValue>,
  updated_field_values: map<FieldName, RenewedFieldValue>,
  all_field_groups: map<FieldName, [RenewedFieldGroup]>,
  updated_field_groups: map<FieldName, [RenewedFieldGroup]>
}

RenewedPeril: {
  locator: locator,
  display_id: string,
  name: PerilName,
  display_name: string,
  renewal_effect: RenewalEffect,
  all_field_values: map<FieldName, RenewedFieldValue>,
  updated_field_values: map<FieldName, RenewedFieldValue>,
  all_field_groups: map<FieldName, [RenewedFieldGroup]>,
  updated_field_groups: map<FieldName, [RenewedFieldGroup]>
}