> ## Documentation Index
> Fetch the complete documentation index at: https://docs.horizonpay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List All Invoices — Invoice AI REST API Reference

> Retrieve a cursor-paginated list of invoices. Filter by status, customer, or date range. Results include overdue detection and pagination cursors.

Returns a cursor-paginated list of invoice objects belonging to your account. Results are ordered newest-first. Use the `next_cursor` value from one page as the `cursor` parameter on the next call to walk through the full set. An empty `data` array with `next_cursor: null` means you have reached the end.

The `overdue` status is computed at read time — no invoice row is ever stored with that value — so filtering by `status=overdue` returns all open invoices whose `due_date` is in the past, even though their stored column reads `open`.

```http theme={null}
GET /api/v1/invoices
```

**Base URL:** `https://invoice.horizonpay.co`

***

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token in the form `Bearer inv_live_…`. The token must carry the `invoices:read` scope.
</ParamField>

***

## Query Parameters

<ParamField query="status" type="string">
  Filter by invoice status. One of: `draft`, `open`, `paid`, `overdue`, `void`.
  `overdue` is computed server-side from `due_date`; all other values match the stored column.
</ParamField>

<ParamField query="customer" type="string">
  Filter by customer. Accepts a `cus_…` public ID or the underlying UUID.
</ParamField>

<ParamField query="from" type="string">
  Lower bound on `issue_date`, inclusive. ISO 8601 date string (`YYYY-MM-DD`).
</ParamField>

<ParamField query="to" type="string">
  Upper bound on `issue_date`, inclusive. ISO 8601 date string (`YYYY-MM-DD`).
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor. Pass the `next_cursor` value returned by the previous page. Omit to start from the first page.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of invoices to return per page. The server may return fewer. Defaults to `20`.
</ParamField>

***

## Request Example

```bash theme={null}
curl -G https://invoice.horizonpay.co/api/v1/invoices \
  -H "Authorization: Bearer inv_live_sk_1234abcd5678efgh" \
  --data-urlencode "status=open" \
  --data-urlencode "customer=cus_01J9ZXMQR7P4KBN2VWTF3D6H8A" \
  --data-urlencode "from=2025-01-01" \
  --data-urlencode "to=2025-06-30" \
  --data-urlencode "limit=5"
```

***

## Response Example

```json theme={null}
{
  "data": [
    {
      "id": "in_01J9ZXMQR7P4KBN2VWTF3D6H8A",
      "object": "invoice",
      "number": "INV/25-26/0042",
      "status": "open",
      "customer": "cus_01J9ZXMQR7P4KBN2VWTF3D6H8A",
      "currency": "USD",
      "collection_method": "send_invoice",
      "issue_date": "2025-03-15",
      "due_date": "2025-04-14",
      "description": "Q1 consulting retainer",
      "footer": "Payment due within 30 days of issue.",
      "subtotal": 500000,
      "discount": 25000,
      "taxable": 475000,
      "tax": 85500,
      "total": 560500,
      "amount_due": 560500,
      "amount_in_words": "Five thousand six hundred and five dollars",
      "public_url_token": "tok_share_a1b2c3d4e5f6",
      "finalized_at": "2025-03-15T09:30:00.000Z",
      "paid_at": null,
      "voided_at": null,
      "void_reason": null,
      "created": "2025-03-14T17:12:00.000Z",
      "updated": "2025-03-15T09:30:00.000Z"
    },
    {
      "id": "in_01J9ZXMQR7P4KBN2VWTF3D6H8B",
      "object": "invoice",
      "number": "INV/25-26/0041",
      "status": "open",
      "customer": "cus_01J9ZXMQR7P4KBN2VWTF3D6H8A",
      "currency": "USD",
      "collection_method": "send_invoice",
      "issue_date": "2025-02-01",
      "due_date": "2025-03-03",
      "description": null,
      "footer": null,
      "subtotal": 200000,
      "discount": 0,
      "taxable": 200000,
      "tax": 36000,
      "total": 236000,
      "amount_due": 236000,
      "amount_in_words": null,
      "public_url_token": "tok_share_f6e5d4c3b2a1",
      "finalized_at": "2025-02-01T10:00:00.000Z",
      "paid_at": null,
      "voided_at": null,
      "void_reason": null,
      "created": "2025-02-01T08:45:00.000Z",
      "updated": "2025-02-01T10:00:00.000Z"
    }
  ],
  "next_cursor": "cursor_eyJpZCI6ImluXzAxSjlaWE1RUjdQNEtCTjJWV1RGM0Q2SDhCIn0"
}
```

