> ## 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 all invoices with filtering and pagination

<Note>
  This endpoint retrieves a paginated list of invoices. Use filters to narrow results by status, customer, date range, and more.
</Note>

## Authentication

This endpoint requires a valid API key with `invoices:read` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="integer">
  Number of items to return (default: 20, max: 100)
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination (invoice ID)
</ParamField>

<ParamField query="status" type="string">
  Filter by status: "draft", "sent", "viewed", "partially\_paid", "paid", "overdue", "voided"
</ParamField>

<ParamField query="customer_id" type="string">
  Filter by customer ID
</ParamField>

<ParamField query="issue_date_from" type="string">
  Filter by issue date start (YYYY-MM-DD)
</ParamField>

<ParamField query="issue_date_to" type="string">
  Filter by issue date end (YYYY-MM-DD)
</ParamField>

<ParamField query="due_date_from" type="string">
  Filter by due date start (YYYY-MM-DD)
</ParamField>

<ParamField query="due_date_to" type="string">
  Filter by due date end (YYYY-MM-DD)
</ParamField>

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

<ParamField query="sort_by" type="string">
  Sort field: "created\_at", "issue\_date", "due\_date", "total\_amount"
</ParamField>

<ParamField query="sort_order" type="string">
  Sort order: "asc" or "desc" (default: "desc")
</ParamField>

### Response

<ResponseField name="object" type="string">
  Object type, always "list"
</ResponseField>

<ResponseField name="data" type="array">
  Array of invoice objects
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more items exist
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stateset.com/v1/invoices?status=sent&limit=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const invoices = await stateset.invoices.list({
    status: 'sent',
    limit: 10,
    overdue_only: false
  });
  ```

  ```python Python theme={null}
  invoices = stateset.invoices.list(
    status='sent',
    limit=10,
    overdue_only=False
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "inv_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
        "object": "invoice",
        "invoice_number": "INV-2024-0001",
        "status": "sent",
        "customer_id": "cust_abc123",
        "customer_name": "Acme Corporation",
        "issue_date": "2024-01-19",
        "due_date": "2024-02-18",
        "currency": "USD",
        "total_amount": 697500,
        "amount_due": 697500,
        "days_until_due": 30
      },
      {
        "id": "inv_7823f083-bb2c-54d6-bf6d-1b8e3fc75f41",
        "object": "invoice",
        "invoice_number": "INV-2024-0002",
        "status": "partially_paid",
        "customer_id": "cust_def456",
        "customer_name": "TechCorp Inc",
        "issue_date": "2024-01-15",
        "due_date": "2024-01-30",
        "currency": "USD",
        "total_amount": 125000,
        "amount_due": 50000,
        "days_until_due": 11
      }
    ],
    "has_more": true,
    "url": "/v1/invoices"
  }
  ```
</ResponseExample>