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",
            "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 Maintaining positive equity.

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"
        },
      ...
    }
}