<Note>
  The list response does **not** expand `lines`. To retrieve line items for an invoice, call [GET /api/v1/invoices/:id](/api-reference/invoices/retrieve). Only the retrieve endpoint populates the `lines.data` array.
</Note>

***

## Response Fields

<ResponseField name="data" type="array">
  Array of invoice objects. Empty array `[]` when no invoices match the filter. Invoice objects in the list do not include the `lines` field.
</ResponseField>

<ResponseField name="data[].id" type="string">
  Unique public identifier for the invoice, prefixed `in_`.
</ResponseField>

<ResponseField name="data[].object" type="string">
  Always `"invoice"`.
</ResponseField>

<ResponseField name="data[].number" type="string | null">
  Human-readable invoice number (e.g. `INV/25-26/0042`). `null` for drafts — a number is assigned only when the invoice is finalized.
</ResponseField>

<ResponseField name="data[].status" type="string">
  Current invoice status. One of `draft`, `open`, `paid`, `overdue`, or `void`. `overdue` is derived at read time from `due_date` and is never stored.
</ResponseField>

<ResponseField name="data[].customer" type="string">
  The `cus_…` public ID of the customer this invoice belongs to.
</ResponseField>

<ResponseField name="data[].currency" type="string">
  Three-letter ISO 4217 currency code (e.g. `"USD"`, `"EUR"`, `"INR"`).
</ResponseField>

<ResponseField name="data[].collection_method" type="string">
  How payment is collected: `"send_invoice"` or `"charge_automatically"`.
</ResponseField>

<ResponseField name="data[].issue_date" type="string">
  ISO 8601 date the invoice was issued (`YYYY-MM-DD`).
</ResponseField>

<ResponseField name="data[].due_date" type="string | null">
  ISO 8601 date payment is due. `null` if no due date was set.
</ResponseField>

<ResponseField name="data[].description" type="string | null">
  Notes shown on the invoice body. `null` if not set.
</ResponseField>

<ResponseField name="data[].footer" type="string | null">
  Footer text shown at the bottom of the invoice, typically used for payment terms. `null` if not set.
</ResponseField>

<ResponseField name="data[].subtotal" type="integer">
  Sum of all line totals before discounts and tax, in minor units (e.g. `500000` = \$5,000.00 USD).
</ResponseField>

<ResponseField name="data[].discount" type="integer">
  Total discount applied across all line items, in minor units.
</ResponseField>

<ResponseField name="data[].taxable" type="integer">
  The taxable amount (subtotal minus discount), in minor units.
</ResponseField>

<ResponseField name="data[].tax" type="integer">
  Total tax charged, in minor units.
</ResponseField>

<ResponseField name="data[].total" type="integer">
  Grand total (taxable + tax), in minor units.
</ResponseField>

<ResponseField name="data[].amount_due" type="integer">
  Amount currently owed, in minor units. `0` for drafts, paid, and voided invoices. Equals `total` for `open` and `overdue` invoices.
</ResponseField>

<ResponseField name="data[].amount_in_words" type="string | null">
  The total expressed in words (e.g. `"Five thousand six hundred and five dollars"`). `null` if not generated.
</ResponseField>

<ResponseField name="data[].public_url_token" type="string | null">
  Token for the shareable public invoice URL. `null` until the invoice is finalized.
</ResponseField>

<ResponseField name="data[].finalized_at" type="string | null">
  ISO 8601 datetime when the invoice was finalized. `null` for drafts.
</ResponseField>

<ResponseField name="data[].paid_at" type="string | null">
  ISO 8601 datetime when the invoice was marked paid. `null` until payment is recorded.
</ResponseField>

<ResponseField name="data[].voided_at" type="string | null">
  ISO 8601 datetime when the invoice was voided. `null` unless voided.
</ResponseField>

<ResponseField name="data[].void_reason" type="string | null">
  Reason supplied when voiding. `null` if the invoice was not voided.
</ResponseField>

<ResponseField name="data[].created" type="string">
  ISO 8601 datetime when the invoice record was created.
</ResponseField>

<ResponseField name="data[].updated" type="string">
  ISO 8601 datetime of the last modification to the invoice record.
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Opaque cursor to pass as `cursor` on the next request to retrieve the following page. `null` when you have reached the last page.
</ResponseField>

***

## Error Codes

| HTTP Status | `code`         | Meaning                                                                      |
| ----------- | -------------- | ---------------------------------------------------------------------------- |
| `401`       | `unauthorized` | Missing or invalid `Authorization` header, or expired token.                 |
| `403`       | `forbidden`    | Token does not carry the `invoices:read` scope.                              |
| `429`       | `rate_limited` | Per-credential rate limit exceeded. Check the `Retry-After` response header. |