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](https://api.deployhq.com/docs).

## 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

```json
[
  {
    "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

| Parameter | Location | Description |
| --- | --- | --- |
| `number` | Path | The invoice number to download. |

### 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.