Endorsements

Endorsements are used to change policy, exposure, and peril details, with options for repricing the endorsed period of the policy.

Endorsement objects contain instructions for how the policy should change. These changes can include:

  • Updating field values at the policy, exposure, and peril levels

  • Adding and ending exposures

  • Adding and ending perils

  • Optional repricing of the endorsed period

  • Changes to the end timestamp of the policy (see note)

Note

The end timestamp of the policy cannot be changed. A feature flag is available to enable extension or reduction via endorsement, but we recommend that it be avoided, preferring renewal or cancel-rewrite instead. See Enable an Endorsement to Change a Policy End Timestamp for more information.

Changes made in an endorsement are carried forward until the end of the policy.

See the Endorsements API topic for information about how to implement this feature.

Note

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

Repricing

Repricing runs the premium, tax and commissions calculations and applies them to the endorsed period of the policy. Premium is allocated to periods before the endorsed period of the policy on a pro-rata basis. Future invoices are unaffected if the endorsement does not result in a reprice.

In configuration, the reprice setting takes one of four values: never, always, all or input. If omitted, reprice defaults to never.

  • The input option requires that the user or API call specify what to do and otherwise returns an error. In the API, this is done by passing in true or false on the reprice parameter.

  • The always option means that the period after the endorsement will always be repriced using the premium calculation logic if its field values have changed.

  • The all option means that the period after the endorsement will be repriced even if none of its data has changed.

  • The never option means that the period will be prorated and pricing logic will not be invoked.

Note

If, after the pricing is done, the premium rate is unchanged, the premium amount will be set on the repriced segment to ensure that, for that peril, the total premium before and after the endorsement is unchanged.

Endorsement Types

Multiple endorsement types may be created, and the user can choose from among them when endorsing. Each endorsement type can specify documents to be associated with a generatingEvent as described below.

Extensions and Reductions

Warning

The property.endorsement.update.policydate.enabled flag to enable extensions and reduction by endorsement is geared towards a subset of specific scenarios and policy configurations; we recommend using renewals or cancel-rewrite instead.

Please contact your Socotra representative for assistance determining the best approach for your product.

Enabling Extension and Reduction Endorsements

By default, extension/reduction endorsements – changes to the policy end timestamp – are not allowed, either in the application or by setting the newPolicyEndTimestamp property using an Endorsement API. To enable extension/reduction endorsements, you must first set the property.endorsement.update.policydate.enabled feature flag to true.

For example, add the property.endorsement.update.policydate.enabled flag to config.json and set it to true, as follows:

  {
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "features": {
          "property.endorsement.update.policydate.enabled": true
      }
  }

Extension and Reduction Endorsements (Only If Enabled)

By default, extensions and reduction endorsements are not allowed. This topic describes how these endorsements will behave, if the relevant feature flag has first been set.

The policy end can be changed along with any other changes in the endorsement (only if extension/reduction endorsements are enabled). Updated policy end times must be at midnight in the tenant’s timezone. The change to the end will be reflected in the effectiveContractEndTimestamp in the PolicyResponse.

If the endorsement changes only the policy end time, the application will automatically set the effective time of the endorsement to the earlier of the old and new end times. The start time of the endorsement cannot be set in the application.

Policies are extended when the policy end is made later than before:

  • Any coverage active at the current end time of the policy will be extended

  • Extended coverage will be priced using the peril’s premium calculation

Policies are reduced when the policy end is made earlier than before:

  • All coverage will be terminated as of the new end time

  • Refunds will be prorated

Configuration

The file policy/endorsements.json specifies names for the endorsements that may be applied to a policy. If this file is empty or doesn’t exist, endorsements will be disabled for that product. Documents to be generated along with the endorsement are optionally specified here.

Example endorsements.json

{
  "endorsements": [
    {
      "name": "change.address",
      "displayName": "Change Address",
      "reprice": "always",
      "documents": [
        {
          "displayName": "Address Change",
          "fileName": "address_endt.pdf",
          "templateName": "address_endt.template.liquid",
          "generatingEvent": "accept"
        }
      ]
    },
    {
      "name": "change.beneficiary",
      "displayName": "Change Beneficiary"
    }
  ]
}

Note

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

Feature Flags

The following flags are available to customize invoicing behavior related to endorsements:

  • property.endorsement.nonrated.retain.invoices: Prevents calls to the installments plugin for non-rated endorsements, alleviating the burden of writing installments plugin logic if you simply want to retain the existing invoice stream in such cases.

  • property.endorsement.zerodue.invoices.suppression.enabled: Suppresses any zero-due invoices that would be generated at endorsement acceptance or issuance.

  • property.endorsement.zerodue.installments.suppression.enabled: Suppresses corresponding invoice generation for any zero-due installments, including those in the future invoice stream.

  • property.endorsement.invoice.fees.suppression.enabled: Suppresses installment fees for non-rated endorsements. Note: this should only be used when property.endorsement.zerodue.invoices.suppression.enabled and property.endorsement.nonrated.retain.invoices are enabled as well.

