Invoices API

These API endpoints allow you to list the finalised invoices on your account and download any individual invoice as a PDF. Together they let you retrieve a full set of invoices programmatically: list the invoices, then download each one using the URL provided for it.

Tip: You can explore and test these endpoints interactively using our OpenAPI documentation.

Permissions

Both endpoints require the authenticated user to be a billing manager on the account. Requests made with an API key belonging to a user without billing permissions are rejected with a 403 Forbidden response.

List Invoices

Returns every finalised invoice on the account, most recent first. Each invoice includes a download_url pointing at the PDF download endpoint for that invoice.

URL

/account/invoices

HTTP Method

GET

Supported Parameters

This endpoint does not accept any parameters.

Example cURL Request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
https://test.deployhq.com/account/invoices

Example Response

[
  {
    "number": 1042,
    "kind": "subscription",
    "currency": "gbp",
    "total": "120.00",
    "vat": "20.00",
    "paid": true,
    "paid_at": "2026-01-15T09:30:00Z",
    "created_at": "2026-01-10T08:00:00Z",
    "download_url": "https://test.deployhq.com/account/invoices/1042.pdf"
  },
  {
    "number": 1041,
    "kind": "subscription",
    "currency": "gbp",
    "total": "120.00",
    "vat": "20.00",
    "paid": false,
    "paid_at": null,
    "created_at": "2025-12-10T08:00:00Z",
    "download_url": "https://test.deployhq.com/account/invoices/1041.pdf"
  }
]

Notes

• The number field is the invoice number and is used to identify the invoice in the download endpoint.
• The kind field indicates the type of invoice, for example subscription.
• The total and vat fields are returned as strings to preserve the exact amounts.
• The paid field indicates whether the invoice has been paid; when it has, paid_at contains the time of payment, otherwise it is null.
• The download_url field is the full URL for downloading that invoice as a PDF.
• Only finalised invoices are returned.

Download an Invoice PDF

Downloads a single invoice as a PDF. The response body is the binary PDF content rather than JSON.

URL

/account/invoices/:number.pdf

Replace :number with the invoice number returned by the list endpoint.

HTTP Method

GET

Supported Parameters

Example cURL Request

curl -H "Accept: application/pdf" \
--user adam@atechmedia.com:my-api-key \
-o invoice-1042.pdf \
https://test.deployhq.com/account/invoices/1042.pdf

Example Response

The response body is the raw PDF document, served with a Content-Type of application/pdf. The -o option in the example above writes it to a file.

Notes

• Request the invoice using its number, with a .pdf extension on the URL.
• If no invoice exists with the given number, the endpoint returns a 404 Not Found response with a JSON error body.
• To download all of your invoices, call the list endpoint first and then request each invoice's download_url in turn.