Policy-level charges

An account can have two levels of charges: account-level charges and policy-level charges. A policy-level charge is a charge that is owned by one of the account's policy's policy periods (such as a premium charge or tax charge for a given policy period). For more information on account-level charges, see Account-level charges.

Use the following endpoints to query for policy-level charges.

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

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

From an application design standpoint, charges are associated with accounts and policy periods. But charges are considered to be a top-level entity. Thus, to get a policy period's charges, you use an endpoint that has the account as the parent. But to get details about a specific charge, you use an endpoint where the charge itself is the parent.

For example, the following request queries for the policy-level charges for policy period bc:909 for policy bc:808, which is owned by account bc:707. The response specifies two charges: a premium charge for $1200 and a tax charge for $50.

Command

GET /billing/v1/accounts/bc:707/policies/bc:808/policy-periods/bc:909/charges
Response body
{
    "count": 2,
    "data": [
        {
            "attributes": {
                "amount": {
                    "amount": "50.00",
                    "currency": "usd"
                },
                "chargeDate": "2023-05-23T21:34:33.717Z",
                "chargePattern": {
                    "displayName": "Taxes",
                    "id": "default_data:6"
                },
                "holdStatus": {
                    "code": "none",
                    "name": "Not Held"
                },
                "id": "bc:SYe6sQChPC8HsTpUAz5rT",
                "reversed": false,
                "skipInvoiceItemCreation": false,
                "totalInstallments": 0,
                "writtenDate": "2023-05-23T21:34:32.748Z"
            },
            ...
        },
        {
            "attributes": {
                "amount": {
                    "amount": "1200.00",
                    "currency": "usd"
                },
                "chargeDate": "2023-05-23T21:34:33.717Z",
                "chargePattern": {
                    "displayName": "Premium",
                    "id": "default_data:1"
                },
                "holdStatus": {
                    "code": "none",
                    "name": "Not Held"
                },
                "id": "bc:SjwKGEQ00pe-TC22SOUT_",
                "reversed": false,
                "skipInvoiceItemCreation": false,
                "totalInstallments": 9,
                "writtenDate": "2023-05-23T21:34:32.742Z"
            },
            ...

The following request retrieves more information about the premium charge from the previous request.

Command

GET /billing/v1/charges/bc:SjwKGEQ00pe-TC22SOUT_
Response body
{
    "data": {
        "attributes": {
            "amount": {
                "amount": "1200.00",
                "currency": "usd"
            },
            "chargeDate": "2023-05-23T21:34:33.717Z",
            "chargePattern": {
                "displayName": "Premium",
                "id": "default_data:1"
            },
            "holdStatus": {
                "code": "none",
                "name": "Not Held"
            },
            "id": "bc:SjwKGEQ00pe-TC22SOUT_",
            "reversed": false,
            "skipInvoiceItemCreation": false,
            "totalInstallments": 9,
            "writtenDate": "2023-05-23T21:34:33.717Z"
        },
        ...