[Updated] API Deprecations and Versions at Shopify: What You Need to Know

Before we introduced API versioning at Shopify in April 2019, apps could only interact with the latest and greatest form of our APIs. As we released features to merchants, the APIs tied to these features also evolved, and apps had to quickly adapt to the new way of doing things to ensure they kept working.

This developer experience was not ideal. It wasn’t obvious how to find out if your app would break on any given day, and these changes would totally overtake your own development roadmaps. To solve this, we introduced API versioning to provide stability and a scheduled cadence to our releases.

As we near the one-year mark of shipping versioning, let’s review how it all works, and what you need to look out for in 2020.

How versioning works

To get started, let’s recap the fundamentals of API versioning at Shopify.

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 (eg. 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 choose a stable version to build on 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 the concept of the release candidate. The release candidate is simply the next API version, and can be targeted for requests using the same year-month format. In it, you’ll find the latest set of features that have just been released. Since the release candidate is continuously evolving, you should avoid using it 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 that you only move 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 allows 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-07 after it has become unsupported, you will be served the oldest supported version, which would be 2019-10.

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 1 year, this means that apps actually only have 9 months to adopt these new changes and take advantage of new features before the old behavior is no longer available.

Now that we’ve gone over the basics of how API versioning works at Shopify, let’s review some key information you need to know for 2020.

You might also like: How to Get More App Downloads in the Shopify App Store.

Unsupported versions

This means that on April 1, 2020, the following changes will come into effect on our APIs:

• The 2020-04 version will become stable and ready for general usage.

Then on July 2, 2020, the following will happen:

• The 2019-04 and 2019-07 versions will become unsupported.
• Requests with no API version specified will be served the 2019-10 API version.
• Requests for the 2019-04 or 2019-07 versions will no longer receive those versions. Instead, these requests will fall forward to 2019-10.
• Webhooks set to 2019-04 or 2017-07 will fall forward in the same manner.

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

To minimize merchant impact, if your apps continue to use unsupported APIs after July 2, Shopify may notify merchants that your apps are no longer supported. In some cases, we may de-list apps from the Shopify App Store.

Please note that this deprecation does not affect private apps.

Let’s dive into each of the breaking changes introduced between 2019-04 and 2019-10.

Breaking changes

Below are each of the breaking changes being introduced in April. If your app uses any of the below, you’ll want to update to avoid your app breaking.

1. Pagination

Page-based pagination has been removed, and has been replaced with cursor-based pagination.

Our engineering team wrote about the ins and outs of this change, and how to migrate your calls. You can read more about the reasoning on our engineering blog, and about relative pagination in general in this great blog post from Partners.

The takeaway: Stop using the page parameter. Use page_info instead.

2. Featured field removed from Collects

The featured field was removed from the collects endpoint.

Even if you aren’t using this specific field, REST returns everything by default. Because of this, you’ll receive notifications about this deprecation when using the collect endpoint. 

The takeaway: Update your request URL to API version 2019-07 or later. 

3. GraphQL Admin ID added to webhooks

We added the graphql_admin_id to webhook payloads, to make it easier to make GraphQL calls in response, and to be more consistent with our REST payloads. This caused issues in older versions of Rails apps. Even if you aren’t using Rails, it’s good practice to periodically keep your webhook API version up to date to ensure your payloads don’t change when your current version becomes unsupported.

The takeaway: Update your webhook API version to API version 2019-07 or later.

4. Changes to Delivery Profiles

The activatedCarrierServices field isn't compatible with multiple origin shipping, and has been removed.

Use the availableCarrierServices field instead. It includes both the carrier service and applicable countries.

The takeaway: Start using availableCarrierServices if you need information about carrier services.

5. Inventory

In March of 2018, directly modifying inventory on variants was deprecated. In 2019-10, we will remove support for legacy inventory behavior on all apps.

This means that apps will not be able to set inventory_quantity or inventory_quantity_adjustment directly on product variants. Apps will also not be able to create fulfillments without specifying a location_id, or refund and restock without specifying a location_id.

The takeaway: Migrate to support multiple locations.

Stay on top of changes

Knowing about upcoming changes is a good start, but in many cases, it can be difficult to identify individual breaking requests within your whole app. To help narrow these down, we’ve introduced the following tools that automatically generate data based on your API usage.

1. API Health

Your Partner Dashboard contains a per-app API Health report, which showcases the exact changes that will affect you. In it, you’ll find the specific endpoints, links to migration guides, and last detected timestamps of deprecated requests. 

2. Deprecation headers

Within your app, you should also monitor incoming changes by logging the presence of the X-Shopify-API-Deprecated-Reason header. This header is added to requests that are deprecated and that will be unsupported within 9 months. You should update your request as per the link returned in the header.

3. Email

Every app has an associated emergency developer email that we use to notify you about pending deprecations. In these emails, you’ll find information that is very similar to the API Health report. Since private apps aren’t associated with a partner account, this is the main way these types of apps have of being notified about changes that will affect them.

Get ready for July 2, 2020

We recognize that every change we bring to the platform is an effort we’re asking of our partners. With versioning, we’ve hopefully made that process more predictable, and a little less chaotic. 

This July, ensure your apps are ready for our first-ever version deprecation, where we bid farewell to 2019-04 and 2019-07, and where 2019-10 will become the oldest supported version. 

Check out the 2019-10 release notes for the full set of changes, or your Partner Dashboard to see which changes affect you.