Welcome to the July 2021 edition of our API features roundup, designed to help you understand how you can adopt all the latest changes to improve the quality of your apps and streamline your development experience.
This version includes the Bulk Mutations API, a new API that provides enormous improvements to pushing large amounts of data into Shopify. Also released as a part of 2021-07: Product Variant Bulk APIs, the Files API, expanded support for metafields on the Storefront API, and improvements to international pricing.
The 2021-07 release includes many of the features announced at Shopify Unite this year. Many more announcements, especially around our improvements to the storefront experience, can be found as a part of our All of the Announcements From Shopify Unite 2021 post.
This release also coincides with the removal of version 2020-04, so remember to check your API health report to make sure you're compatible and review the changes coming. For a full list of API changes associated with this version, visit the 2021-07 release notes.
Table of contents
1. Metafield updates
Before this version release, using metafields on the storefront was possible but also time-consuming and inflexible. The only storefront metafields available were product and product variant resources, and you needed to create metafields through the API and hard-code them into themes.
The 2021-07 release comes with major updates to metafields that drastically improve their utility for apps and merchants. Metafield storefront visibility is now supported on articles, blogs, collections, customers, orders, pages, and the shop resource, using the metafieldStorefrontVisibilityCreate mutation to make metafield data visible to Storefront API clients. It's never been easier to share relevant, flexible, and contextual data about each resource with consumers of the Storefront API.
As shown at Shopify Unite, metafield definitions can now be created in the admin, allowing merchants to create metafield templates that can be applied to their products. These definitions are also API-accessible through the GraphQL API. This means that you can now create metafield definitions that show up in-context in the admin, giving merchants the ability to easily add structured metafield data to their products.
Here is an example of a request that creates a metafield definition for display in the admin:
Variables:
The resulting created metafield definition will show up in the admin as highlighted below.
These metafield definitions come with the ability to perform validations on 17 unique types of data, preparing them to be displayed on all compatible themes. This is a huge expansion to metafield utility on storefronts, and we can't wait to see what you build with it.
Learn more about the changes announced as part of Online Store 2.0 in Introducing Online Store 2.0: What it Means For Developers.
2. Bulk Mutation APIs
Last year, we released the Bulk APIs to help apps manage large datasets and prevent them from fully saturating their call limits to fetch data. In this version, we're releasing another related feature that will dramatically improve the experience of working with data on large stores: Bulk Mutation APIs. The Bulk Mutation APIs remove the need to manage your client-side throttle, and allow apps to asynchronously run mutations to import vast amounts of data into Shopify stores.
Shopify's API throttle ordinarily works using a "leaky bucket" algorithm. The throttle gives you a bucket of API calls that you can use instantly, but it takes 20 seconds for the bucket to completely refill if you empty it. This algorithm means that if you need to update a few resources, it's usually preferable to operate synchronously.
You'll notice something about the graph above. If you need to create more than 160 products through the API, it's always faster to use bulk mutations. However, bulk mutations aren't restricted to just products. You can run any mutation asynchronously. Since all Shopify resources use the same throttling mechanism, you'll see a similar trend with any creation or update.
If we expand the timeline further, it's very apparent that if you need to create or update many resources, the Bulk Operations API always pulls ahead.
Bulk mutations run more than twice as fast as synchronous GraphQL mutations and seven times faster than their REST equivalents. If you're looking for ways to update or create Shopify resources more quickly, bulk mutations are the most effective way to interact with the API.
Learn more about the Bulk Mutation APIs in our documentation.
3. Product Variant Bulk APIs
Working with Variants using the Product resource has traditionally had a few pitfalls to try and avoid. In the past, API client intent needed to be inferred based on differences between the state of the product on Shopify and your clients' requests. Shopify would expect any call to the Product API that includes variants to have an up-to-date copy of variant data. In prior API versions, the most common mistake when using the Product API was the accidental deletion of variants by pushing up stale product data.
The Product Variant Bulk APIs include four new mutations that allow clients to explicitly specify variant behavior when they push data into Shopify, rather than the error-prone implicit model.
- The productVariantsBulkCreate mutation allows you to create new variants for any product without needing to include all of the existing variant data as a part of your request.
- Using productVariantsBulkUpdate, you can update multiple variants explicitly, and leave out the variants that you’re not updating without fear of them being deleted.
- The productVariantsBulkDelete mutation allows you to specify a list of variants to delete on a product.
- The productVariantsBulkReorder mutation facilitates the reorganization of variants on a product with a single request.
The Product Variant Bulk APIs are the best way to safely, efficiently, and synchronously interact with product variant data without facing the risk of deleted variants due to stale app data.
4. Files API
One of the most requested features by the community, a Files API, is now available as a part of the 2021-07 version.
The stagedUploadCreate mutation, which previously only supported staging product media, now allows you to stage other types of files for upload. These staged files can now also be included as a part of a fileCreate mutation, which uploads the files to Shopify and adds them to the Files page in the Shopify Admin. Alternatively, you can provide an external URL to fileCreate to upload the file directly from the remote source to the admin.
For example, the following mutation will upload a file to the Files page :
Variables:
Files aren’t limited to images, either. Price lists, PDF brochures, sizing guides, or other generic files can also be uploaded using the File API.1.
5. International pricing
The prices that display on a storefront can vary based on the customer’s location. As seen at Shopify Unite, the 2021-07 release allows you to use the Storefront API to query international prices for products and orders, and explicitly set the checkout context. This feature works in conjunction with priceLists, and allows you to surface international pricing in a contextually relevant way to buyers.
Queries that use the inContext directive can use a country code argument, which will return results in the context of the chosen country.
For example, the query the price ranges for products in Canada, you can use the following query using the inContext directive:
Response:
This allows you to easily surface the relevant prices for the buyer, rather than returning prices in the store’s default currency.
Stay on top of changes
For all Shopify platform changes, make sure to subscribe to the developer changelog, the primary source of information for all new product launches. Stay up to date using the changelog, and stay ahead of the curve by adopting new features as soon as they’re shipped into the upcoming 2021-10 release candidate.
You can also subscribe to our monthly What’s New for Partners and Developers at Shopify newsletter, which will help keep you on top of all platform updates.
