Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 55 ยท Admin GraphQL API

Pagination with Cursors

Page through Shopify Admin GraphQL connections with first, after, pageInfo and cursors, choose sort keys, go in reverse, and test a paginator on mock data.

No store has only ten products, and no app can ask for all of them at once. Every list in the Admin GraphQL API is a connection: a window onto a longer list, plus the information you need to move that window forward. The mechanism is cursor-based pagination, and nearly every real app (catalog syncs, order exports, customer imports) is built on a loop around it.

This lesson explains the arguments and the fields you use, how sort keys and reverse change the order, what edges and nodes are for, why offsets do not exist, and how to write a loop that cannot get stuck. The examples target Admin API version 2026-07. Real requests are read-only here because they need a live shop; the runnable paginator is a stand-in that works on mock data in memory. You will use the same loop in Querying Products and Variants and in nearly every later lesson.

Forward paging: first and after

The simplest request asks for a page of a given size:

GRAPHQL
query Page($after: String) {
  products(first: 50, after: $after, sortKey: ID) {
    nodes {
      id
      title
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

The first call sends no after (or null). The response includes pageInfo.endCursor, an opaque string that marks the end of the page you just received. To get the next page you send the same query with after set to that cursor. You stop when hasNextPage is false.

JSON
{ "after": "eyJsYXN0X2lkIjoxMDUwLCJsYXN0X3ZhbHVlIjoxMDUwfQ==" }

That value looks like Base64, and it often is, but you must treat it as opaque. Its contents, format and lifetime are not part of the API contract. Never build a cursor yourself, never parse one, and do not store one for days and expect it to keep working. Store the cursor only for the duration of one job, and resume from the last good page if the job fails.

The maximum page size is 250 for most connections, and a smaller page costs fewer points (see Rate Limits and Query Cost). A page of 50 to 100 is a good default. Larger pages mean fewer round trips but a bigger risk of throttling and slower individual responses.

Pagination in both directions

Connections also accept last and before, which walk backwards from the end:

GRAPHQL
query LastPage($before: String) {
  products(last: 20, before: $before) {
    nodes { id title }
    pageInfo {
      hasPreviousPage
      startCursor
    }
  }
}

The pairs go together: first with after uses hasNextPage and endCursor; last with before uses hasPreviousPage and startCursor. Do not mix a forward argument with a backward one in the same request. Most apps only ever page forward; the backward form is mainly useful for "previous page" buttons in an admin screen.

flowchart LR
    A["Request 1<br/>first: 3"] --> B["Items 1-3<br/>endCursor = c3"]
    B --> C["Request 2<br/>first: 3, after: c3"]
    C --> D["Items 4-6<br/>endCursor = c6"]
    D --> E["Request 3<br/>first: 3, after: c6"]
    E --> F["Items 7-8<br/>hasNextPage = false"]

Each response hands you the cursor for the next request; the loop ends when hasNextPage is false.

Edges and nodes

A connection exposes the same data in two shapes. With nodes you get a plain list of objects. With edges you get a list of wrappers, each holding a cursor and the node:

GRAPHQL
products(first: 3) {
  edges {
    cursor
    node {
      id
      title
    }
  }
}

Use nodes for almost everything: it is shorter and easier to read. Use edges when you need the cursor of an individual item, for example to resume from the middle of a page, or to remember where a particular record sat in a list. You can ask for both in one query, but then you receive each object twice, so pick one unless you need both.

Sort keys and reverse

Order matters for pagination, because a cursor means "after this item, in this order". Each connection has a sortKey enum with values that depend on the object. For products, common keys are ID, TITLE, CREATED_AT, UPDATED_AT, INVENTORY_TOTAL, VENDOR and PRODUCT_TYPE; for orders you will see CREATED_AT, PROCESSED_AT, TOTAL_PRICE and more. The default is usually ID. Add reverse: true to flip the direction, for example to get the newest products first with sortKey: CREATED_AT, reverse: true.

Choose the key to suit the job:

  • A full export should use ID (stable and unique). Items cannot move around in an ID ordering because IDs never change.
  • An incremental sync can use UPDATED_AT together with a search filter such as updated_at:>2026-06-01. See the search syntax in Querying Products and Variants.
  • A screen for people can use TITLE or CREATED_AT, whichever the user expects.

If you sort by a field that changes while you are paging, an item can jump from an unread part of the list to one you already passed. With UPDATED_AT that is common on a busy store: a product you edit during the scan moves to the end, and you may see it twice. Treat your sync as idempotent: processing the same product twice must be harmless, a rule that Idempotency explains in detail.

Why there are no offsets

If you come from SQL you may look for page: 3 or offset: 100. The Admin API does not offer it, and for good reasons:

  1. It would be slow. Skipping ten thousand rows still means walking past ten thousand rows.
  2. It would be wrong. If a product is added while you read, an offset shifts everything and you either skip or repeat items. A cursor says "after exactly this item", which survives inserts and deletes before it.
  3. It would be expensive to protect. A cursor lets Shopify resume cheaply from an index position.

The trade-off is that you cannot jump to "page 17" directly. If a person needs to jump around a long list, use search filters to narrow the list rather than counting pages.

A loop that always ends

A robust pagination loop does five things: it sends the cursor it was given, it reads pageInfo, it stops on hasNextPage === false, it checks for errors on every response, and it has a guard against a server that keeps saying there is more. Here is the shape in read-only JavaScript (it needs a real adminFetch function that sends the request):

JavaScript
async function fetchAllProducts(adminFetch) {
  const all = [];
  let after = null;
  for (let page = 1; page <= 10_000; page++) {
    const body = await adminFetch(QUERY, { after });
    if (body.errors) throw new Error(JSON.stringify(body.errors));
    const { nodes, pageInfo } = body.data.products;
    all.push(...nodes);
    if (!pageInfo.hasNextPage) return all;
    after = pageInfo.endCursor;
  }
  throw new Error('Pagination guard tripped');
}

Holding everything in an array is fine for thousands of items. For hundreds of thousands, write each page to your database or a file as you go; and for truly large reads, switch to Bulk Operations, which does the paging on Shopify's side.

Try it: a cursor paginator

The stand-in below implements a connection over an in-memory list. Its cursors are Base64 strings, like many real ones, but remember that is an implementation detail. The code supports first/after, sortKey and reverse, and returns pageInfo.

Node.js A cursor paginator over mock data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The loop ends exactly when hasNextPage turns false, and the order follows the sort key. Notice that the sort functions break ties with the id: two products created on the same day need a stable tie-breaker, otherwise the order (and therefore the cursor position) would be ambiguous. Shopify's own orderings solve the same problem for you.

Inserts, deletes and consistency

What if the data changes while you are reading? With ID ordering and after cursors:

  • A product added with a higher ID than your cursor appears later in the scan. You will see it.
  • A product added with a lower ID than your cursor never appears in this scan, but you will find it next time. If you cannot accept that, subscribe to webhooks for new products, as described in Webhooks in Shopify, and use both: the scan for the baseline and webhooks for changes.
  • A product deleted before your cursor does not matter. Cursors are meant to encode a position in the ordering, but do not rely on resuming from a deleted item's cursor across long pauses; restart the scan if a request with an old cursor fails.

Try the three cases yourself with a second stand-in. It scans a list in ID order, 2 items per page, and changes the data between pages. The cursor remembers the last ID seen, so only items after that position show up.

Node.js What a scan sees when data changes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

This is why large apps combine a periodic reconciliation scan with webhooks: neither is perfect alone, and together they converge on the truth.

Common mistakes

  • Parsing or storing cursors long-term. They are opaque, and they can stop working.
  • Ignoring hasNextPage and stopping when a page is smaller than expected. Pages can be shorter than first for other reasons. Trust pageInfo.
  • Sending a changed query with an old cursor. A cursor belongs to the combination of query, filter and sort order it came from. Change any of them and start over.
  • Paging with first: 250 for nested lists. The nested cost multiplies; keep inner pages small.
  • Running paging loops in parallel with the same cursor. The cursor chain is sequential. To parallelize, split the work by filter (for example by date ranges), not by cursor.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you request the page after the one you just received?

    Connections use cursors. The endCursor from the last response marks where the next page starts.
  2. 2. When is it right to use edges instead of nodes?

    Edges wrap every node with its cursor. If you only need the objects, nodes is shorter and easier to read.
  3. 3. Why is sorting by UPDATED_AT during a long export risky?

    An item that changes while you scan moves in the ordering and can reappear after you passed it. ID ordering never moves; with UPDATED_AT, make handlers safe to repeat.
  4. 4. Which statement about cursors is correct?

    The format is not part of the contract, and a cursor is tied to the query and sort order it came from.

Summary

  • Lists are connections: send first and after, read pageInfo.hasNextPage and endCursor, and repeat until there is no next page.
  • last with before walks backwards using hasPreviousPage and startCursor.
  • Use nodes for data and edges when you need each item's cursor.
  • sortKey and reverse define the order; ID is the safest for full scans, and a cursor is valid only for the query and order that produced it.
  • There are no offsets: cursors are faster and stay correct when data changes.
  • Treat cursors as opaque, make processing idempotent, guard your loops, and combine scans with webhooks or bulk operations for large or live data.

Next: Mutations and userErrors.