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.
- 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:
POST /billing/v1/accounts/bc:SSwoYVe/policies/bc:SjuMqx4/policy-periods/bc:SKfAeaM/cancellations
{
"data": {
"attributes": {
"modificationDate": "2024-02-15"
}
}
}
- 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.