API Deprecation at Shopify: 2022-04 Edition

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 edition, we'll review the breaking changes in the2021-07API version, the oldest supported version as of April 1, 2022. This includes vital information for developers of private apps. Let's take a look.

A quick refresher on versioning

Before we dive into the changes headed your way, let's revisit howAPI versioning at Shopifyworks.

• We release a version every quarter. These releases typically happen on or around January 1, April 1, July 1, and October 1. Versions are named in a year-month format (e.g. 2022-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.
• 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 this means that any features released after your targeted version won't be accessible until you update your request URL.
• 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.
• 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. 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.
• 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 have nine months to 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 April 1, 2022.

What’s happening on April 1

On April 1, 2022, the following changes will come into 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 in2021-07will cause your app to be flagged. To minimize merchant impact, Shopify will de-list flagged apps from theShopify App Storeand 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 the2021-07 version.
• Requests for the2021-04version will no longer receive that version. Instead, these requests will fall forward to2021-07.
• Webhooks set to2021-04will fall forward in the same manner.

Most importantly, the2021-07API version, which will become the default version, includes breaking API changes. If your app is making requests that would break in2021-04, you need 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

Below are the breaking changes introduced in2021-07, which will become Shopify’s oldest supported version onApril 1, 2022.

Deprecated field on Metafield object

Thevalue_typefield on theMetafieldobject has been deprecated. This has been replaced with thetype字段。重要的是要注意,这deprecation affects both the GraphQL Admin API and the Rest Admin API. More information can be found in the变更后, while the list of accepted types can be found in ourMetafields documentation.

Deprecated connection on Shop object

The GraphQL AdminShopobjecthas been changed such that theuploadedImagesconnection has been deprecated. From now on, theuploadedImagesbyIdsfields should be used to retrieve a list of images by id instead.

Empty selling plan groups

Validation has been added to thesellingPlanGroupUpdatemutation. Selling plan groups with no selling plans will no longer be permitted.

Pricing policies for selling plans

ThesellingPlanGroupUpdatemutation has been changed so that the end state ofallof the pricing policies is contained in the input. That is, the pricing policies for the given selling plan will be overwritten by the values included in the mutation’s input.

This change allows pricing policies to be deleted from a selling plan, which previously was not possible. It is also possible now to remove all pricing policies by including an empty array (pricingPolicies: []) in the input.

Deprecated field on Shop resource

Theforce_sslfield on the REST API Admin’sShop resourcehas been removed. Since all requests now use HTTPS,force_sslis alwaystrue. The field has also been removed from theshop/updateandapp/uninstalledwebhook topics.

Explicit user permissions

Thepermissionsproperty of the REST API Admin’sUser resourcenow returns a complete list of permissions for a user withfullpermissions.

Get ready for April 1, 2022

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, theX-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
• Deprecated API calls endpoint: Private apps can access their API health information via this endpoint.

Check out the 2022-04 release notes for the full set of new features, yourPartner Dashboard看到哪些变化s may affect you, or subscribe to our monthly What’s New for Shopify Developers and Partners newsletter below.