Welcome to the January 2022 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 improved product filtering through the storefront API, the all-new product taxonomy API, and new metafield definitions on collections, customers, and orders. This version also includes an order invoice API, new error codes for bulk mutations, and simplified methods for getting translatable resources, featured images, and barcodes.
This release also coincides with the removal of version2021-01, 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 2022-01 release notes.
Table of contents
1. Product filtering in collections using the Storefront API
As of the 2022-01 version, it’s now possible to filter products in a collection, allowing you to narrow down the search results displayed to customers. After retrieving products by the collection they belong to, you can filter products in a collection based on the vendor, product type, variant options, price, and whether or not the product is in stock.
These filters can even be combined, allowing you to retrieve products in a collection with a specific set of more complex characteristics.
For example, the following query shows how to fetch products that have all the following characteristics:
- Type: Shirts & Tops
- Vendor: Bestshop
- Color: Very Peri
Variables:
Filtering products in a collection is a great way to surface the most relevant products to customers. For more information on how to filter products in a collection using the Storefront API, you can visit our docs.
2. Product Taxonomy API
The new Product Taxonomy API is the best way to keep products organized and discoverable by customers on merchant’s storefronts. StandardizedProductTypes are predefined categories of products that can improve discoverability on the storefront and make it easier for merchants to list products on channels like Facebook that require products to fit in a standard set of types.
For product types that don’t fit in one of the predefined categories, you can use the customProductType
field on the product object. Custom product types are a string, like the legacy type
field. These custom product types can also be paired with a parent StandardizedProductType if a parent category makes sense for the product.
Below is an example of a query to fetch the StandardizedProductType of a given product:
Response:
To learn more about product taxonomy, visit our developer docs.
3. Metafield definitions on Collections, Customers, and Orders
In the July version, we released updates to Metafields that allowed custom metafield types on Products. This version expands support for this feature to Collections, Customers, and Orders. Metafields on these new resources can also perform validations on 18 different types of data, allowing you to store validated data for display on storefronts or within apps.
Below is an example of a request to create a Customer metafield definition that stores a reference to a product.
Variables:
For more information about metafield definitions and migration to the improved type
system, visit our developer docs.
4. Order Invoice API
A new mutation has been added to apps to send invoices for orders through Shopify's API. The orderInvoiceSend mutation allows you to provide an order ID and email content, and directly email a customer to request payment for an order that still requires payment. This is a great opportunity to automate what has previously been a very manual process for merchants.
Below is an example mutation to send an invoice to the customer:
Variables:
Below is the email that this request will send to the customer:
![Screenshot of the email patients receive that links directly to the checkout, displaying cost, taxes, etc.](https://cdn.shopify.com/s/files/1/0533/2089/files/shopify-api-release-january-2022-email-linked.jpg?v=1640150604)
This email will link directly to the checkout, allowing the customer to easily pay for the order.
Visit our reference documentation for more information about sending invoices with the orderInvoiceSend mutation.
5. Bulk Mutation API error codes
Previously, the only error code BulkMutations could display was "BULK_MUTATION_USER_ERROR_CODE". In this version, we've replaced that general error code with five new, more granular error codes that will provide more insight into what exactly went wrong.
For a complete list of the new error codes, visit our developer docs.
As a reminder, if you need to do more than 10 seconds of continuous API requests, the BulkMutationAPI is the fastest and most efficient way to sync data back to Shopify. To learn more about syncing data to Shopify with the BulkMutation API, visit our documentation.
6. Fetch multiple Translatable resources by ID
In the past, getting translatable resources for a specific set of IDs required you to make multiple requests, getting a single resource at a time. As of 2022-01, it's now possible to get a specific list of translatable resources using an array of IDs, rather than getting all of the resources that belong to a specific type or needing to make a separate request to get each resource by ID.
Below is an example of a request to get the translatable content from a specific product and two variants with a single request:
For more information about the translatableResourcesByIds query, visit our reference documentation.
7. New Storefront API product fields
As of the 2022-01 version, the Storefront API supports two new fields on products. The featuredImage
field allows you to quickly and efficiently fetch the featured image of any product, and the ProductVariant barcode
allows you to fetch the barcode of any variant.
Below is an example query that fetches both new fields:
Response:
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 2022-04 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.