# List invoices

Retrieve a paginated list of invoices. Non-staff users only see their organization's invoices, while staff users can see all invoices.

#### Query Parameters

**`skip`** integer optional

Number of invoices to skip (offset). Defaults to 0.

**`limit`** integer optional

Maximum invoices per page (1-100). Defaults to 50.

**`organization_id`** string optional

Filter by specific organization (format: `org_<uuid>`). Staff only - non-staff users will receive a 403 error if attempted.

**`status`** string optional

Filter by invoice status. Valid values: `draft`, `issued`, `paid`, `overdue`, `cancelled`.

**`year`** integer optional

Filter by invoice year (2024-2100).

**`month`** integer optional

Filter by invoice month (1-12).

## Returns

Returns a paginated list of invoice objects with pagination metadata.

### Response Fields

**`invoices`** array

Array of invoice objects (without items for brevity).

**`total`** integer

Total number of invoices matching the query.

**`skip`** integer

Number of invoices skipped.

**`limit`** integer

Maximum invoices per page.


```bash
# Basic list with pagination
curl "https://api.aitronos.com/v1/invoices?skip=0&limit=50" \
  -H "X-API-Key: $FREDDY_API_KEY"

# Filter by organization (staff only)
curl "https://api.aitronos.com/v1/invoices?organization_id=org_123e4567e89b12d3a456426614174000" \
  -H "X-API-Key: $FREDDY_API_KEY"

# Filter by status
curl "https://api.aitronos.com/v1/invoices?status=paid" \
  -H "X-API-Key: $FREDDY_API_KEY"

# Filter by year and month
curl "https://api.aitronos.com/v1/invoices?year=2024&month=11" \
  -H "X-API-Key: $FREDDY_API_KEY"

# Combine filters
curl "https://api.aitronos.com/v1/invoices?organization_id=org_123e4567e89b12d3a456426614174000&status=issued&year=2024&skip=0&limit=20" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

# Basic list with pagination
response = requests.get(
    "https://api.aitronos.com/v1/invoices",
    headers={"X-API-Key": api_key},
    params={"skip": 0, "limit": 50}
)

data = response.json()
print(f"Total invoices: {data['total']}")
for invoice in data['invoices']:
    print(f"{invoice['invoice_number']}: CHF {invoice['total_amount']}")

# Filter by organization (staff only)
response = requests.get(
    "https://api.aitronos.com/v1/invoices",
    headers={"X-API-Key": api_key},
    params={"organization_id": "org_123e4567e89b12d3a456426614174000"}
)

# Filter by status and date
response = requests.get(
    "https://api.aitronos.com/v1/invoices",
    headers={"X-API-Key": api_key},
    params={
        "status": "issued",
        "year": 2024,
        "month": 11
    }
)
```


```javascript
// Basic list with pagination
const response = await fetch(
  "https://api.aitronos.com/v1/invoices?skip=0&limit=50",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

const data = await response.json();
console.log(`Total invoices: ${data.total}`);
data.invoices.forEach(invoice => {
  console.log(`${invoice.invoice_number}: CHF ${invoice.total_amount}`);
});

// Filter by organization (staff only)
const orgResponse = await fetch(
  "https://api.aitronos.com/v1/invoices?organization_id=org_123e4567e89b12d3a456426614174000",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

// Combine filters
const params = new URLSearchParams({
  status: "issued",
  year: "2024",
  month: "11",
  skip: "0",
  limit: "20"
});

const filteredResponse = await fetch(
  `https://api.aitronos.com/v1/invoices?${params}`,
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);
```

**Response:**

200 OK

```json
{
  "invoices": [
    {
      "id": "inv_123e4567e89b12d3a456426614174000",
      "invoice_number": "INV-2024-12-AIT-001",
      "organization_id": "org_123e4567e89b12d3a456426614174000",
      "organization_name": "Aitronos AG",
      "billing_period_start": "2024-12-01T00:00:00Z",
      "billing_period_end": "2025-01-01T00:00:00Z",
      "issue_date": "2024-12-31T23:59:59Z",
      "due_date": "2025-01-30T23:59:59Z",
      "payment_date": null,
      "currency": "CHF",
      "exchange_rate": 1.0,
      "subtotal": 1250.50,
      "tax_rate": 0.081,
      "tax_amount": 101.29,
      "total_amount": 1351.79,
      "status": "issued",
      "items": [],
      "created_at": "2024-12-31T23:59:59Z",
      "updated_at": "2024-12-31T23:59:59Z"
    }
  ],
  "total": 42,
  "skip": 0,
  "limit": 50
}
```

401 Unauthorized

```json
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required",
    "system_message": "Missing or invalid authentication token",
    "type": "client_error",
    "status": 401,
    "details": {},
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```

403 Forbidden

```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You don't have permission to filter by organization",
    "system_message": "Only staff can filter by organization_id",
    "type": "client_error",
    "status": 403,
    "details": {
      "required_role": "aitronos_staff"
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```

422 Unprocessable Entity

```json
{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid query parameters",
    "system_message": "Validation error",
    "type": "client_error",
    "status": 422,
    "details": {
      "field": "month",
      "value": 13,
      "valid_range": "1-12"
    },
    "trace_id": "2fbbf3b6-51a1-4f1b-88e2-c00e8b52fbb8",
    "timestamp": "2025-11-26T08:21:45Z"
  }
}
```