Product Versioning


Product versioning is a system for ensuring that policy data and its associated configuration remain in sync. For example, you could choose to add or remove a non-optional field value from your policy definition; older policies may be inconsistent with this change, which could cause difficulties rendering the policy in the UI, or in extreme cases, transaction failure for that policy.

With product versioning, each policy will have a configVersion property which identifies which version of the configuration it was created with. In practice, this could look like this:

  1. Configuration 1 deployed

  2. Policy A created and issued. It is associated with configVersion 1.

  3. Configuration 2 deployed

  4. Policy B created and issued. It is associated with configVersion 2.

  5. Policy A is endorsed. The rules, schema, document templates, etc. used for the endorsement transaction will be those defined in configuration 1, even though it is not the most recent version.

With product versioning, it is safe to deploy new policy configurations whenever desired, without risk to already-existing data. It also ensures that the algorithms, tables, etc. that drive pricing calculations are not changed unless explicitly controlled.


You can determine the configuration version for a given policy by examining the configVersion property of the PolicyResponse object.


See the Deployments API guide for information about getting deployment history by version and retrieving the zip file for a given deployment version.


Production configuration deployment processes will vary based on whether product versioning is enabled or intended to be enabled. See the Deployment API Guide for details.

Versioned Elements

The following elements of policy configuration are versioned:

  • Schema (i.e. fieldValues and fieldGroups)

  • Rating rules (defined in <perilname>.premium.liquid)

  • Underwriting rules defined in underwriting.guidelines.liquid

  • Tables

  • Policy settings, as defined in policy.json, exposure.json, and <perilname>.json

  • Tax and Fee calculations, defined in policy.calculations.liquid, taxes.json, fees.json, and <taxName>.premium.liquid

  • Transaction definitions, such as in endorsements.json

  • Premium reporting settings and rating calculations

  • Document templates

  • Plugin controls for enabling plugins and setting the JavaScript path

Some configuration elements are not versioned, though they may be versioned in future releases:

  • Policyholders

  • Claims and subclaims

  • Payments

  • Plugin scripts

  • Test users

  • Policy reminders

  • Feature flags


Though plugin scripts are not versioned, the path to the script for each plugin is, because each of the path properties for plugins in policy.json are versioned.

Creating Policies with a Specific Version

Normally the latest configuration version is used when creating a new policy. Now, however, the policy create request allows you to specify which particular version to associate by setting the configVersion property.

Product Versioning “Repair”

To update older product versions that have been previously deployed, see the Product Versioning Repair feature topic.

Product Versioning “Upgrade”

To upgrade (or downgrade), the product version associated with a policy, see the Product Versioning Upgrade topic.

Premium Reporting

Most configuration elements are versioned according the policy’s configVersion. However, premium reports are versioned independently. For example, if a policy is on version 2 but the configuration for that product has been updated to version 3, new premium reports for that policy will be created with configuration 3. This makes it easier to update premium reports without the burden of repairing the older configuration.


Because new premium reports are always based on the latest config version, do not delete premium report definitions from configuration if they will be needed for new reports.