Stay up to date

Developer changelog

API

Page-based pagination replaced by cursor-based pagination across multiple REST endpoints

Effective August 14, 2019

Action required

Update

Being able to communicate quickly and reliably with the Shopify APIs is of the utmost importance to our development community. To aid in these areas we've added cursor-based pagination and removed page-based pagination on many REST API resources.

Cursor-based pagination introduces a more efficient way to paginate through resources, resulting in quicker and more efficient API calls.

How does it work?

Inside of Shopify, we support two types of relative pagination: using a since_id, and following URLs from the Link header in the response. The linked resources below discuss both types with examples, but since since_id existed on all endpoints prior to version 2019-07 we'll discuss using the Link header below.

When you send a request to an endpoint that supports cursor-based pagination, the response body returns the first page of results, and the Link 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.

The link header includes a rel parameter, where relation-types describes the relation of the linked page to the current page of results, this 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.

To learn more about using cursor-based pagination in the REST API see our guide on pagination and our blog post How to Use Relative Pagination In Your Application.

Do I need to update my app?

If you are using the legacy page parameter in order receive paginated data from the Shopify REST API, you will need to update to cursor-based pagination. If you are using the shopify_api ruby gem, it has been updated to support cursor-based pagination.

Affected API Endpoints

These changes were released in two parts; Many endpoints were updated with the release of the 2019-07 version on July 1st 2019, and others today for the 2019-10 version. Visit the release notes of the specific versions for more details on the affected endpoints: