API reference
List invoices
Organization invoice list.
GET
/invoicesList invoices in the key's environment, newest first, with cursor pagination.
- Permission
- read:invoices
- Auth
- api-key
- Idempotent
- No
- Language
- Node.js
| Field | In | Type | Required | Description |
|---|---|---|---|---|
| limit | query | integer | No · 50 | 1–100. |
| cursor | query | string | No | nextCursor from the previous page, unchanged. |
| status | query | string | No | One status or a comma-separated list, e.g. paid,payment_detected. |
| chain | query | string | No | Network ID. |
| reference | query | string | No | The checkout session reference stored on the invoice. |
| createdAfter | query | string | No | ISO 8601, inclusive. |
| createdBefore | query | string | No | ISO 8601, exclusive. |
| metadata[key] | query | string | No | Exact metadata match. Repeat for several keys; all must match. |
const response = await fetch(`${process.env.BOSPAY_API_BASE}/invoices?status=paid&metadata[orderId]=1048&limit=20`, {
method: "GET",
headers: {
"Content-Type": "application/json",
"BOSPay-Version": "2026-09-23",
"X-API-Key": process.env.BOSPAY_API_KEY,
}
});
if (!response.ok) {
throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();Success
200
{
"object": "list",
"data": [
{
"id": "inv_1048",
"object": "invoice",
"status": "paid",
"metadata": {
"orderId": "1048"
}
}
],
"hasMore": true,
"nextCursor": "MjAyNi0wOS0yM1QxMDo0MjowMC4wMDBafGludl8xMDQ4"
}Validation error
400
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}