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.

Preview a policy rewrite

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

  • POST /billing/v1/accounts/{accountId}/rewrite-preview

This endpoint functions the same as the policy rewrite 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 rewrite.

This endpoint accepts exactly the same request body as the policy rewrite 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 rewrite. 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)