Pagination and filtering
Cursor pagination and the filtering contract for collection reads.
Collection reads return a JSON array in data. Cursor-based pagination is supported where the endpoint documents it; endpoints that do not paginate return all matching results in a single response with has_more: false. Filtering narrows a collection using the endpoint's canonical field names. This page fixes the wire contract for both.
Requesting a page
A paginated collection endpoint accepts two canonical query parameters:
| Parameter | Meaning |
|---|---|
limit | Maximum number of items to return in this page. Default and maximum values are published in Reference. |
cursor | Opaque continuation token from a previous response's meta.pagination.next_cursor. Omit it to request the first page. |
Rules:
cursoris opaque. Clients MUST NOT construct, parse, or mutate its contents.- A
cursoris scope-bound to the exact filter set and ordering of the request that produced it. To continue a result set, replay the same filters and pass the cursor unchanged. Sending a malformed or scope-incompatible cursor is rejected asVALIDATION_ERROR. - Both parameters are sent only on endpoints that support pagination. An unpaginated list still returns
dataas an array.
Reading the response
Pagination state is surfaced only through meta.pagination, and only on a paginated collection result:
{
"ok": true,
"data": [ {} ],
"error": null,
"meta": {
"result_type": "collection",
"pagination": {
"next_cursor": "opaque-token-or-null",
"has_more": true
}
}
}| Field | Type | Rules |
|---|---|---|
next_cursor | string | null | The token to pass as cursor for the next page. MUST be null when no continuation exists. |
has_more | boolean | true only when a further page is available under the same query scope; otherwise false. |
Drive iteration off these fields: pass next_cursor back as cursor while has_more is true, and stop when has_more is false (at which point next_cursor is null). Do not infer the end of a result set from page size alone.
Empty results
A collection that matches nothing is still a success: 200, ok: true, and data: []. An empty list MUST NOT be returned as a 404. Singleton absence is the distinct NOT_FOUND case — see Conventions and Errors.
Filtering
Filters narrow a collection using the canonical field names documented for that endpoint — for example merchant_id, payment_intent_id, or a lifecycle-state field. The exact filter set is per endpoint.
- Filter parameter names MUST be the exact canonical names. The API does not accept aliases or abbreviations.
- An unknown query parameter — including a filter the endpoint does not define — is rejected as
VALIDATION_ERROR(400). Do not send parameters outside the endpoint's documented contract. - A filter combination that matches no rows is an empty collection, not an error.