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

# List Invoices

> Retrieve a paginated list of invoices for your merchant account

# List Invoices

Returns a paginated list of invoices belonging to your merchant account. Supports filtering by status, currency, and date range.

## Query Parameters

<ParamField query="status" type="string">
  Filter by invoice status. One of: `pending`, `confirmed`, `settled`, `expired`.
</ParamField>

<ParamField query="currency" type="string">
  Filter by invoice currency (case-insensitive). Example: `USD`, `EUR`.
</ParamField>

<ParamField query="from" type="string">
  Filter invoices created on or after this date. ISO 8601 format.

  **Example:** `2024-01-01T00:00:00Z`
</ParamField>

<ParamField query="to" type="string">
  Filter invoices created on or before this date. ISO 8601 format.

  **Example:** `2024-01-31T23:59:59Z`
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of results per page. Min: `1`, Max: `100`.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number (1-indexed).
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of invoice objects (same fields as [Create Invoice](/api-reference/invoices/create) response).
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination metadata">
    <ResponseField name="total" type="number">Total number of matching invoices</ResponseField>
    <ResponseField name="page" type="number">Current page (1-indexed)</ResponseField>
    <ResponseField name="limit" type="number">Items per page</ResponseField>
    <ResponseField name="totalPages" type="number">Total number of pages</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  # List all invoices (default pagination)
  curl https://api.settlx.io/api/v1/invoices \
    -H "Authorization: Bearer pk_live_your_api_key"

  # Filter pending invoices from January 2024
  curl "https://api.settlx.io/api/v1/invoices?status=pending&from=2024-01-01T00:00:00Z&limit=50" \
    -H "Authorization: Bearer pk_live_your_api_key"
  ```

  ```javascript Node.js theme={null}
  // List all invoices
  const response = await fetch('https://api.settlx.io/api/v1/invoices', {
    headers: { 'Authorization': 'Bearer pk_live_your_api_key' }
  });
  const { data, meta } = await response.json();

  // With filters and pagination
  const params = new URLSearchParams({
    status: 'settled',
    currency: 'USD',
    from: '2024-01-01T00:00:00Z',
    limit: '50',
    page: '1'
  });
  const filtered = await fetch(`https://api.settlx.io/api/v1/invoices?${params}`, {
    headers: { 'Authorization': 'Bearer pk_live_your_api_key' }
  });
  ```

  ```python Python theme={null}
  import httpx

  client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})

  # List all
  response = client.get("https://api.settlx.io/api/v1/invoices")

  # With filters
  response = client.get("https://api.settlx.io/api/v1/invoices", params={
      "status": "settled",
      "currency": "USD",
      "from": "2024-01-01T00:00:00Z",
      "limit": 50,
      "page": 1
  })

  result = response.json()
  invoices = result["data"]
  total = result["pagination"]["total"]
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
        "amount": "99.99",
        "currency": "USD",
        "status": "settled",
        "description": "Order #1234",
        "expiresAt": "2024-01-15T10:30:00.000Z",
        "webhookUrl": "https://yoursite.com/webhooks/settlx",
        "paymentUrl": "https://api.settlx.io/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "createdAt": "2024-01-15T10:00:00.000Z",
        "updatedAt": "2024-01-15T10:05:00.000Z"
      }
    ],
    "pagination": {
      "total": 142,
      "page": 1,
      "limit": 20,
      "totalPages": 8
    }
  }
  ```
</ResponseExample>