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.

GET /api/v1/invoices

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

---

Authentication

Authorization · string · required

Bearer token in the form Bearer inv_live_…. The token must carry the invoices:read scope.

---

Query Parameters

status · 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.

customer · string

Filter by customer. Accepts a cus_… public ID or the underlying UUID.

from · string

Lower bound on issue_date, inclusive. ISO 8601 date string (YYYY-MM-DD).

to · string

Upper bound on issue_date, inclusive. ISO 8601 date string (YYYY-MM-DD).

cursor · string

Opaque pagination cursor. Pass the next_cursor value returned by the previous page. Omit to start from the first page.

limit · integer

Maximum number of invoices to return per page. The server may return fewer. Defaults to 20.

---

Request Example

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

{
  "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"
}

The list response does not expand lines. To retrieve line items for an invoice, call GET /api/v1/invoices/:id. Only the retrieve endpoint populates the lines.data array.

---

Response Fields

data · array

Array of invoice objects. Empty array [] when no invoices match the filter. Invoice objects in the list do not include the lines field.

data[].id · string

Unique public identifier for the invoice, prefixed in_.

data[].object · string

Always "invoice".

data[].number · 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.

data[].status · 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.

data[].customer · string

The cus_… public ID of the customer this invoice belongs to.

data[].currency · string

Three-letter ISO 4217 currency code (e.g. "USD", "EUR", "INR").

data[].collection_method · string

How payment is collected: "send_invoice" or "charge_automatically".

data[].issue_date · string

ISO 8601 date the invoice was issued (YYYY-MM-DD).

data[].due_date · string | null

ISO 8601 date payment is due. null if no due date was set.

data[].description · string | null

Notes shown on the invoice body. null if not set.

data[].footer · string | null

Footer text shown at the bottom of the invoice, typically used for payment terms. null if not set.

data[].subtotal · integer

Sum of all line totals before discounts and tax, in minor units (e.g. 500000 = $5,000.00 USD).

data[].discount · integer

Total discount applied across all line items, in minor units.

data[].taxable · integer

The taxable amount (subtotal minus discount), in minor units.

data[].tax · integer

Total tax charged, in minor units.

data[].total · integer

Grand total (taxable + tax), in minor units.

data[].amount_due · integer

Amount currently owed, in minor units. 0 for drafts, paid, and voided invoices. Equals total for open and overdue invoices.

data[].amount_in_words · string | null

The total expressed in words (e.g. "Five thousand six hundred and five dollars"). null if not generated.

data[].public_url_token · string | null

Token for the shareable public invoice URL. null until the invoice is finalized.

data[].finalized_at · string | null

ISO 8601 datetime when the invoice was finalized. null for drafts.

data[].paid_at · string | null

ISO 8601 datetime when the invoice was marked paid. null until payment is recorded.

data[].voided_at · string | null

ISO 8601 datetime when the invoice was voided. null unless voided.

data[].void_reason · string | null

Reason supplied when voiding. null if the invoice was not voided.

data[].created · string

ISO 8601 datetime when the invoice record was created.

data[].updated · string

ISO 8601 datetime of the last modification to the invoice record.

next_cursor · 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.

---

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.