Canceling policies

A cancellation is a policy transaction that ends a policy before its expiration date. The policy can be canceled by either the insured or the insurer. For example, the insurer might cancel the policy because of non-payment, or the insured might cancel the policy in order to work with a different insurer.

From an application perspective, the cancellation is initiated by the PAS. The PAS sends information about the policy cancellation to BillingCenter, typically consisting of a cancellation billing request and an array of charges.
  • The billing request can contain information about the cancellation, such as cancellation date, the cancellation reason, the cancellation type, and special handling.
  • The charges are usually negative, and are meant to settle the existing amount that has not yet been paid on the policy.

When a policy is canceled, planned invoice items are typically moved onto a final invoice. If the payer has overpaid for the policy, the additional funds can be disbursed or applied to another policy. For more information, see The cancellation process.

For information on cancellations in general, see Cancellations.

Cancel a policy

Cancel a policy using the following endpoint:

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

The only required field on a cancellation is modificationDate. This is the date that the cancellation is effective, which is the Cancellation Date in the user interface. This date can come before or after BillingCenter receives the policy cancellation billing request from the PAS.

The following is an example of a minimal cancellation:

Command
POST /billing/v1/accounts/bc:SSwoYVe/policies/bc:SjuMqx4/policy-periods/bc:SKfAeaM/cancellations
Request body
{
    "data": {
        "attributes": {
            "modificationDate": "2024-02-15"
        }
    }
}
By default, this example causes the following updates on the policy:
  • The policy period’s Cancellation Status is set to Canceled, and the Cancellation Date is set to 2024-02-15
  • The remaining amount that is due on the policy, if any, is placed onto the next planned invoice
  • Any invoices following the next planned invoice are deleted

Note that this request does not include any charges, so the entire remainder of the premium must be paid by the insured.

Additional fields and behaviors

When canceling a policy, you can specify fields which update the policy period and affect the behavior of the cancellation. Some fields in the request are specific to the cancellation billing instruction (such as holdUnbilledPremiumCharges), and other fields are on the policy period (such as effectiveDate and expirationDate). These fields are modified on the existing policy period when included in the request.

Note the behavior of the following optional fields:

Field Data type Note
charges Array of charge objects It is not necessary to send any charges when canceling a policy through Cloud API. If no charges are sent, the entire amount remaining on the policy is collapsed onto the final invoice. These charge objects have the same required fields as the charges for Issuing policies
cancellationType Typekey reference There are three codes in the base configuration: flat, prorata, and shortrate. When specified as flat, BillingCenter releases any holds on all charges on the policy period and does not create any new holds. prorata and shortrate are descriptive and do not affect cancellation behavior.
depositRequirement Monetary amount object The collateral requirement created by the cancellation.
holdUnbilledPremiumCharges Boolean If true, BillingCenter places charge holds on unbilled premium charges on the target policy. The default is false. If cancellationType is flat, this field is always treated as false, even if a value of true is sent.
primaryNamedInsuredContact Contact object Creates a new primary contact on the policy period. Has two required fields: contactSubtype and lastName (if a person) or companyName (if a company).
specialHandling Typekey reference Defines if billing is handled differently for the cancellation billing instruction. There are several options, but typically the only code that makes business sense for a cancellation is holdforauditall. This code means that BillingCenter places a charge hold on all unbilled items, including the charge that is sent with the cancellation. Holds are only placed if the cancellation type is not flat.

Response

The response contains the cancellation billing instruction and the updated policy period, reflecting any changes made to it during cancellation.