Product Versioning - Policy Upgrade


See the Product Versioning feature guide for a general overview of the Product Versioning feature.


When a policy is created, it is associated with a specific product version which governs its algorithms, data structure, and document templates. This feature allows you to change the version associated with a policy. For example, if you update your products with new disclosure documents, you can choose which policies to associate with the new version so that they will use those document templates when creating new policy transactions.


The system will check to make sure the policy’s data structure is compatible with the target product version. If there are mismatches, such as required fields that exist in the configuration but don’t exist in the policy data, the transaction will fail.

Upon a successful upgrade operation, the system will emit a policy.upgrade event to the Event Stream.

If the operation does not succeed, the system will respond with a list of the validation errors that failed when trying to map the policy data to the new product version.


Validation checks will be performed when attempting to upgrade a policy. The validation will fail if any of the following are true:

  • There are required fields in the target configuration which are not present in the policy’s data

  • There are field names in the policy’s data which are not present in the target configuration

  • Any data fields’ types are not compatible with those in the target configuration

  • The policy has exposure names or exposures have peril names that don’t exist in the target configuration

  • The policy currently is lapsed with a legacy cancellation and the target configuration enables the current cancellation process


For the above checks, the policy’s data is presumed to be contained in unreplaced characteristics objects. The system will ignore replaced characteristics.

The following items are not validated, so caution should be taken when these are different in the target product definition:

  • Liquid Templates

  • Liquid calculation fields (taxes, fees, premium reports, etc)

  • Plugin scripts

  • Premium Report configurations

  • Policyholder configurations

  • Claim and Subclaim configurations

  • Grace period, cancellation, and reinstatement configurations

Contact Socotra support if you have any questions about the safety of an upgrade operation.


Upgrade a policy's product version
PATCH /policy/{policyLocator}/upgrade
newConfigVersion integer
policyLocator string
newConfigVersion integer
oldConfigVersion integer