Working with charges

A charge is a cost related to either a policy period or an account that must be processed and tracked as an individual unit. For example, a Personal Auto policy could have three charges:

  • A $1200 charge for the premium

  • A $53 charge for taxes

  • A $10 charge for an installment fee

Some charges are billed over a series of invoices, such as a charge that is billed as a down payment and a set of monthly installments. To enable this, BillingCenter does not place charges directly onto invoices. Instead, BillingCenter converts every charge into one or more invoice items and then places these invoice items on invoices. An invoice item is a line item that represents all or part of a charge.

Cloud API provides endpoints for working with charges and their invoice items.

Querying for charges

A charge can be associated directly with an account (an account-level charge) or with an account's policy's period (a policy-level charge). You can use the following endpoints to query for charges associated with a given account or policy period:

  • GET /billing/v1/accounts/{accountId}/charges

  • GET /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/(policyPeriodId}/charges

For more information, see Account-level charges and Policy-level charges.

Accessing a specific charge

Use the following endpoint to access a specific charge:

  • GET /billing/v1/charges/{chargeId}

A call to this endpoint is typically preceded by a call to retrieve the charges for an account or policy period, as described in the previous topic.

For example, suppose you query for a policy period's charges and identify that there is one premium charge whose id is bc:1212. The following request accesses that specific charge.

Command

GET /billing/v1/charges/bc:1212

Response payload

{
    "data": {
        "attributes": {
            "amount": {
                "amount": "1200.00",
                "currency": "usd"
            },
            "chargeDate": "2023-05-24T17:58:44.732Z",
            "chargePattern": {
                "displayName": "Premium",
                "id": "default_data:1"
            },
            "holdStatus": {
                "code": "none",
                "name": "Not Held"
            },
            "id": "bc:1212",
            "reversed": false,
            "skipInvoiceItemCreation": false,
            "totalInstallments": 9,
            "writtenDate": "2023-05-24T17:58:43.762Z"
        },
        ...

Accessing invoice items

Use the following endpoints to access the invoice items for a given charge:

  • GET /billing/v1/charges/{chargeId}/invoice-items

  • GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId}

For example, the following request retrieves the invoice items for charge bc:1212. The response as shown below includes the first two invoice items: the down payment item and the first installment item.

Command

GET /billing/v1/charges/bc:1212/invoice-items

Response payload

{
    "count": 10,
    "data": [
        {
            "attributes": {
                "amount": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "eventDate": "2023-04-29",
                "id": "bc:STfiGLle2rKWvhYwGLYlA",
                "invoiceDateOverride": {
                    "code": "none",
                    "name": "None"
                },
                "reversed": false,
                "type": {
                    "code": "deposit",
                    "name": "Down Payment"
                }
            },
            ...
        },
        {
            "attributes": {
                "amount": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "eventDate": "2023-07-01",
                "id": "bc:SIN97D4oBanb3p5_IjrAL",
                "installmentNumber": 1,
                "invoiceDateOverride": {
                    "code": "none",
                    "name": "None"
                },
                "reversed": false,
                "type": {
                    "code": "installment",
                    "name": "Installment"
                }
            },
            ...
        },
        ...