Pagination

List endpoints use opaque keyset cursors. Start with your filters, sort, and limit, then follow links.next or pass meta.page.next_cursor unchanged. meta.page.cursor_expires_at appears only when another page exists. The immutable publication revision is returned in the X-Publication-Revision response header; publication time is available through Last-Modified.

let url = new URL('/v1/products', baseUrl);
url.searchParams.set('q', 'bourbon');
url.searchParams.set('limit', '50');

while (url) {
  const response = await fetch(url);
  if (!response.ok) throw await response.json();
  const page = await response.json();

  consume(page.data);
  url = page.links.next ? new URL(page.links.next, baseUrl) : null;
}

Guarantees

Sort order includes a unique stable identifier as a final tie-breaker.
The cursor is bound to its resource endpoint, query, and sort. A product cursor cannot be used to browse brands, stores, or another product’s inventory.
Parameter order and the order of comma-separated set filters do not matter. Search text retains its word order; changing it requires a new traversal. Repeated parameters retain their order as well.
All pages from a cursor chain read one immutable publication revision.
Cursor contents are implementation details and must not be decoded or modified.

Expired or retired cursors return 410. Restart the traversal to see the current publication. Using a cursor with a different endpoint or query returns 400 CURSOR_QUERY_MISMATCH. Start that query without a cursor, or follow the original links.next unchanged. Cursor binding changed during pre-launch development; cursors issued by the earlier implementation must be restarted after upgrading the service.

Get started

Core concepts

Integration guides

Guarantees