Pagination

Paging is cursor-based, and the cursor is asymmetric: it goes inside page on the way in and comes back at the top level on the way out.

The loop

1. Send page: { "limit": 50 }. limit is 1–100 and defaults to 50 when omitted; a larger value is clamped down rather than rejected, so a partner sweeping a whole estate gets a slower correct answer instead of a 400 they learn about from a support ticket.
2. Read nextCursor from the top level of the reply.
3. Send it back as page: { "cursor": "<nextCursor>" }.
4. Repeat until nextCursor is absent. Absent means you have the last page.

Why a cursor and not an offset

An offset re-counts the collection on every request, so a row that is inserted or removed mid-scan shifts the window — and the page you fetch next either skips rows or repeats them, silently. A cursor names a position rather than a count, so it cannot do either.

What a cursor does not promise

• It is opaque. Do not parse it, derive one, or store one as a durable bookmark across days.
• Ordering within a window is unspecified, and iteration is not snapshot-stable.

For an exact backfill, do not lean on the cursor for correctness: iterate contiguous [from, to) windows and reconcile on the row's own id. That is idempotent under any interleaving of concurrent writes, which paging alone is not.

Time windows page too

fetchOrders bounds an order's pickup time with from (inclusive) and to (exclusive), and the window is at most 31 days. There is no rolling retention ceiling, so a full warehouse backfill is a loop over windows, with the cursor loop above nested inside each one.