Pagination and syncing

Pages

Lists answer one page at a time, newest first:

{
  "object": "list",
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0xMFQwODoxNTowMC4wMDAwMDArMDA6MDAiLCJpZCI6Ii4uLiJ9"
}

limit sets the page size, from 1 to 250 (default 50).
cursor fetches the next page: pass next_cursor from the page you have, unchanged.
The last page has has_more: false and next_cursor: null.

Cursors are opaque: don't build or change them. A deep page costs the same as the first.

Time filters

Every list takes these, as ISO 8601 times with a time zone (2026-11-10T08:15:00Z):

Parameter	Includes
`created_at_min`	created at or after this time
`created_at_max`	created before this time
`updated_at_min`	changed at or after this time
`updated_at_max`	changed before this time

Min is inclusive and max exclusive, so consecutive windows neither miss nor repeat anything.

updated_at changes when anything about the object changes, including its parts:

a product: its variants, images, options, categories or collections;
an order: its lines, payments, shipment or returns;
a customer: their addresses or tags.

Syncing changes

To keep another system up to date:

Remember when your last sync started (not finished).
Fetch everything changed since then: GET /v1/orders?updated_at_min=<that time>, following next_cursor to the end.
Save each object by its id. Seeing the same object twice is fine.
Store the new start time for next time.

Lists page by creation time, so an object changed while you are paging stays where it was. The change is picked up by the next sync.

For changes within seconds, use webhooks, and run this sync every hour or so as a safety net.