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

# List Invoices

> Returns a paginated list of all invoices, with optional filters.

### Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

### Query Parameters

<ParamField query="client_id" type="string">
  Filter invoices by client UUID.
</ParamField>

<ParamField query="status" type="string">
  Filter by invoice status. One of: `Draft`, `Sent`, `Paid`, `Overdue`, `Cancelled`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of records to return. Default `50`, max `100`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of records to skip. Default `0`.
</ParamField>

### Response

<ResponseField name="data" type="array">
  List of invoice objects.

  <Expandable title="Invoice object">
    <ResponseField name="id" type="string">Invoice UUID</ResponseField>
    <ResponseField name="invoice_number" type="string">Auto-generated invoice number (e.g. `INV-0042`)</ResponseField>
    <ResponseField name="amount" type="number">Total invoice amount</ResponseField>
    <ResponseField name="currency" type="string">3-letter currency code (e.g. `USD`)</ResponseField>
    <ResponseField name="status" type="string">`Draft`, `Sent`, `Paid`, `Overdue`, or `Cancelled`</ResponseField>
    <ResponseField name="due_date" type="string">ISO 8601 date string</ResponseField>
    <ResponseField name="tax_rate" type="number">Tax rate as a percentage (0–100)</ResponseField>
    <ResponseField name="description" type="string">Invoice description (nullable)</ResponseField>
    <ResponseField name="line_items" type="array">Array of line item objects (nullable)</ResponseField>
    <ResponseField name="client" type="object">Embedded client (`id`, `name`, `email`, `company_name`)</ResponseField>
    <ResponseField name="project" type="object">Embedded project (`id`, `name`) — nullable</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Properties">
    <ResponseField name="total" type="integer">Total number of matching records</ResponseField>
    <ResponseField name="limit" type="integer">Page size used</ResponseField>
    <ResponseField name="offset" type="integer">Offset used</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://kliio.app/api/v1/invoices?status=Sent&limit=10" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```js JavaScript theme={null}
  const params = new URLSearchParams({ status: 'Sent', limit: '10' })
  const res = await fetch(`https://kliio.app/api/v1/invoices?${params}`, {
    headers: { Authorization: 'Bearer YOUR_API_KEY' }
  })
  const { data, pagination } = await res.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "inv-uuid-...",
        "invoice_number": "INV-0042",
        "amount": 1500.00,
        "currency": "USD",
        "status": "Sent",
        "due_date": "2025-04-30",
        "tax_rate": 0,
        "description": "Website redesign - Phase 1",
        "line_items": null,
        "client": {
          "id": "c1d2e3f4-...",
          "name": "Alice Johnson",
          "email": "alice@example.com",
          "company_name": "Acme Corp"
        },
        "project": {
          "id": "proj-uuid-...",
          "name": "Acme Rebrand"
        },
        "created_at": "2025-03-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "total": 84,
      "limit": 10,
      "offset": 0
    }
  }
  ```
</ResponseExample>