2022-01 release notes

The 2022-01 version of Shopify's APIs includes improved product filtering through the Storefront API, the new product taxonomy object, and new metafield definitions on collections, customers, and orders. This version also includes a new mutation to email order invoices, new error codes for bulk mutations, and simplified methods for getting translatable resources, featured images, and barcodes.

What’s new in 2022-01

The following features were added in version 2022-01 of Shopify's APIs.

Storefront API changes:

• Filter products in a collection.

• Retrieve the featured image for a product without having to request the first image in a set.

• Retrieve the resource that a metafield refers to.

• Retrieve the barcode (for example, ISBN, UPC, or GTIN) associated with a product variant.

• Retrieve a policy associated with a store, such as a subscription policy.

  GraphQL Admin API changes:

• Specify private metafield namespaces for the WebhookSubscription object and WebhookSubscriptionInput input object.

• Apply metafield definitions to the Order, Customer, and Collection objects.

• Send an email invoice for an order.

• Retrieve a bounding box from a 3D model.

• Retrieve the total sellable quantity of a product variant for online channels.

• Retrieve product taxonomy details that include standard and custom product types.

• Retrieve a list of products that merchants have scheduled to publish to your sales channel and use new webhooks for scheduled product publishing notifications.

• We've added new error codes for bulk mutations.

  REST Admin API changes:

• Use new webhooks for notifications of scheduled product publishing in sales channels.

• We've simplified the validation for formatting the resource feedback message field.

Anchor to Breaking changesBreaking changes

These changes require special attention. If your app uses these API resources, and you don’t adjust your usage of the resources according to the following instructions, then your app might break when you update to this API version.

Anchor to Error codes for bulk mutationsError codes for bulk mutations

As of API version 2022-01, new error codes have been added to the BulkMutationErrorCode enum to better represent the different types of errors that can occur during the execution of a bulk mutation.

Anchor to Removed fields in the Storefront APIRemoved fields in the Storefront API

In the 2021-01 API version release, several fields on the Storefront API were marked as deprecated. As of API version 2022-01, the following fields and arguments have been removed:

• customer field on Checkout object
• available, presentmentPrices, and presentmentCurrencies fields on the ProductVariant object
• presentmentPriceRanges field on the Product object
• url field on the Article, Blog, and Page objects
• description field on the ScriptDiscountApplication object
• currencyCode, shopifyPaymentsAccountId, productByHandle, collectionByHandle, blogs, articles, collections, products, productTypes, and productTags fields on the Shop object
• maxWidth, maxHeight, crop, and scale arguments on the Image object

Anchor to Changes to the ,[object Object], objectChanges to the Metafield object

In the 2021-07 API version release, the value_type field on the Metafield object in the GraphQL Admin API, Storefront API, and REST Admin API was deprecated. As of the 2022-01 API version release, the value_type field has been removed from these APIs.

You should use the type field instead of the value_type field to access or set the type of a Metafield object. For more information, refer to Managing metafields.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

Below are all the changes currently introduced in the 2022-01 version of the GraphQL Admin API.

Anchor to 3D model bounding boxes ,[object Object]3D model bounding boxes

You can now retrieve a bounding box from a 3D model. A bounding box is the smallest volume that can contain a 3D model.

New field

• boundingBox field was added to Model3d object

  New types

• Model3dBoundingBox object was added

• Vector3 object was added

Anchor to Authorization access errors ,[object Object]Authorization access errors

The authorization access error descriptions have been improved to provide more context and better represent the scopes required to execute a mutation. For example, previous error descriptions only expressed that you were denied access to a mutation. As of the 2022-01 API version, the error descriptions include the access scopes required.

Anchor to Deprecated Image fields ,[object Object]Deprecated Image fields

The following fields on the Image object have been deprecated:

• originalSrc

• src

• transformedSrc

  The deprecated fields are replaced with a single url field that you should use instead.

  New fields

• url field was added to Image object

  New types

• ImageTransformInput input object was added

Anchor to Error codes for bulk mutationsError codes for bulk mutations

Anchor to BreakingBreaking

As of API version 2022-01, new error codes have been added to the BulkMutationErrorCode enum to better represent the different types of errors that can occur during the execution of a bulk mutation.

