Skip to main content
GET
List invoices

Authorizations

Authorization
string
header
required

Server API key, scoped. pk_test_ keys hit the sandbox tenant.

Headers

X-Request-Id
string

Optional client correlation id, up to 128 characters. It is not echoed: the response's X-Request-Id is always our own req_… id. We log your value with the request as client_request_id, so support can find a request by either id. A longer value is refused with 400 parameter_invalid.

Maximum string length: 128

Query Parameters

limit
integer
default:25

Page size, 1–100.

Required range: 1 <= x <= 100
after
string

Cursor from the previous page's next_cursor. Returns older items. Don't send with before.

before
string

Cursor for the reverse direction: returns the items newer than this one. The page is still sorted newest first; has_more and next_cursor then continue in the same (newer) direction, so pass next_cursor as before to keep paging towards the newest items. Don't send with after.

q
string

Search invoice number, customer name or email.

Maximum string length: 200
status
enum<string>[]

Comma-separated invoice statuses.

Invoice state (not a money movement; see CONVENTIONS §8 note in docs/discrepancies). draft → sent → partially_paid → paid; sent / partially_paid → overdue after due_on while money is still owed (an overdue invoice can have part payments; see amount_paid); draft / sent / partially_paid / overdue → void. UI labels: sent → "Awaiting payment", partially_paid → "Part paid".

Available options:
draft,
sent,
partially_paid,
overdue,
paid,
void
customer_id
string

Only this customer's invoices.

due_on_gte
string<date>

Due on or after this date. Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

due_on_lte
string<date>

Due on or before this date. Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

created_gte
string<date-time>

Only items created at or after this time.

created_lte
string<date-time>

Only items created at or before this time.

include
enum<string>

Set to total_count to add total_count to the list response.

Available options:
total_count

Response

A page of invoices. List items omit activity.

Cursor page. Domain files compose this with allOf and set data.items.

object
string
required
Allowed value: "list"
data
object[]
required

Items, newest first.

has_more
boolean
required

True when another page exists.

next_cursor
string | null

Cursor for the next page in the same direction: pass it as after if this page was read with after (or no cursor), as before if it was read with before. Null when has_more is false.

total_count
integer

Only when include=total_count was sent.