API Deprecation at Shopify: 2021-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 released in our July 2020 API release, including vital information for developers of private apps.

Important information for private apps

When COVID-19 started, we decided to indefinitely postpone API version deprecations for private apps. The tailored nature of their solutions, as well as the difficulty in notifying a technical contact, made it challenging for merchants to manage the migration of their apps, all while adapting to new ways of selling during the pandemic.

However, as we adjust to a new normal, we want to return all apps to the same versioning timeline. By fully deprecating old versions, Shopify can remove old code paths, leading to a more performant platform experience for everyone.

On April 1st, 2021, private apps will no longer have access to unsupported versions of the API (2019-04, 2019-07, 2019-10, 2020-01 and 2020-04). Requests from private apps that use deprecated behavior will no longer be supported, and will instead follow the same behavior as public apps.

Learn more about breaking changes for private apps

If you’re the developer of a private app, you can read more about the list of breaking changes and how to handle them by reviewing the other articles in this series:

We also recommend visiting our private app information page in the developer documentation to prepare your app for this coming change.

Visit page

A quick refresher on versioning

Before we dive into the changes headed your way, let’s revisit how API versioning at Shopify works.

We release a version every quarter. These releases typically happen on or around January 1st, April 1st, July 2nd, and October 1st. Versions are named in a year-month format (e.g. 2021-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 that 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 1st, 2021.

What’s happening on April 1st

On April 1st, 2021, the following changes will come into effect on our APIs for both public and private apps:

The 2021-04 version will become stable and ready for general usage.
The 2020-04 version will become unsupported.
Requests that have been deprecated by changes in 2020-07 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 the 2020-07 version.
Requests for the 2020-04 version will no longer receive that version. Instead, these requests will fall forward to 2020-07.
Webhooks set to 2020-04 will fall forward in the same manner.

Most importantly, the 2020-07 API version, which will become the default version, includes breaking API changes. If your app is making requests that would break in 2020-07, you need to take action and migrate those requests before April 1st, 2021. Failure to do so will result in failed requests and a broken app.

"If your app is making requests that would break in 2020-07, you need to take action and migrate those requests before April 1st, 2021."

Now, let’s dive into each of the breaking changes introduced in 2020-07.

Upcoming breaking changes

Below are the breaking changes introduced in 2020-07, which will become Shopify’s oldest supported version on April 1st.

1. Allocation method for discounts

We’ve reworked the possible values on discounts that have the target_selection attribute set to explicit. Previously, these discounts were applied to a single line item, and had a value of one. With this change, the allocation methods will instead include each and across.

We've made this change to simplify the discount syntax, as one and across functionally both discount the final price by a set amount.

The takeaway: When reading discounts, you may see an allocation method value of across where you used to see one.

2. ProductVariant images resource removed

In our GraphQL Admin API, the “images” field on the ProductVariant object had been marked as deprecated, since it was replaced by the more aptly named “image” field. This change completes the deprecation process by fully removing the field.

The takeaway: When querying for a ProductVariant’s image in GraphQL, use the “image” field instead.

Get ready for April 1st, 2021

The following resources can help you stay on top of changes to the Shopify platform:

API health report: A per-app health report in the Partner Dashboard that 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-Reason header 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 2021-04 release notes for the full set of new features, your Partner Dashboard to see which changes may affect you, or subscribe to our monthly What’s New for Shopify Developers and Partners newsletter below.