Executing a policy change

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.

Preview a policy change

Cloud API allows you to preview the billing impact of a policy change by POSTing a policy change object using the following endpoint:

  • POST /accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/policy-change-preview

This endpoint functions the same as the policy change endpoint, except no data from the POST is persisted to the database. The endpoint returns an array of preview invoice items that reflect the potential policy change.

This endpoint accepts exactly the same request body as the policy change endpoint. The same fields are required.

The request returns a response object that includes an array of preview items. Preview items are data objects that represent invoice items that BillingCenter would create in the event of an actual policy change. Preview items are not persisted to the database, and only exist in the context of individual API calls.

Preview items include the following information:

  • The amount of the invoice item
  • The category of the charge
  • The payer account
  • The invoice stream
  • The type of invoice item (such as installment, one time, or down payment)