API Pagination

Overview

What it means

API pagination is dividing a large collection of API results into manageable pages instead of returning every record in one response. It affects how merchants retrieve transaction histories, invoices and payouts without missing items.

How it works

Common schemes use a cursor, opaque continuation token, offset or page number. A client follows the returned next-page marker until exhausted while respecting filters, sort order and request limits. Cursor pagination is often safer for rapidly changing datasets, but the provider’s contract determines consistency guarantees.

Understanding the technical details

For financial records, preserve the filters and cursor sequence used during retrieval so the result set can be audited. Cursor-based pages are generally preferable when rows are added during export, though guarantees differ by API. If an export spans many minutes, request a fixed date range or snapshot semantics when supported. Deduplicate each returned row by stable record ID and detect gaps before concluding that payouts or invoices reconcile to zero.

Additional protocol context

Offset pagination can duplicate or skip records when data changes, while cursors can expire or encode sensitive state. Unstable ordering, ambiguous limits, unauthorized totals, and clients that ignore termination conditions create missing data, loops, or excessive load.

Providers should define stable ordering, maximum page size, token lifetime, filter interaction, and consistency expectations. Clients must follow returned continuation values, detect repeats, persist progress, handle expiration, and reconcile important collections rather than assuming one traversal is a snapshot.

Common failures and limitations

New records arriving during offset-based pagination can shift page boundaries and cause duplicates or omissions. Retried pages should be deduplicated by stable IDs. An API returning an empty page does not always mean a query is complete unless its documented pagination signals say so.

Related concepts

Webhook, Webhook Verification, Merchant API Key.

Further reading

Stripe documentation — Pagination.