Welcome to another edition of API deprecations at Shopify, where we explore the disruptive modifications taking effect across all supported versions. In this edition, we will examine the breaking changes in the oldest supported version as of April 1, 2022: the 2021-07 API version. This is crucial information for developers of private apps. Let’s delve into it.
A Brief Refresher on Versioning
Before we dive into the upcoming changes, let’s revisit how API versioning works at Shopify.
We release a new version every quarter, typically on or around January 1, April 1, July 1, and October 1. Versions are named in a year-month format (e.g., 2022-01). This format ensures easy identification of when the version became stable and allows for easy comparison between multiple versions.
Apps can make requests to a specific version of the API by specifying it in the request URL. This allows apps to be built on a stable version, ensuring a consistent API contract. However, any features released after the targeted version won’t be accessible until the request URL is updated.
We continuously release features to merchants using release candidates. The release candidate is simply the next API version and can be targeted for requests using the year-month format. While the release candidate contains the latest set of features, it is continuously evolving, so it’s not recommended for everyday consumption. We suggest keeping your everyday requests on a stable version and moving specific calls dealing with newly released features to the release candidate.
Apps that do not request a specific version are served the oldest supported version. This mechanism allows existing apps to continue functioning without requiring URL updates. Apps explicitly calling versions that are no longer supported also fall under this provision. Although this prevents all requests from failing after a version switch, it is still recommended to target recent releases intentionally.
Versions are supported for one year to facilitate agility and necessary changes for optimal merchant service. However, this means apps only have nine months to adopt new changes and leverage new features before the old behavior is no longer available.
With this refresher, let’s now review the essential information you need to be prepared for April 1, 2022.
What to Expect on April 1
On April 1, 2022, the following changes will take effect on our APIs for both public and private apps:
The 2022-04 version will become stable and ready for general usage.
The 2021-04 version will become unsupported.
Requests that have been deprecated by changes in the 2021-07 version will cause your app to be flagged. To minimize the impact on merchants, flagged apps will be de-listed from the Shopify App Store, and new installs will be blocked. Additionally, we may notify merchants that your apps are no longer supported.
Shortly afterward, at our discretion:
Requests with no specified API version will be served the 2021-07 version.
Requests for the 2021-04 version will no longer receive that version. Instead, these requests will fall forward to 2021-07.
Webhooks set to the 2021-04 version will also fall forward in the same manner.
Most importantly, the 2021-07 API version, which will become the default version, includes breaking API changes. If your app makes requests that would break in 2021-04, it is crucial to take action and migrate those requests before April 1, 2022. Failure to do so will result in failed requests and a broken app.
Upcoming Breaking Changes
Here are the breaking changes introduced in the 2021-07 version, which will become Shopify’s oldest supported version on April 1, 2022.
Deprecated Field on Metafield Object
The value_type field on the Metafield object has been deprecated. It has been replaced with the type field. Importantly, this deprecation affects both the GraphQL Admin API and the REST Admin API. For more information, please refer to the changelog post, and you can find the list of accepted types in our Metafields documentation.
Deprecated Connection on Shop Object
The GraphQL Admin Shop object has been modified, deprecating the uploadedImages connection. Henceforth, the uploadedImagesbyIds fields should be used to retrieve a list of images by id instead.
Empty Selling Plan Groups
Validation has been added to the sellingPlanGroupUpdate mutation. Selling plan groups with no selling plans will no longer be permitted.
Pricing Policies for Selling Plans
The sellingPlanGroupUpdate mutation has been altered so that the end state of all pricing policies is contained in the input. In other words, the pricing policies for the given selling plan will be overwritten by the values included in the mutation’s input.
This change enables the deletion of pricing policies from a selling plan, which was previously not possible. It is now also possible to remove all pricing policies by including an empty array (pricingPolicies: ) in the input.
Deprecated Field on Shop Resource
The force_ssl field on the REST API Admin’s Shop resource has been removed. Since all requests now use HTTPS, force_ssl is always true. This field has also been removed from the shop/update and app/uninstalled webhook topics.
Explicit User Permissions
The permissions property of the REST API Admin’s User resource now returns a complete list of permissions for a user with full permissions.
Get Ready for April 1, 2022
To ensure preparedness for the changes to the Shopify platform, the following resources can be beneficial:
API health report: A per-app health report in the Partner Dashboard that showcases the exact API changes affecting your app.
Email: Keep your developer contact email up-to-date to receive timely notifications about pending changes.
Deprecation headers: In your app, requests that are deprecated and will be unsupported within nine months will have the X-Shopify-API-Deprecated-Reason header added.
Developer changelog: Stay up to date with recent changes to Shopify’s APIs and other developer products.
Deprecated API calls endpoint: Private apps can access their API health information through this endpoint.
Check out the 2022-04 release notes for the full set of new features. You can also visit your Partner Dashboard to see which changes may affect you or subscribe to our monthly “What’s New for Shopify Developers and Partners” newsletter.
Remember, it’s crucial to adapt and migrate your app’s requests before April 1, 2022, to avoid failed requests and maintain optimal functionality.
Make sure to stay informed, stay prepared, and embrace the exciting changes coming to Shopify.