Endorsement Documents

You may configure any number of documents to be generated with an endorsement. The same document template may be used for multiple endorsements, or each may have a dedicated template, as specified in the configuration.

These templates have access to the same data available to other Document Templates, as well as data.endorsement:

data.endorsement: {
  name: string,
  locator: locator,
  display_id: string,
  start_timestamp: timestamp, /* optional */
  issued_timestamp: timestamp,
  effective_contract_end_timestamp: EndorsedContractEndTimestamp,
  repriced: boolean,
  price: PolicyPriceChange,
  policy_updates: {
    locator: locator,
    display_id: string,
    all_exposures: map<ExposureName, [EndorsedExposure]>,
    updated_exposures: map<ExposureName, [EndorsedExposure]>,
    all_field_values: map<FieldName, [EndorsedFieldValue]>,
    updated_field_values: map<FieldName, [EndorsedFieldValue]>,
    all_field_groups: map<FieldName, [EndorsedFieldGroup]>,
    updated_field_groups: map<FieldName, [EndorsedFieldGroup]>
  }

  // Deprecated fields (use policy_updates instead of these)
  field_values: map<string, string[]>
  add_field_groups: [FieldGroupCreateRequest],
  update_field_groups: [FieldGroupUpdateRequest],
  remove_field_groups: [string],
  update_exposures: [ExposureUpdate]
}

EndorsementEffect: One of "unchanged", "added", "removed", or "updated"

EndorsedContractEndTimestamp: {
  endorsement_effect: EndorsementEffect,
  old_value: timestamp,
  new_value: timestamp
}

EndorsedFieldValue: {
  title: string,
  endorsement_effect: EndorsementEffect,
  old_value: string | [string],
  new_value: string | [string]
}

EndorsedFieldGroup: {
  locator: string,
  title: string,
  endorsement_effect: EndorsementEffect,
  all_field_values: map<FieldName, EndorsedFieldValue>,
  updated_field_values: map<FieldName, EndorsedFieldValue>
}

EndorsedExposure: {
  locator: locator,
  display_id: string,
  name: ExposureName,
  display_name: string,
  endorsement_effect: EndorsementEffect,
  all_perils: map<PerilName, [EndorsedPeril]>,
  updated_perils: map<PerilName, [EndorsedPeril]>,
  all_field_values: map<FieldName, EndorsedFieldValue>,
  updated_field_values: map<FieldName, EndorsedFieldValue>,
  all_field_groups: map<FieldName, [EndorsedFieldGroup]>,
  updated_field_groups: map<FieldName, [EndorsedFieldGroup]>
}

EndorsedPeril: {
  locator: locator,
  display_id: string,
  name: PerilName,
  display_name: string,
  endorsement_effect: EndorsementEffect,
  all_field_values: map<FieldName, EndorsedFieldValue>,
  updated_field_values: map<FieldName, EndorsedFieldValue>,
  all_field_groups: map<FieldName, [EndorsedFieldGroup]>,
  updated_field_groups: map<FieldName, [EndorsedFieldGroup]>
}

PolicyPriceChange: {
  new_total: number,
  new_gross_premium: number,
  new_gross_taxes: number,
  new_gross_fees: number,
  new_gross_commissions: number,
  total_change: number,
  gross_premium_change,
  gross_taxes_change: number,
  gross_fees_change: number,
  gross_commissions_change: number,
  exposure_prices: ExposurePriceChange,
  tax_groups: [PricedTax],
  fees: [PricedFee]
  commissions: [PricedCommission]
}

ExposurePriceChange: {
  locator: locator,
  name: string,
  new_gross_premium: number,
  new_gross_taxes: number,
  new_gross_commissions: number,
  gross_premium_change,
  gross_taxes_change: number,
  gross_commissions_change: number,
  peril_prices: [PerilPriceChange],
  tax_groups: [PricedTax],
  commissions: [PricedCommission]
}

PerilPriceChange: {
  locator: locator,
  name: string,
  new_gross_premium: number,
  new_gross_taxes: number,
  new_gross_commissions: number,
  gross_premium_change,
  gross_taxes_change: number,
  gross_commissions_change: number,
  peril_prices: [PerilPriceChange],
  taxes: [PricedTax],
  commissions: [PricedCommission]
}

PricedTax: {
  name: string,
  new_amount: number,
  change: number
}

PricedFee: {
  locator: locator,
  name: string,
  new_amount: number,
  amount_change: number
}

PricedCommission: {
  new_amount: number,
  amount_change: number,
  recipient: string
}