Changing policies

A policy change is a policy transaction that modifies a policy period. The most common reasons for a policy change are:

  • The policyholder wishes to add or remove coverages
  • The policyholder wishes to modify the scope of existing coverages, such as raising or lowering a deductible.

For more information, see Application Guide.

Use the following endpoint to change a policy through Cloud API:

  • POST /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/policy-changes

Fields for policy changes

The only required field is modificationDate, which is a string in the format YYYY-MM-DD.

Policy changes commonly include charges. The new charges are sliced and added to invoices. Charges can be added using the charges field, which contains an array of charge objects. Each charge object must have the following fields:

  • amount - The amount of the charge, as an object with amount and currency fields.
  • chargePattern - An object containing the id of the charge pattern of the charge.

A policy change charge can be positive or negative. For example, when coverage is added to a policy, a positive charge is added. When coverage is removed from a policy, a negative charge is added to cancel out the existing charge.

Example policy change request

Consider a personal auto policy that has a $1400 coverage on a single vehicle. The policyholder sells that vehicle and buys a different vehicle for which there will be a $1200 coverage. The difference in the coverage costs is calculated by the policy administration system and sent over as a single charge for -$200. The request would look like this:

Command

POST /billing/v1/accounts/bc:101/policies/bc:12492/policy-periods/bc:12493/policy-changes

Request body

{
    "data": {
        "attributes": {
            "modificationDate": "2025-07-06",
            "charges": [
                {
                    "amount": {
                        "amount": "-200",
                        "currency": "USD"
                    },
                    "chargePattern": {
                        "id": "default_data:1"
                    }
                }
            ]
        }
    }
}

If the request is successfully executed, a 201 response is returned along with the object capturing the policy change information.

As a result of the policy change, the new charge is added to the policy. The new charge is sliced into invoice items and placed onto the invoices that have not been billed. The original charge and its invoice items are not modified.