Welcome to another edition of API deprecations at Shopify, where we dive into the breaking changes coming into effect for all supported versions. In this post, we’ll look back at the breaking changes shipped in January 2020, which becomes the oldest supported Shopify API version on October 1st, 2020.
Use this article as a guide to prepare for the coming changes, so your app continues to function properly for users ahead of Black Friday/Cyber Monday (BFCM).
If you’d like to see a live explanation and demo of these changes, you can check out the video below:
A quick refresher on versioning
Before we dive into the changes headed your way, let’s revisit howAPI versioning at Shopifyworks.
1. We release a version every quarter
Typically, these releases happen on or around January 1st, April 1st, July 2nd, and October 1st. Versions are named in a year-month format (e.g. 2020-01), ensuring that it will always be easy to identify the time the version became stable, as well as compare the timelines of multiple versions.
2. Apps make requests to a specific version of the API by specifying it in the request URL
While the Shopify APIs continuously evolve, apps can be built on a stable version to ensure that the API contract remains constant. Keep in mind that this means that any features released after your targeted version won’t be accessible until you update your request URL.
3. We release features to merchants continuously
To ship features without affecting the latest stable APIs, we use release candidates. The release candidate is simply the next API version, and can be targeted for requests using the same year-month format. In the release candidate, you’ll find the latest set of features that have just been released. However, since it’s continuously evolving, you should avoid using the release candidate for your app’s general everyday consumption of the API.
To have both the benefit of stability and access to the latest features, we recommend keeping your app’s everyday requests on a stable version, and only moving specific calls that deal with newly released features to the release candidate.
4. Apps that do not request a specific version are served the oldest supported version
This allowed existing apps to continue functioning when we shipped versioning, without having to update to the new URLs. This concept also applies to apps explicitly calling versions that are no longer supported.
For example, if your app continues to request 2019-10 after it has become unsupported, you will be served the oldest supported version, 2020-01.
While every app will benefit from this mechanism preventing all of their requests from erroring out after a version switch, we recommend targeting recent releases intentionally.
5. Versions are supported for one year
Removing support for versions allows us to stay agile and make the changes needed to best serve our merchants and the Shopify platform for the long term. While versions are supported for one year, this means that apps actually only havenine monthsto adopt these new changes and take advantage of new features before the old behavior is no longer available.
With this refresher at the top of our mind, let’s review the key information you’ll need to be ready for October 1st, 2020.
You might also like:The Essential List of Resources for Shopify App Development.
What’s happening on October 1st
On October 1st, 2020, the following changes will come into effect on our APIs:
- The 2020-10 version will become stable and ready for general usage
- The 2019-10 version will become unsupported
- Requests that have been deprecated by changes in 2020-01 will cause your app to be flagged. To minimize merchant impact, Shopify will de-list flagged apps from the Shopify App Store and block new installs. Additionally, we may notify merchants that your apps are no longer supported.
Shortly afterward, at our discretion:
- Requests with no API version specified will be served the2020-01 version.
- Requests for the 2019-10 version will no longer receive that version. Instead, these requests will fall forward to2020-01.
- Webhooks set to 2019-10 will fall forward in the same manner.
Most importantly, the 2020-01 API version, which will become the default version, includes breaking API changes.If your app is making requests that would break in 2020-01, you need to take action and migrate those requests before October 1st, 2020. Failure to do so will result in failed requests and a broken app.
Now, let’s dive into each of the breaking changes introduced in 2020-01.
Build apps for Shopify merchants
Whether you want to build apps for the Shopify App Store, offer custom app development services, or are looking for ways to grow your user base, the Shopify Partner Program will set you up for success. Join for free and access educational resources, developer preview environments, and recurring revenue share opportunities.
Sign upUpcoming breaking changes
Below are the breaking changes introduced in 2020-01, which will become Shopify’s oldest supported version on October 1st.
1. Smart Collects removed from Collects API
The Collections API was redesigned to offer more effective and performant endpoints. As part of this transition, the Collects API stopped including “Smart Collects”. These Smart Collects have moved over to the new Collections API, available both via REST and GraphQL.
The takeaway:Use the new Collections API for all your collection needs. This is especially important if you deal with Smart Collections. If you attempt to get Smart Collection info via the Collects API, you’ll get incorrect results or a 404 error.
Learn more in thedeveloper changelog.
2. GraphQL Input objects limited to 250 items
On all connections, we already limit the maximum number (either byfirst:numorlast:num) of returned results to 250. This change simply extends this limit to input arguments.
The takeaway:你再也不能通过无限长输入the API. Divide your requests into smaller, more manageable sizes.
Learn more in thedeveloper changelog.
You might also like:Faster Retrieval of Shopify Metafields with GraphQL.
Get ready for October 1st, 2020
我们认识到,每一个改变我们带给中国人民解放军tform is an effort we’re asking of our developers and partners. With versioning, we’ve hopefully made that process more predictable and a little less chaotic. The following resources can help you stay on top of changes to the Shopify platform:
- API health report: A per-app health report in thePartner Dashboardthat showcases the exact API changes that will affect you
- Email: Ensure your developer contact email is up-to-date so we can notify you about pending changes
- Deprecation headers: In your app, the
X-Shopify-API-Deprecated-Reasonheader is added to requests that are deprecated and will be unsupported within nine months - Developer changelog: Stay up to date with the recent changes to Shopify’s APIs and other developer products
Or, subscribe to our monthly What’s New for Shopify Developers and Partners newsletter below.
Stay in the know
Subscribe to receive What's New with Shopify, our monthly email featuring Shopify's latest product news.
This October, ensure your apps are BFCM ready with these performance enhancements by migrating to 2020-01 or later.
Check out the2020-10 release notesfor the full set of new features, or yourPartner Dashboardto see which changes affect you.
Sign up for our Developer Digest Newsletter
Stay up to date with the recent changes to Shopify APIs and other developer products with our quarterly Developer Digest.
Sign up