New error codes

• BULK_MUTATION_USER_ERROR_CODE was added to enum BulkMutationErrorCode
• OPERATION_IN_PROGRESS was added to enum BulkMutationErrorCode
• INVALID_MUTATION was added to enum BulkMutationErrorCode
• INVALID_STAGED_UPLOAD_FILE was added to enum BulkMutationErrorCode
• NO_SUCH_FILE was added to enum BulkMutationErrorCode
• INTERNAL_FILE_SERVER_ERROR was added to enum BulkMutationErrorCode

Anchor to Error codes for processing Model3D files ,[object Object]Error codes for processing Model3D files

As of API version 2022-01, a new error code has been added to the FileErrorCode and MediaErrorCode enums to communicate file creation failures when processing Model3D files on the backend.

New error codes

• MODEL3D_PROCESSING_FAILURE was added to enum FileErrorCode
• MODEL3D_PROCESSING_FAILURE was added to enum MediaErrorCode

Anchor to Media warnings ,[object Object]Media warnings

You can now display warnings for media. For example, if 3D model dimensions might be incorrect, then a warning will be displayed on the product page.

New field

• MediaWarning field was added to ExternalVideo, MediaImage, Model3d, and Video objects

  New types

• MediaWarning object was added

• MediaWarningCode enum was added

Anchor to Metafields ,[object Object]Metafields

As of the 2022-01 API version release, you can use the GraphQL Admin API to apply metafield definitions to the Order, Customer, and Collection objects.

In the 2021-07 API version release, the value_type field on the Metafield object was deprecated. As of the 2022-01 API version release, the value_type field has been removed. You should use the type field instead of the value_type field to access or set the type of a Metafield object. For more information, refer to Managing metafields.

New types

• HasMetafieldDefinitions interface has been added to Order, Customer, and Collection objects

  Removed fields

• valueType field was removed from Metafield object

• valueType field was removed from MetafieldInput input object

Anchor to Online channels,[object Object]Online channels

You can now query the total sellable quantity of a product variant for online channels. This doesn't represent the total available inventory or capture limitations based on customer location.

New field

• sellableOnlineQuantity field was added to ProductVariant object

Anchor to Orders,[object Object]Orders

As of the 2022-01 API version release, you can use the OrderInvoiceSend mutation to send an email invoice for an order.

New mutation

• OrderInvoiceSend mutation was added

Anchor to Private metafield namespaces ,[object Object]Private metafield namespaces

As of API version 2022-01, you can specify private metafield namespaces for webhook subscriptions.

New fields

• private_metafield_namespaces field was added to the WebhookSubscription object
• private_metafield_namespaces field was added to the WebhookSubscriptionInput input object

Anchor to Product taxonomy ,[object Object]Product taxonomy

You can now query the GraphQL Admin API to retrieve a classification of product types. This includes all of the standard and custom product types associated with a product.

New types

• ProductTaxonomyNode object was added

• StandardProductType object was added

• StandardProductTypeInput input object was added

  New fields

• standardizedProductType was added to Product object

• standardizedProductType was added and ProductInput input object

• customProductType was added to Product object

• customProductType was added to ProductInput input object

Anchor to Scheduled publications,[object Object]Scheduled publications

You can now query the GraphQL Admin API for products that merchants have scheduled to publish to your sales channel. You can also use new webhooks for scheduled product publishing notifications. Use these webhooks to enable channel app workflows such as product drops and timed sales.

New field

• resourcePublicationOnCurrentPublication field was added to Product object

  New values

• SCHEDULED_PRODUCT_LISTINGS_ADD value was added to enum WebhookSubscriptionTopic

• SCHEDULED_PRODUCT_LISTINGS_REMOVE value was added to enum WebhookSubscriptionTopic

• SCHEDULED_PRODUCT_LISTINGS_UPDATE value was added to enum WebhookSubscriptionTopic

Anchor to Subscriptions,[object Object]Subscriptions

When you create a subscription draft, you can now add a note to apply to generated orders. For example, the note can be a personalized message to the customer.

New field

• note field was added to SubscriptionContract object

Anchor to Translatable resources by IDs ,[object Object]Translatable resources by IDs

