Renewing policies

A renewal is a policy transaction that creates a new policy period from an existing one. Typically, this occurs when the existing policy period is approaching its expiration date. When a policy is renewed, most information from the prior policy period is copied to the new policy period.

There are two types of renewals in BillingCenter.

  • Renewal - This is a renewal for a policy that is already known to BillingCenter.
  • New renewal - This is a renewal for a policy that is known to a legacy billing system but is new to BillingCenter.

For more information on renewals in BillingCenter, see the Application Guide.

Create both renewals and new renewals using the following endpoint:

  • POST /billing/v1/accounts/{accountId}/renewals

The required fields vary based on whether it is a renewal or a new renewal.

Renewing an existing policy period

Typically, renewals are created when there is a known policy with an existing policy period in BillingCenter. A renewal creates a new policy period while maintaining some or all of the prior policy period data.

There is one required field when creating a renewal:

  • priorPolicyPeriod - A reference to the ID of the existing policy period. The prior policy period must be owned by the account specified in the endpoint path.

Command 

POST /billing/v1/accounts/bc:128/renewals

Request body 

{
  "data": {
    "attributes": {
      "priorPolicyPeriod": {
        "id": "bc:336615"
      }
    }
  }
}

Specifying renewal information

When renewing a policy, you can include optional fields to modify the newly created policy period.

Some fields are copied over automatically from the original policy period, whereas some are not.

Field Description Copied from original policy period?
charges The charges on the new policy period, as an array of charge objects. No
depositRequirement The deposit requirement for the new policy period, as a monetaryAmount object. No
description A description of the renewal, as a string. No
effectiveDate and expirationDate The effective and expiration dates of the new policy period, as strings in the format YYYY-MM-DD. By default, the effective date is set to the day after the prior policy period closes, and the expiration date is one year later. No
offerNumber The offer number for the new policy period, as a string. No
paymentPlan The new payment plan for the renewed policy, as a simple reference. Yes
primaryNamedInsuredContact The primary contact for the new policy period. Yes
producerCodesAndRoles An array of producer codes and their roles on the new policy period. Yes

Example: Create a renewal for an existing policy period

Suppose that a policy period bc:328 on account bc:128 is renewed. For the new policy period, the premium is $1250. The payment plan is also changed.

Command 

POST /billing/v1/accounts/bc:128/renewals

Request body 

{
  "data": {
    "attributes": {
      "priorPolicyPeriod": {
        "id": "bc:328"
      },
      "paymentPlan": {
        "id": "bc:SY5CiSGOgl9RZhs0Z8rP7"
      },
      "charges": [
        {
          "amount": {
            "amount": "1250.00",
            "currency": "USD"
          },
          "chargePattern": {
            "id": "default_data:1"
          }
        }
      ]
    }
  }
}

The response object contains information on the charges, the policy, the renewal policy period, and the prior policy period.

Creating new renewals

A new renewal is created when BillingCenter receives a renewal billing instruction that is not associated with an existing policy or policy period. When BillingCenter receives a new renewal, it creates a new policy and policy period. Accordingly, a POST request for a new renewal must include the necessary information to create the new policy and policy period.

When creating a new renewal through Cloud API, the account must already exist in BillingCenter. The account ID is included in the endpoint path.

Required fields

The fields required for new renewals are the same as the fields required for issuing policies.

  • paymentPlan - A simple reference specifying the policy’s payment plan

  • policy - An object containing optional information about the policy. Can be empty.

  • policyPeriod - An object containing information on the policy period. Requires the following fields:

    • effectiveDate - The effective date of the new renewal policy period.

    • expirationDate - The expiration date of the new renewal policy period.

    • policyNumber - The policy number of the new policy.

Note: You cannot specify a priorPolicyPeriod field for new renewals. BillingCenter throws an error if both priorPolicyPeriod and policyPeriod are included in the request body.

Example: Create a new renewal

Suppose that a policy in a legacy billing system is renewed, and the billing details must be sent to BillingCenter. The account bc:194 already exists in BillingCenter, but the policy does not.

The request contains the following information:

Command 

POST /billing/v1/accounts/bc:194/renewals

Request body 

{
  "data": {
    "attributes": {
      "charges": [
        {
          "amount": {
            "amount": "1200",
            "currency": "USD"
          },
          "chargePattern": {
            "id": "default_data:1",
            "displayName": "Premium"
          }
        }
      ],
      "paymentPlan": {
        "id": "bc:SEGIMFL47eoelzL4W3EvK"
      },
      "policy": {},
      "policyPeriod": {
        "effectiveDate": "2025-08-01",
        "expirationDate": "2026-08-01",
        "policyNumber": "bs:392-legacy"
      }
    }
  }
}

The response object contains information on the charges, the policy, the renewal policy period, and the prior policy period.