Everyone

GET /api/v1/invoices

List invoices for the authenticated client, with optional status filtering.

Last updated 1776211200

Endpoint

GET /api/v1/invoices

Returns a paginated list of invoices for the authenticated client. Includes invoices in all statuses unless filtered.

Query Parameters

Parameter Type Description
status string Filter by status: unpaid, paid, overdue, cancelled
page integer Page number (default: 1)
per_page integer Results per page (default: 15, max: 100)

Request Examples

List all invoices:

curl "https://billing.example.com/api/v1/invoices" \
  -H "Authorization: Bearer {your-token}"

List unpaid and overdue invoices:

curl "https://billing.example.com/api/v1/invoices?status=unpaid" \
  -H "Authorization: Bearer {your-token}"

curl "https://billing.example.com/api/v1/invoices?status=overdue" \
  -H "Authorization: Bearer {your-token}"

Response

{
  "data": [
    {
      "id": 305,
      "invoice_number": "INV-0305",
      "status": "paid",
      "subtotal": 2000,
      "tax_amount": 200,
      "total": 2200,
      "amount_due": 0,
      "currency_code": "USD",
      "due_date": "2026-04-10",
      "paid_at": "2026-04-08T14:33:10Z",
      "created_at": "2026-04-01T00:00:00Z"
    },
    {
      "id": 306,
      "invoice_number": "INV-0306",
      "status": "unpaid",
      "subtotal": 500,
      "tax_amount": 0,
      "total": 500,
      "amount_due": 500,
      "currency_code": "USD",
      "due_date": "2026-05-01",
      "paid_at": null,
      "created_at": "2026-04-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 38
  }
}

Response Fields

Field Type Description
id integer Unique invoice ID
invoice_number string Human-readable invoice reference
status string unpaid, paid, overdue, or cancelled
subtotal integer Pre-tax total in the smallest currency unit
tax_amount integer Tax amount in the smallest currency unit
total integer Full invoice total including tax (smallest currency unit)
amount_due integer Remaining balance (0 if paid, smallest currency unit)
currency_code string Three-letter ISO currency code
due_date string ISO 8601 date the payment is due
paid_at string ISO 8601 timestamp of full payment, or null if unpaid
created_at string ISO 8601 timestamp when the invoice was created

[!IMPORTANT] All monetary amounts (subtotal, tax_amount, total, amount_due) are in the smallest currency unit. For USD, 2200 means $22.00. Always divide by 100 when displaying two-decimal currencies.

Status Values

Status Meaning
unpaid Invoice has been issued and payment has not been received
paid Invoice has been paid in full
overdue Payment was due in the past and has not been received
cancelled Invoice was voided and will not be collected

[!TIP] To build a "balance due" widget, filter by status=unpaid and status=overdue, then sum the amount_due fields across all results (paginating through all pages if necessary).

Previous
← GET /services — List Services
Next
GET /orders — List Orders →