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 endpoints to retrieve invoice items:

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

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

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"
                },
                "policyPeriod": {
                    "displayName": "pc:4329",
                    "id": "bc:SG2vzarSYSof8a6Zp7IjO",
                    "type": "PolicyPeriod",
                    "uri": "/billing/v1/accounts/bc:St9b7qu5VHXEYJ584krXB/policies/bc:S2BoN_2S1N5dj22lm3CIq/policy-periods/pc:4329"
                },
                "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:

  1. GET /billing/v1/accounts/{accountId}/charges, to get the charge ID

  2. 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:

  1. GET /billing/v1/account/{accountId}/policies to get the policy ID

  2. GET /billing/v1/account/{accountId}/policies/{policyId}/policy-periods to get the policy period ID

  3. GET /billing/v1/account/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/charges, to get the charge ID

  4. GET /billing/v1/charges/{chargeId}/invoice-items/{invoiceItemId}, to get the invoice item in detail

Filtering invoice items by policy period

For a given invoice, you can retrieve invoice items filtered based on the policy period. Use the field policyPeriodId to do this. For example, the following request retrieves only invoice items on the policy period bc:3409.

GET /billing/v1/invoices/bc:2202/invoice-items?filter=policyPeriodId:eq:bc::3409