Skip to content
/
List invoices
Last updated

List invoices

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

GEThttps://api.aitronos.com/v1/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"

Response:

{
  "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
}
Previous page
Next page