Policy audits

This topic introduces policy audits in BillingCenter and explains how audits are managed using Cloud API. You can use Cloud API to schedule, issue, or waive audits and manage audit processing in BillingCenter.

A policy audit is a process that recalculates the final premium for a policy after the policy term ends. Policy audits help ensure that the premium reflects the true exposure during the policy period. When a final audit is required, BillingCenter may hold unbilled charges until the audit is finished. BillingCenter can then bill the policy period payer for any outstanding amount, or execute a disbursement to settle a negative amount.

You can perform the following actions with audits in Cloud API:

  • Scheduling a policy period for final audit - A policy period can be scheduled as requiring a final audit when it is issued or at any point within or after its effective dates.
  • Issue an audit billing instruction - Audits are sent as billing instructions that can contain charges and other fields to update the policy.
  • Waiving audits - If an audit has been scheduled, you can mark that it no longer needs to be executed by waiving it.

Schedule a final audit

Before a final audit can be created, the policy period must be in the correct state. You can ensure that the policy is in the proper state by scheduling a final audit.

There are two ways to schedule a final audit for a policy period.
  1. Schedule the final audit when the policy is issued. Do this by setting the scheduleFinalAudit field to true when you issue a policy.
  2. Schedule a final audit using a separate API call after issuance, as described below.

Use the following endpoint to schedule a final audit for a policy period after the policy period has been issued:

  • POST /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/schedule-final-audit

Behavior for scheduling final audits

When you schedule a final audit, BillingCenter does the following:

  • Sets the closure status to "open locked." The "open locked" status is used to prevent the policy from being closed before the audit is complete. This value is set whether the policy period was previously open or closed.

The only required field in the request is modificationDate.

Example of scheduling a final audit

This example demonstrates scheduling a final audit for a policy period.

Command 
POST /billing/v1/accounts/bc:4322/policies/bc:100293/policy-periods/bc:100294/schedule-final-audit
Request body 
{
    "data": {
        "attributes": {
            "modificationDate": "2025-08-08"
        }
    }
}

As a result of this call, the policy period bc:100294 has a closureStatus of openlocked.

Issue an audit billing instruction

Audits are sent as billing instructions that can contain charges, contacts, and other fields which are used to update the policy.

Use the following endpoint to create an audit:

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

Audit fields

The only required field in the request is modificationDate. Otherwise, the request body can contain fields used to update the policy period, such as adding charges. The following table details the possible fields:

Field Data type Description
charges Array of charge objects These charge objects have the same required fields as the charges for Issuing policies.
depositRequirement Monetary amount object The collateral requirement created by the audit.
description String The description of the audit.
effectiveDate String in the date-time format YYYY-MM-DD The effective date of the policy audit billing instruction.
expirationDate String in the date-time format YYYY-MM-DD The expiration date of the policy audit billing instruction.
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 to the SpecialHandling typelist Defines if billing is handled differently for the billing instruction.
totalPremium Boolean Determines how the policy period's charges are updated. Defaults to false.
  • If true, the charges in the request represent the total amount of premium that are due for the policy term. BillingCenter creates negative charges to cancel out the existing charges on the policy, so the total amount of premium due on the policy period comes from the charges in the request. See the example below for more.
  • If false, the charges in the request are added to the policy, and the original charges on the policy are not changed.
finalAudit Boolean Indicates whether this is the final audit for this policy period. Defaults to false.
  • If true, the policy period's closureStatus is set to open. This status is set to open so that the policy period is eligible to be closed by the PolicyClosure batch process.
  • If false, the policy period's closureStatus is not changed.

Examples of creating audits

The following example demonstrates creating a final audit where there is an additional charge for $31.50 added. This amount is added as a separate charge. No existing charges on the policy period are modified, because totalPremium is not set to true. Additionally, this request causes the closure status of the policy period to be set to open, because this is the final audit.

Command 
POST /billing/v1/accounts/bc:4322/policies/bc:100293/policy-periods/bc:100294/audits
Request body 
{
    "data": {
        "attributes": {
            "modificationDate": "2025-08-13",
            "finalAudit": true,
            "charges": [
                {
                    "amount": {
                        "amount": "31.50",
                        "currency": "USD"
                    },
                    "chargePattern": {
                        "id": "default_data:1",
                        "displayName": "Premium"
                    }
                }
            ]
        }
    }
}

The AuditData object is returned.

For another example, suppose that the target policy period bc:100443 has two charges initially: one premium charge for $1200, and one taxes charge for $60. The policy administration system calculates that an additional $100 premium must be paid. Instead of sending over the $100 dollar difference as its own charge, the policy administration system can send entire new policy charges to replace the old policy charges. The request might look like this:

Command 
POST /billing/v1/accounts/bc:4322/policies/bc:100443/policy-periods/bc:100445/audits
Request body 
{
    "data": {
        "attributes": {
            "modificationDate": "2025-08-12",
            "finalAudit": true,
            "totalPremium": true,
            "charges": [
                {
                    "amount": {
                        "amount": "1300",
                        "currency": "USD"
                    },
                    "chargePattern": {
                        "id": "default_data:1",
                        "displayName": "Premium"
                    }
                },
                {
                    "amount": {
                        "amount": "60",
                        "currency": "USD"
                    },
                    "chargePattern": {
                        "id": "default_data:6",
                        "displayName": "Taxes"
                    }
                }
            ]
        }
    }
}

As a result of this request, BillingCenter creates negative charges to cancel out the original premium and tax charges on the policy period, and adds the new charges to the policy period.

The AuditData response object contains both the newly created charges and the negative charges that BillingCenter created to reverse the original charges on the policy period:

Response

{
    "data": {
        "attributes": {
            "charges": [
                {
                    "amount": {
                        "amount": "1300.00",
                        "currency": "usd"
                    },
                    "chargePattern": {
                        "displayName": "Premium",
                        "id": "default_data:1",
                        "type": "ChargePattern",
                        "uri": "/admin/v1/charge-patterns/default_data:1"
                        ...
                },
                {
                    "amount": {
                        "amount": "-1200.00",
                        "currency": "usd"
                    },
                    "chargePattern": {
                        "displayName": "Premium",
                        "id": "default_data:1",
                        "type": "ChargePattern",
                        "uri": "/admin/v1/charge-patterns/default_data:1"
                    },
                    ...
                },
                {
                    "amount": {
                        "amount": "60.00",
                        "currency": "usd"
                    },
                    "chargePattern": {
                        "displayName": "Taxes",
                        "id": "default_data:6",
                        "type": "ChargePattern",
                        "uri": "/admin/v1/charge-patterns/default_data:6"
                    },
                    ...
                },
                {
                    "amount": {
                        "amount": "-60.00",
                        "currency": "usd"
                    },
                    "chargePattern": {
                        "displayName": "Taxes",
                        "id": "default_data:6",
                        "type": "ChargePattern",
                        "uri": "/admin/v1/charge-patterns/default_data:6"
                    },
                    ...
                }
            ],
            ...
        },
        "checksum": "0"
    }
}

Waive a final audit

In some cases, the policy administration system determines that a final audit is not going to occur. You can waive final audits using the following endpoint:

  • POST /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/waive-final-audit

When a final audit is waived:

  • BillingCenter releases any charges that are being held for a final audit. The holdStatus of the charge is set to none.
  • The closureStatus of the policy period is set to open.

No request body is required.

For example, the following waives a final audit for policy period bc:101223:

Command 
POST /billing/v1/accounts/bc:4322/policies/bc:101222/policy-periods/bc:101223/waive-final-audit
Request body 
<no request body>