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

# List Invoices

> List invoices, filtered by status, counterparty, or date, with cursor pagination.

### Overview

Returns a page of invoices. The common uses are finding what is outstanding and finding what is
overdue — those are different queries, and only the second one is about time.

### Query

<ParamField query="limit" type="integer">
  Maximum results to return. Defaults to 50.
</ParamField>

<ParamField query="offset" type="integer">
  Number of results to skip. Defaults to 0.
</ParamField>

<ParamField query="customer_id" type="string">
  Filter by customer ID (UUID).
</ParamField>

<ParamField query="order_id" type="string">
  Filter by order ID (UUID).
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `draft`, `sent`, `viewed`, `paid`, `overdue`, or `voided`.
</ParamField>

<ParamField query="invoice_type" type="string">
  Filter by type: `standard`, `credit_note`, `pro_forma`, or `recurring`.
</ParamField>

<ParamField query="overdue_only" type="boolean">
  Return only overdue invoices.
</ParamField>

<ParamField query="from_date" type="string">
  Invoices created on or after this date (RFC 3339).
</ParamField>

<ParamField query="to_date" type="string">
  Invoices created on or before this date (RFC 3339).
</ParamField>

### Response

<ResponseField name="data" type="array" required>
  The invoices, each shaped as in [Get Invoice](/stateset-commerce-api-reference/invoices/get).
</ResponseField>

<ResponseField name="total" type="integer">
  Total matching invoices, for computing how many pages remain.
</ResponseField>

### Errors

Succeeds with `200`. Failures return `400`, `401`, `403` or `429` with an error body, per the [platform status-code contract](/api-reference/errors#http-status-codes).

<RequestExample>
  ```bash cURL theme={null}
  # Everything sent but not yet paid
  curl 'https://api.stateset.com/api/v1/invoices?status=sent&limit=50' \
    -H 'Authorization: Bearer <token>'
  ```

  ```bash Overdue theme={null}
  curl 'https://api.stateset.com/api/v1/invoices?overdue_only=true' \
    -H 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "invoice_id": "inv_1234567890",
        "status": "sent",
        "total_amount": { "value": "12000.00", "denom": "ssusd" },
        "amount_paid": { "value": "5000.00", "denom": "ssusd" },
        "balance_due": { "value": "7000.00", "denom": "ssusd" }
      }
    ],
    "total": 128
  }
  ```
</ResponseExample>

<Warning>
  This endpoint paginates with `limit` and `offset`, not a cursor. Offset paging over a set that is
  changing underneath you can skip or repeat rows — invoices move between `sent`, `paid`, and
  `overdue` continuously. Narrow with `status` or a `from_date`/`to_date` window so each page is drawn
  from a more stable set, and treat a full walk as approximate rather than exact.
</Warning>

### Related

* [Get Invoice](/stateset-commerce-api-reference/invoices/get)
* [Create Invoice](/stateset-commerce-api-reference/invoices/create)
* [Finance](/stateset-commerce-api-reference/finance) — factor what is outstanding