As of API version 2022-01, you can retrieve translatable resources by their IDs.

New connection

• translatableResourcesByIds connection was added to the QueryRoot object

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

Below are all the changes currently introduced in the 2022-01 version of the GraphQL Storefront API.

Anchor to Deprecated Image fields ,[object Object]Deprecated Image fields

The following fields on the Image object have been deprecated:

• originalSrc

• src

• transformedSrc

  The deprecated fields are replaced with a single url field that you should use instead.

  New fields

• url field was added to Image object

  New types

• ImageTransformInput input object was added

Anchor to Featured product images ,[object Object]Featured product images

You can now use the Storefront API to retrieve the featured image for a product without having to request the first image in a set.

New field

• featuredImage field was added to Product object

Anchor to Filtering products ,[object Object]Filtering products

You can now use the Storefront API to filter products in a collection. This functionality lets you build a desired customer experience on a storefront, such as the ability to narrow down the search results that you display to customers.

New types

• Filter object was added

• FilterValue object was added

• VariantOptionFilter input object was added

• ProductFilter input object was added

• PriceRangeFilter input object was added

• MetafieldFilter input object was added

• FilterType enum was added

  New field

• filters field was added to Product object

Anchor to Metafields ,[object Object]Metafields

You can now use the Storefront API to retrieve the resource that a metafield refers to. This functionality provides parity with the reference field on the GraphQL Admin API's MetafieldReference object.

In the 2021-07 API version release, the value_type field on the Metafield object was deprecated. As of the 2022-01 API version release, the value_type field has been removed. You should use the type field instead of the value_type field to access or set the type of a Metafield object. For more information, refer to Managing metafields.

New field

• reference field was added to MetafieldReference object

  Removed fields

• valueType field was removed from Metafield object

Anchor to Product variants ,[object Object]Product variants

You can now use the Storefront API to retrieve the barcode (for example, ISBN, UPC, or GTIN) associated with a product variant.

New field

• barcode field was added to ProductVariant object

Anchor to Removed fieldsRemoved fields

Anchor to BreakingBreaking

In the 2021-01 API version release, several fields on the Storefront API were marked as deprecated. As of API version 2022-01, the following fields and arguments have been removed:

• customer field on Checkout object
• available, presentmentPrices, and presentmentCurrencies fields on the ProductVariant object
• presentmentPriceRanges field on the Product object
• url field on the Article, Blog, and Page objects
• description field on the ScriptDiscountApplication object
• currencyCode, shopifyPaymentsAccountId, productByHandle, collectionByHandle, blogs, articles, collections, products, productTypes, and productTags fields on the Shop object
• maxWidth, maxHeight, crop, and scale arguments on the Image object

Anchor to Store policy ,[object Object]Store policy

You can now use the Storefront API to retrieve policy associated with a store, such as a subscription policy.

New type

• ShopPolicyWithDefault object was added

  New fields

• subscriptionPolicy field was added to Shop object

Anchor to REST Admin API changesREST Admin API changes

Below are all the changes currently introduced in the 2022-01 version of the REST Admin API.

Anchor to Metafields ,[object Object]Metafields

In the 2021-07 API version release, the value_type property on the Metafield resource was deprecated. As of the 2022-01 API version release, the value_type property has been removed.

You should use the type field instead of the value_type field to access or set the type of a Metafield object. For more information, refer to Managing metafields.

Removed properties

• value_type property was removed from Metafield resource

Anchor to Resource feedback ,[object Object]Resource feedback

The validation for formatting the resource feedback message field has been simplified.

If the feedback state is requires_action, then you can send a string message that communicates the action to be taken by the merchant. The string must be a single message up to 100 characters long and must end with a period.

For more information, refer to ResourceFeedback.

Anchor to Scheduled publications webhooks ,[object Object]Scheduled publications webhooks

Sales channels can now use webhooks for notifications of scheduled product publishing. Use these webhooks to enable channel app workflows such as product drops and timed sales.

New topics

• scheduled_product_listings/add topic was added to Webhook resource

• scheduled_product_listings/remove topic was added to Webhook resource

• scheduled_product_listings/update topic was added to Webhook resource