Skip to main content
Use cursors to page through any list in the v3 API. List fields are connections, which follow the Relay connection pattern. Any field whose type ends in Connection (for example ProductConnection) is paginated.

Connection shape

Every connection exposes nodes, edges, and pageInfo: PageInfo contains: When a list has no results, startCursor and endCursor are null.

Paging forward

Pass first to set the page size and after to continue from a cursor:
To fetch the next page, send endCursor from the previous response as after:
Send the cursor in variables, exactly as you received it:
Keep requesting while pageInfo.hasNextPage is true. Follow hasNextPage, not the number of items. Some connections, such as customers, can return a page with fewer items than you asked for, or none, while hasNextPage is still true. Keep paging with endCursor.

Page size

first and last accept 1 to 100. A connection requested without either returns 25 items. A page size outside that range returns HTTP 400. analyticsReportRows is the exception: it accepts 1 to 500 and returns 100 rows by default. Page size also sets query cost. See Rate limiting.

Paging backward

Pass last and before (a startCursor from a previous page) to page toward the start of the list, and keep requesting while pageInfo.hasPreviousPage is true. Do not combine first/after with last/before in one request. See Pagination errors.

Sorting

Many connections accept orderBy (a sort key enum, such as ProductSortKey) and reverse to flip the direction. Each connection has a default sort. For products, it is CREATED_AT, newest first, so this query returns the oldest products first:
Cursors encode the sort position, so always keep orderBy and reverse consistent across pages of the same list. See Pagination errors.

Pagination errors

These requests return HTTP 400:
  • A malformed cursor.
  • A cursor sent with a different orderBy or reverse than it came from.
  • first/after combined with last/before.
  • A page size outside the allowed range.
A bad cursor sets extensions.code to INVALID_CURSOR, and mixed directions set INVALID_PAGINATION. A few older lists return a message and no code, so check the HTTP status first and read extensions.code when it is present. See Errors.