Pagination

Thor uses cursor-based GraphQL connections. A connection contains nodes or edges, a pageInfo object, and—when requested—totalCount. Page sizes are limited to 100 items.

Forward pagination

Request the first page with first. If hasNextPage is true, pass the returned endCursor as after on the next request.

Keep the query, filters, sort direction, sort key, and Storefront context unchanged while walking the connection. A cursor identifies a position in that exact result ordering; it is not a reusable resource ID.

Backward pagination

To move backward, request last items before a cursor with before. Use the previous response’s startCursor and continue while hasPreviousPage is true.

Do not combine first with last, or after with before, in a normal page request. Forward and backward traversal are two directions over the same ordered connection.

Nodes, edges, and total count

  • Use nodes when you only need the resources.
  • Use edges { cursor node { ... } } when the cursor for each individual item is useful.
  • Request totalCount only when the UI needs an exact total. It can require additional work compared with reading one page.
  • pageInfo exposes hasNextPage, hasPreviousPage, startCursor, and endCursor.

Reliability rules

  1. Always set first or last; use a value no greater than 100.
  2. Treat cursors as opaque strings. Store and return them unchanged; do not decode or construct them.
  3. Keep sorting, filters, search query, locale, store, publication channel, price channel, currency, country, preview state, and shopper context stable between pages.
  4. Restart from the first page after changing any of those inputs.
  5. Expect live data mutations to move items between pages. For exports or other consistency-sensitive jobs, use a purpose-built export workflow rather than assuming a long-running connection is a database snapshot.