Making requests to paginated REST Admin API endpoints

Some REST endpoints support cursor-based pagination. When you send a request to one of these endpoints, the response body returns the first page of results, and the response header return links to the next page and the previous page of results (if applicable). You can use the links in the response header to iterate through the pages of results.

Link headers use the following syntax:

#...
Link: "<https://{shop}.myshopify.com/admin/api/{version}/products.json?page_info={page_info}&limit={limit}>; rel={next}, <https://{shop}.myshopify.com/admin/api/{version}/products.json?page_info={page_info}&limit={limit}>; rel={previous}"
#...

The link header includes a rel parameter, where relation-types describes the relation of the linked page to the current page of results. The value can either be previous or next.

The URL in the link header can include up to two parameters:

  • page_info: A unique ID used to access a certain page of results. The page_info parameter can't be modified and must be used exactly as it appears in the link header URL.
  • limit: The maximum number of results to show on the page.

A request that includes the page_info parameter can't include any other parameters except for limit. If you want your results to be filtered by other parameters, then you need to include those parameters in the first request you make.

Supported endpoints

You can use cursor-based pagination on the following endpoints.

Release 2019-07

Release candidate 2019-10

Make a paginated request and iterate through the pages

When you make a request to an endpoint that supports paginated results, you can set the number of results to return per page using the limit parameter. If you don't specify a limit, then the endpoint will use its default page limit. You can also set other parameters in this request to narrow down your results.

The following example request asks the product endpoint for all products that belong to a collection, with a limit of 3 products per page of results:

Request

GET https://{shop}.myshopify.com/admin/api/2019-07/products.json?limit=3&collection_id=841564295

Response header

#...
Link: "<https://{shop}.myshopify.com/admin/api/2019-07/products.json?page_info=hijgklmn&limit=3>; rel=next"
#...

Response body

{
  "products": [
    {id: 1 ... },
    {id: 2 ... },
    {id: 3 ... }
  ],
}

The response header returns a link header that includes a URL for the next page of results. The response body returns the first page of results, which includes 3 products.

To get the next page of results, you can make a request to the URL stored in the link header of the last response:

Request

GET https://{shop}.myshopify.com/admin/api/2019-07/products.json?page_info=hijgklmn&limit=3

Response header

#...
Link: "<https://{shop}.myshopify.com/admin/api/2019-07/products.json?page_info=abcdefg&limit=100>; rel=previous, <https://{shop}.myshopify.com/admin/api/2019-07/products.json?page_info=opqrstu&limit=100>; rel=next"
#...

Response body

{
  "products": [
    {id: 4 ... },
    {id: 5 ... },
    {id: 6 ... }
  ],
}

The response header includes a link to the previous page of results and a link to the next page. The response body includes the second page of results, which includes the next 3 products after the first page.

You can use the URLs in the link headers to iterate through each page of results. If you make a call to a page and the response header only includes a link to the previous page, then you've reached the last page of results.

Change the number of results for a specific page

You can change the limit in a link header URL to return a different number of results from a specified point. For example, the following example request asks the product endpoint for all products, with a limit parameter of 3:

Request

GET https://{shop}.myshopify.com/admin/api/2019-07/products.json?limit=3

Response header

#...
Link: "<https://{shop}.myshopify.com/admin/api/2019-07/products.json?page_info=hijgklmn&limit=3>; rel=next"
#...

Response body

{
  "products": [
    {id: 1 ... },
    {id: 2 ... },
    {id: 3 ... }
  ],
}

If you change the limit in the URL in the link header to 6 and make a request to that URL, then the response body returns the 6 products after the first page of results:

Request

GET https://{shop}.myshopify.com/admin/api/2019-07/products.json?page_info=hijgklmn&limit=6

Response header

#...
Link: "<https://{shop}.myshopify.com/admin/api/2019-07/products.json?page_info=vwxyzab&limit=6>; rel=next"
#...

Response body

{
  "products": [
    {id: 4 ... },
    {id: 5 ... },
    {id: 6 ... },
    {id: 7 ... },
    {id: 8 ... },
    {id: 9 ... }
  ],
}

Sign up for a Partner account to get started.

Sign up