Rewriting policies

A rewrite is a policy transaction that creates a new policy period based on an existing policy period. In general, policy rewrites are used when a policy must be changed significantly.

Policy rewrites are flexible policy transactions. When executed using Cloud API, they can do the following:
  • Create a new policy period based on a canceled policy when there is a gap in coverage
  • Redo a policy with incorrect data entered
For more information about how BillingCenter handles rewrites, see the Application Guide.

Policy rewrite behaviors

When a policy is rewritten, BillingCenter populates the rewritten policy period with data from the existing policy period. Additional data can be provided to overwrite data on the existing policy period.

Note the following behaviors:
  • The charges on the existing policy period are not copied over to the rewritten policy period. Any charges must be included in the rewrite request.
  • Executing a rewrite does not change the status of the existing policy period. Existing policy periods are not canceled when they are rewritten.
  • If no effective and expiration dates are specified, the rewrite is scheduled to take effect on the expiration date of the existing policy period.
  • Whenever a policy is rewritten, it is rewritten to the same account. This applies even if a different account is specified in the endpoint path. Rewriting policies to new accounts is not currently supported through Cloud API.

Rewrite a policy in Cloud API

Use the following endpoint to rewrite a policy:
  • POST /billing/v1/accounts/{accountId}/rewrites

The only required field for a policy rewrite is priorPolicyPeriod. The following call is an example of a minimal policy rewrite:

Command
POST billing/v1/accounts/bc:131/rewrites
Request body
{
    "data": {
        "attributes": {
            "priorPolicyPeriod": {
                "id": "bc:132"        
            }
        }
    }
}
This request creates a new policy period using the existing data of policy period bc:132. The new policy period has the following attributes:
  • The policy period is numbered as if it were a renewal. It has the same number as the original policy with an incremented term number, such as "TestPolicy-2".
  • The policy period's effective date is set to the original policy's expiration date.
  • The policy period has no charges, because no charges were specified in the request body.

Other rewrite details

When rewriting a policy, you can include optional fields such as:
  • charges - The charges on the new policy period, as an array of charge objects
  • depositRequirement - The deposit requirement for the new policy period, as a monetary amount
  • description - A description of the new policy period, as a string
  • effectiveDate and expirationDate - The effective and expiration dates of the new policy period, as strings in the format YYYY-MM-DD
  • offerNumber - The offer number for the new policy period, as a string
  • paymentPlan - The new payment plan for the rewritten policy, as a simple reference
  • primaryNamedInsuredContact - The primary contact for the new policy period
  • producerCodesAndRoles - An array of producer codes and their roles on the new policy period
Note: As of this release, the policy and policyPeriod fields are read only and cannot be specified in rewrites.

When these fields are specified in rewrites, the provided data overwrites the data copied from the prior policy period.