Working with invoice items

An invoice item is an object that represents either an entire charge or a portion of a charge. Invoice items are placed onto invoices, and they provide the ability to bill a given charge over multiple invoices. Thus, every invoice item belongs to a charge and is associated with an invoice.

Accessing the invoice items for an invoice

Use the following endpoint to retrieve the invoice items for an invoice. Note that you do not need to know the ID of the account or policy period. The only thing you need is the invoice ID:

GET /billing/v1/invoices/{invoiceId}/invoice-items

For example, the following request queries for the invoice items related to invoice bc:2022. Note that the invoice has three invoice items: a down payment item and two one-item invoice items (which could be invoice items for taxes or other fees).

Command

GET /billing/v1/invoices/bc:2202/invoice-items

Response payload

{
    "count": 3,
    "data": [
        {
            "attributes": {
                "amount": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "eventDate": "2023-04-29",
                "id": "bc:STfiGLle2rKWvhYwGLYlA",
                "invoiceDateOverride": {
                    "code": "none",
                    "name": "None"
                },
                "paidAmount": {
                    "amount": "120.00",
                    "currency": "usd"
                },
                "reversed": false,
                "type": {
                    "code": "deposit",
                    "name": "Down Payment"
                }
            },
            ...
        },
        {
            "attributes": {
                "amount": {
                    "amount": "50.00",
                    "currency": "usd"
                },
                "eventDate": "2023-04-29",
                "id": "bc:S86b6sNYUsAZ1DaGSSIZj",
                "invoiceDateOverride": {
                    "code": "none",
                    "name": "None"
                },
                "paidAmount": {
                    "amount": "50.00",
                    "currency": "usd"
                },
                "reversed": false,
                "type": {
                    "code": "onetime",
                    "name": "One-Time"
                }
            },
            ...
        },
        {
            "attributes": {
                "amount": {
                    "amount": "15.00",
                    "currency": "usd"
                },
                "eventDate": "2023-05-24",
                "id": "bc:SUdh_6Pxwe1VjwiGwT18p",
                "invoiceDateOverride": {
                    "code": "none",
                    "name": "None"
                },
                "paidAmount": {
                    "amount": "0.00",
                    "currency": "usd"
                },
                "reversed": false,
                "type": {
                    "code": "onetime",
                    "name": "One-Time"
                }
            },
            ...
        }
    ...

Accessing a specific invoice item for an invoice

From an application design standpoint, invoice items are associated with invoices. But they are considered to be children of charges. (An invoice item can move from one invoice to another, but an invoice item always belongs to the same charge.) Thus, in order to access a specific invoice item, you must use the following endpoint, which has charge as the parent:

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

If the invoice item is related to an account-level charge, and you know only the account ID, the invoice ID, and the invoice item ID, then you must execute the following calls to get the invoice item in detail:

GET /billing/v1/accounts/{accountId}/charges, to get the charge ID
GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId}, to get the invoice item in detail

If the invoice item is related to a policy-level charge, and you know only the account ID, the invoice ID, and the invoice item ID, then you must execute the following calls to get the invoice item in detail:

GET /billing/v1/account/{accountId}/policies to get the policy ID
GET /billing/v1/account/{accountId}/policies/{policyId}/policy-periods to get the policy period ID
GET /billing/v1/account/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/charges, to get the charge ID
GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId}, to get the invoice item in detail