List & Retrieve Invoices

List all invoices for your organization with filtering and pagination, or retrieve a single invoice by ID.

List Invoices

Query Parameters

Code Examples

import requests

url = "http://localhost:8000/api/v1/invoices"
headers = {
  "Authorization": "Bearer your-api-key"
}

# List all invoices
response = requests.get(url, headers=headers)
invoices = response.json()

# Filter by status
params = {"status": "sent", "limit": 50}
response = requests.get(url, headers=headers, params=params)
sent_invoices = response.json()

# Search for invoices
params = {"search": "Acme", "limit": 20}
response = requests.get(url, headers=headers, params=params)
search_results = response.json()

Response

Returns an array of invoice objects:

[
  {
    "id": "inv_01HXYZ123ABC",
    "number": "INV-2025-0001",
    "customer_name": "Acme Ltd",
    "amount": 120.0,
    "currency": "EUR",
    "status": "sent",
    ...
  },
  {
    "id": "inv_01HXYZ456DEF",
    "number": "INV-2025-0002",
    "customer_name": "Beta Corp",
    "amount": 250.0,
    "currency": "USD",
    "status": "paid",
    ...
  }
]

Retrieve Single Invoice

Path Parameters

Code Examples

import requests

invoice_id = "inv_01HXYZ123ABC"
url = f"http://localhost:8000/api/v1/invoices/{invoice_id}"
headers = {
  "Authorization": "Bearer your-api-key"
}

response = requests.get(url, headers=headers)
invoice = response.json()
print(invoice)

Response

Returns a single invoice object:

{
  "id": "inv_01HXYZ123ABC",
  "organization_id": "org_01HABC456DEF",
  "external_id": "crm-12345",
  "number": "INV-2025-0001",
  "customer_name": "Acme Ltd",
  "customer_email": "[email protected]",
  "customer_wallet": "lnbc1u1p3xyz...",
  "amount": 120.0,
  "currency": "EUR",
  "status": "sent",
  "issued_at": "2025-11-24T10:00:00Z",
  "due_at": "2025-12-01T10:00:00Z",
  "paid_at": null,
  "source": "api",
  "created_at": "2025-11-24T10:00:00Z",
  "updated_at": "2025-11-24T10:00:00Z"
}

Pagination

When listing invoices, use limit and offset for pagination:

• First page: limit=50&offset=0
• Second page: limit=50&offset=50
• Third page: limit=50&offset=100

Continue incrementing offset by limit until you receive fewer results than limit (indicating the last page).

Error Scenarios

404 Not Found

• Invoice ID does not exist (for GET single invoice)
• Invoice belongs to a different organization

401 Unauthorized

• Missing or invalid API key
• API key does not have permission to read invoices

400 Bad Request

• Invalid status filter value
• Invalid limit or offset (negative or too large)

Related Documentation

• Create & Send Invoices
• Invoice Data Model
• Mark Invoice as Paid