Pagination

When list endpoints arrive

They will accept these query parameters:

Parameter	Type	Default	Meaning
`cursor`	string	`null`	Opaque pagination cursor. Pass `next_cursor` from the previous response.
`limit`	int	`25`	Items per page. Max `100`.

And return:

{
  "data": [
    { "transaction_id": "txn_...", "...": "..." },
    { "transaction_id": "txn_...", "...": "..." }
  ],
  "next_cursor": "eyJpZCI6IjY3MDdiMzNmIiwidHMiOjE3NDA5MzcyMDB9",
  "has_more": true
}

When has_more is false, next_cursor is null and there are no more pages.

Why cursor, not offset

Offset-based pagination has well-known problems:

It double-counts or skips rows when new data is inserted between page fetches.
Performance degrades for large offsets — the database has to walk past every skipped row.

Cursor-based pagination encodes the position into an opaque token the gateway issues. New data inserted ahead of your cursor doesn’t shift your iteration; new data inserted behind it does the right thing on the next page.

What you should NOT do

Don’t parse the cursor. It’s an opaque base64 blob whose format may change in v2 without notice. Treat it as a string.
Don’t increment limit indefinitely. The gateway caps at 100 per request and returns 400 for higher values.
Don’t rely on response order beyond what the endpoint documents. When endpoints document an order (typically created_at desc), it’s a contract; otherwise, no.

Pagination

When list endpoints arrive

Why cursor, not offset

What you should NOT do

See also