Invoices

Read and distribute billing documents for an organization. These endpoints use a Bearer JWT and require an organization owner or admin role.

Resolve organizationId and confirm your role from Organization.

Get an invoice

GET /v1/invoice/:invoiceId

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/invoice/inv_7e8b1d40"

{
  "id": "inv_7e8b1d40",
  "organizationId": "org_8f3a2c7e",
  "number": "2026-0042",
  "status": "paid",
  "currency": "EUR",
  "amountDue": 49000,
  "amountPaid": 49000,
  "issuedAt": "2026-05-01T00:00:00Z",
  "dueAt": "2026-05-15T00:00:00Z",
  "paidAt": "2026-05-03T10:21:00Z"
}

Field	Description
number	Human-readable invoice number.
status	draft, open, paid, or void.
currency	ISO 4217 currency code.
amountDue / amountPaid	Amounts in minor units (cents).
issuedAt / dueAt / paidAt	ISO 8601 timestamps; paidAt is null until paid.

List invoices

GET /v1/invoice/organization/:organizationId?page=&limit=&status=&type=&fromDate=&toDate=&minAmount=&maxAmount=&invoiceNumber=&sortBy=&sortOrder=

Returns the invoices for an organization, newest first, paginated. Use the filters to narrow by status, type, date range, or amount.

Parameter	Type	Description
page	integer	1-based page number. Default 1.
limit	integer	Items per page. Default 20, maximum 100.
status	string	Filter by status (draft, open, paid, void).
type	string	Filter by invoice type.
fromDate	string	ISO 8601 start of the issue-date range.
toDate	string	ISO 8601 end of the issue-date range.
minAmount	integer	Minimum amount, in minor units (cents).
maxAmount	integer	Maximum amount, in minor units (cents).
invoiceNumber	string	Filter to a specific invoice number.
sortBy	string	Field to sort by.
sortOrder	string	asc or desc.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/invoice/organization/org_8f3a2c7e?page=1&limit=20&status=paid"

{
  "data": [
    {
      "id": "inv_7e8b1d40",
      "number": "2026-0042",
      "status": "paid",
      "currency": "EUR",
      "amountDue": 49000,
      "issuedAt": "2026-05-01T00:00:00Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 8
}

Page through by incrementing page until page * limit >= total.

Download the PDF

GET /v1/invoice/:invoiceId/pdf

Returns the invoice as a PDF (Content-Type: application/pdf). Write the body to a file.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/invoice/inv_7e8b1d40/pdf" \
  -o invoice-2026-0042.pdf

Send an invoice

POST /v1/invoice/:invoiceId/send

Emails the invoice to the organization's billing contact. Use it to send an invoice for the first time or to re-send one.

curl -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/invoice/inv_7e8b1d40/send"

Errors

Status	Meaning
401	Missing or invalid Bearer token.
403	You are not an owner or admin of the organization.
404	The invoice or organization does not exist.
429	Rate limited, see Rate limits & credits.

Next

• Usage stats, the credit consumption behind the charges.
• Organization, confirm your role and members.
• Billing questions? Contact us.