Working with invoices

Querying for invoices

Use the following endpoints to retrieve information about invoices:

  • GET /billing/v1/accounts/{accountId}/invoices
  • GET /billing/v1/invoices/{invoiceId}

For example, the following request retrieves invoices for account bc:16:

GET /billing/v1/accounts/bc:16/invoices

{
    "count": 10,
    "data": [
        {
            "attributes": {
                "adHoc": false,
                "amount": {
                    "amount": "175.00",
                    "currency": "usd"
                },
                "amountDue": {
                    "amount": "175.00",
                    "currency": "usd"
                },
                "eventDate": "2022-11-01",
                "id": "bc:8819",
                "invoiceNumber": "1000000000",
                "paymentDueDate": "2022-11-22",
                "status": {
                    "code": "planned",
                    "name": "Planned"
                },
                "subtype": "AccountInvoice"
            },
            "checksum": "0",
            "links": {
                "self": {
                    "href": "/billing/v1/invoices/bc:SvdfPR6dOWmlT_xoqH5yR",
                    "methods": [
                        "get"
                    ]
                }
            }
        },
        ...

The following request gets detailed information about invoice bc:8819. Note that in order to get details about specific invoice, the endpoint path does not include the account. The parent of the endpoint path is /invoices.

GET /billing/v1/invoices/bc:8819

{
    "data": {
        "attributes": {
            "adHoc": false,
            "amount": {
                "amount": "175.00",
                "currency": "usd"
            },
            "amountDue": {
                "amount": "175.00",
                "currency": "usd"
            },
            "eventDate": "2022-11-01",
            "id": "bc:8819",
            "invoiceNumber": "1000000000",
            "invoiceStream": {
                "displayName": "Monthly",
                "id": "bc:SU1Dk4IN9ULJkScqm_bij",
                "type": "AccountInvoiceStream",
                "uri": "/billing/v1/accounts/bc:5641/invoice-streams/bc:5690"
            },
            "paymentDueDate": "2022-11-22",
            "status": {
                "code": "planned",
                "name": "Planned"
            },
            "subtype": "AccountInvoice"
        }
        ...

Modifying invoices

Use the following endpoint to modify a single invoice:

  • PATCH /billing/v1/invoices/{invoiceId}

The only attributes of an invoice that you can update are the eventDate (the bill date) and the paymentDueDate (the due date).

When modifying an invoice, the following must be true:
  • The invoice has a status of planned
  • paymentDueDate and eventDate cannot be in the past
  • paymentDueDate cannot be before eventDate
Note: If you change the bill date or due date of an invoice in the user interface, you might be shown an equity warning. Cloud API does not provide any sort of equity warning as part of the response when updating invoices. For more information, see the BillingCenter Cloud API Consumer Guide.

The example below demonstrates updating the bill date and the due date on invoice bc:Swwq21ZNjhqLn_Vl0SPIl. The updated invoice is returned in the response.

Command
PATCH /billing/v1/invoices/bc:Swwq21ZNjhqLn_Vl0SPIl
Request
{
    "data": {
        "attributes": {
            "eventDate": "2024-03-10",
            "paymentDueDate": "2024-03-24"
        }
    }
}
Response
{
    "data": {
        "attributes": {
            "adHoc": false,
            "amount": {
                "amount": "98.19",
                "currency": "usd"
            },
            "amountDue": {
                "amount": "98.19",
                "currency": "usd"
            },
            "eventDate": "2024-03-10",
            "id": "bc:Swwq21ZNjhqLn_Vl0SPIl",
            "invoiceNumber": "1000000014",
            "paymentDueDate": "2024-03-24",
            "status": {
                "code": "planned",
                "name": "Planned"
            },
            "subtype": "AccountInvoice"
        },
      ...
    }
}

Retrieving invoices on an invoice stream

You can retrieve all the invoices on an invoice stream.

In addition to retrieving all invoices on accounts and producers, you might want to retrieve all the invoices on a specific invoice stream. This is useful in the following scenarios:

  • An account that uses account-level billing and has policies with different periodicities. There is an invoice stream for each periodicity.
  • An account that uses policy-level billing, so there is a different invoice stream for each policy.

Use the following endpoint to retrieve invoices on an invoice stream:

  • GET /billing/v1/accounts/{accountId}/invoice-streams/{invoiceStreamId}/invoices