Skip to main content

2021-07 release notes

Note

We're no longer publishing API release notes. Instead, you can find the latest updates on Shopify APIs in our developer changelog. You can filter updates by area. For example, you can filter API updates by the API name and version, such as GraphQL Admin API changes in version 2025-04.

Release dateDate version is no longer supported
July 1, 2021July 1, 2022

The 2021-07 release includes the Bulk Mutations API, a new API that provides 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. For more information, refer to the All of the Announcements From Shopify Unite 2021 blog post.

What’s new in 2021-07

The following features were added in version 2021-07 of Shopify's APIs:

  • We've made updates to metafields that improve their utility for apps and merchants. Metafield storefront visibility is now supported on articles, blogs, collections, customers, orders, pages, and the shop resource.
  • The Bulk Mutation APIs remove the need to manage your client-side throttle, and allow apps to asynchronously run mutations to import large amounts of data into Shopify stores.
  • 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 Files APIs 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.
  • You can now 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.

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 Deprecated connection on Shop objectDeprecated connection on Shop object

As of API version 2021-07, the uploadedImages connection on the GraphQL Admin Shop object type has been deprecated. The connection previously represented all images that were uploaded to a shop.

You can use the uploadedImagesbyIds field instead to retrieve a list of images by ID that have been uploaded to the shop.

Anchor to Deprecated field on Shop resourceDeprecated field on Shop resource

As of API version 2021-07, the force_ssl field on the REST Shop resource has been removed. Previously, this field had indicated whether requests made to the REST Shop resource connected over SSL using HTTPS. All requests now use HTTPS, so force_ssl is always true.

Anchor to Deprecated field on Metafield objectDeprecated field on Metafield object

As of API version 2021-07, the value_type field on the Metafield object was deprecated.

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 about this transition, refer to this changelog entry.

Anchor to Deprecated property on Metafield resourceDeprecated property on Metafield resource

As of API version 2021-07, the value_type property on the Metafield resource was deprecated.

You should use the type property instead of the value_type property to access or set the type of a Metafield resource. For more information about this transition, refer to this changelog entry.

Anchor to Explicit user permissionsExplicit user permissions

In previous API versions, the permissions property in the REST User resource returned either full or a specific list of permissions. The full permission represents that the user has the same permissions as the store owner, with some exceptions, such as modifying the account billing or deleting staff accounts.

As of API version 2021-07, the complete list of explicit permissions that a user with the full permission has access to is returned in the permissions property.

Anchor to Empty selling plan groupsEmpty selling plan groups

Prior to API version 2021-07, a selling plan group could exist without any selling plans. Apps could create a selling plan group with selling plans, and subsequently delete all selling plans in the group. This was problematic because empty selling plan groups could result in undesirable behavior on the product page and a broken cart experience.

As of API version 2021-07, we've added a validation to the sellingPlanGroupUpdate mutation that prevents the presence of empty selling plan groups.

Anchor to Pricing policies for selling plansPricing policies for selling plans

Apps update the pricing policies associated with a selling plan using the sellingPlanGroupUpdate mutation. Prior to API version 2021-07, two key behaviors existed:

  • Apps could apply partial updates to a pricing policy by supplying only the updated pricing policy in the mutation's input. For example, if you had a selling plan with an existing fixed pricing policy, and you wanted to add a recurring pricing policy, then you could supply only the recurring pricing policy as the input to the sellingPlanGroupUpdate mutation.

  • There wasn't a clear way to delete a pricing policy associated with a selling plan.

    As of API version 2021-07, apps must explicitly provide the end state of all pricing policies in the sellingPlanGroupUpdate mutation's input. For example, if you have a selling plan with an existing fixed pricing policy, and you want to add a recurring pricing policy, then you need to supply both the existing and new pricing policy in the mutation's input.

    To delete all pricing policies from a selling plan, you need to supply an empty array of pricing policies (pricingPolicies: []) in the sellingPlanGroupUpdate mutation's input.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

Below are all the changes currently introduced in the 2021-07 version of the GraphQL Admin API.

Anchor to Deprecated connection on Shop object typeDeprecated connection on Shop object type

Anchor to BreakingBreaking

As of API version 2021-07, the uploadedImages connection on the GraphQL Admin Shop object type has been deprecated. The connection previously represented all images that were uploaded to a shop.

You can use the uploadedImagesbyIds field instead to retrieve a list of images by ID that have been uploaded to the shop.

Anchor to Empty selling plan groupsEmpty selling plan groups

Anchor to BreakingBreaking

Prior to API version 2021-07, a selling plan group could exist without any selling plans. Apps could create a selling plan group with selling plans, and subsequently delete all selling plans in the group. This was problematic because empty selling plan groups could result in undesirable behavior on the product page and a broken cart experience.

As of API version 2021-07, we've added a validation to the sellingPlanGroupUpdate mutation that prevents the presence of empty selling plan groups.

Anchor to Pricing policies for selling plansPricing policies for selling plans

Anchor to BreakingBreaking

Apps update the pricing policies associated with a selling plan using the sellingPlanGroupUpdate mutation. Prior to API version 2021-07, two key behaviors existed:

  • Apps could apply partial updates to a pricing policy by supplying only the updated pricing policy in the mutation's input. For example, if you had a selling plan with an existing fixed pricing policy, and you wanted to add a recurring pricing policy, then you could supply only the recurring pricing policy as the input to the sellingPlanGroupUpdate mutation.

  • There wasn't a clear way to delete a pricing policy associated with a selling plan.

    As of API version 2021-07, apps must explicitly provide the end state of all pricing policies in the sellingPlanGroupUpdate mutation's input. For example, if you have a selling plan with an existing fixed pricing policy, and you want to add a recurring pricing policy, then you need to supply both the existing and new pricing policy in the mutation's input.

    To delete all pricing policies from a selling plan, you need to supply an empty array of pricing policies (pricingPolicies: []) in the sellingPlanGroupUpdate mutation's input.

Anchor to Deprecated field on Metafield object ,[object Object]Deprecated field on Metafield object

As of API version 2021-07, the value_type field on the Metafield object has been deprecated.

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 about this transition, refer to this changelog entry.

You can set the type field of the Metafield object using any of the new values introduced below.

New fields

  • type field was added to object Metafield

    New values

  • single_line_text_field value was added to object Metafield

  • multi_line_text_field value was added to object Metafield

  • page_reference value was added to object Metafield

  • product_reference value was added to object Metafield

  • variant_reference value was added to object Metafield

  • file_reference value was added to object Metafield

  • number_integer value was added to object Metafield

  • number_decimal value was added to object Metafield

  • date value was added to object Metafield

  • date_time value was added to object Metafield

  • url value was added to object Metafield

  • json value was added to object Metafield

  • boolean value was added to object Metafield

  • color value was added to object Metafield

  • weight value was added to object Metafield

  • volume value was added to object Metafield

  • dimension value was added to object Metafield

  • url value was added to object Metafield

Anchor to Duties and international taxes ,[object Object]Duties and international taxes

As of API version 2021-07, you can use the GraphQL Admin API to query whether the duties and international taxes associated with an order were charged at checkout.

New fields

  • international_duties field was added to object FulfillmentOrder

    New types

  • FulfillmentOrderInternationalDuties object was added

Anchor to Estimated taxes on orders ,[object Object]Estimated taxes on orders

As of API version 2021-07, you can use the estimatedTaxes field on the Order object to determine whether taxes on an order are estimated.

The field returns false when taxes on an order are finalized and aren't subject to any changes.

New field

  • estimatedTaxes field was added to Order object

Anchor to Configure payment gateways to work with subscriptions ,[object Object]Configure payment gateways to work with subscriptions

As of API version 2021-07, you can use the customerPaymentMethodRemoteCreate mutation to associate a Shopify customer ID with an Authorize.net customer profile ID and payment method ID.

For more information on configuring payment gateways to work with subscriptions, refer to Migrating existing subscription contracts to Shopify.

New types

  • customerPaymentMethodRemoteCreate mutation was added
  • CustomerPaymentMethodRemoteUserError was added

Anchor to Manage images and generic files ,[object Object]Manage images and generic files

As of API version 2021-07, you can use the GraphQL Admin API to create, update, and delete generic files and images using the Files API. This functionality allows merchants to reuse files for different apps.

New mutations

  • FileCreate mutation was added

  • FileDelete mutation was added

  • FileUpdate mutation was added

    New types

  • FileError object was added

  • GenericFile object was added

  • FileCreateInput input object was added

  • FileUpdateInput input object was added

  • File interface was added

  • FileContentType enum was added

  • FileErrorCode enum was added

  • file_storage_limit_exceeded error code was added to enum MediaErrorCode

  • generic_file_download_failure error code was added to enum MediaErrorCode

  • generic_file_invalid_size error code was added to enum MediaErrorCode

  • invalid_image_aspect_ratio error code was added to enum MediaErrorCode

  • invalid_image_resolution error code was added to enum MediaErrorCode

    New errors

  • FilesUserError error was added

    New fields

  • FileStatus field was added to Media interface

    New connections

  • file_saved_searches connection added to object QueryRoot

  • files connection added to object QueryRoot

    New values

  • FILE value was added to enum UploadResource

  • File value was added to enum SearchResultType

Anchor to Bulk import data asynchronously ,[object Object]Bulk import data asynchronously

As of API version 2021-07, you can use the GraphQL Admin API to bulk import large volumes of data asychronously. By running a bulk mutation operation, you can avoid manually running a GraphQL mutation multiple times and managing a client-side throttle.

To learn more about bulk importing data asynchronously, refer to Bulk import data with the GraphQL Admin API.

New mutation

  • bulkOperationRunMutation mutation was added

    New types

  • BulkOperationType enum was added

  • BulkMutationUserError type was added

  • currentBulkOperation connection was added to object QueryRoot

  • BULK_MUTATION_VARIABLES value was added to enum StagedUploadTargetGenerateUploadResource

Anchor to Product variants ,[object Object]Product variants

As of API version 2021-07, you can create, update, and delete multiple product variants at once using 3 new product variant mutations.

Previously, multiple product variants could be managed at once only through the productCreate and productUpdate mutations, which required additional input to avoid overwriting existing variants.

New mutations

  • productVariantsBulkCreate mutation was added

  • productVariantsBulkUpdate mutation was added

  • productVariantsBulkDelete mutation was added

  • productVariantsBulkReorder mutation was added

    New types

  • ProductVariantsBulkInput input object was added

  • ProductVariantsBulkCreateUserError was added

  • ProductVariantsBulkUpdateUserError was added

  • ProductVariantsBulkDeleteUserError was added

Anchor to Manage webhooks with Google Cloud Pub/Sub ,[object Object]Manage webhooks with Google Cloud Pub/Sub

As of API version 2021-07, you can use the GraphQL Admin API and Google Cloud Pub/Sub to manage webhook subscriptions.

New mutations

  • pubSubWebhookSubscriptionCreate mutation was added

  • pubSubWebhookSubscriptionUpdate mutation was added

    New input

  • pubSubWebhookSubscriptionInput was added

    New type

  • WebhookPubSubEndpoint object was added

  • PubSubWebhookSubscriptionInput was added

  • PubSubWebhookSubscriptionCreatePayload was added

  • PubSubWebhookSubscriptionUpdatePayload was added

Anchor to Manage URL redirects on an online store ,[object Object]Manage URL redirects on an online store

As of API version 2021-07, you can use the GraphQL Admin API to manage redirects on an online store.

URL redirects can be used to redirect traffic from one web page to another. For example, if you delete a product, then you can set up a URL redirect so that when customers enter the URL for that product, they are redirected to a similar product on an online store.

New mutations

  • UrlRedirectBulkDeleteAll mutation was added

  • UrlRedirectBulkDeleteByIds mutation was added

  • UrlRedirectBulkDeleteBySavedSearch mutation was added

  • UrlRedirectBulkDeleteBySearch mutation was added

  • UrlRedirectCreate mutation was added

  • UrlRedirectDelete mutation was added

  • UrlRedirectImportCreate mutation was added

  • UrlRedirectImportSubmit mutation was added

  • UrlRedirectUpdate mutation was added

    New types

  • UrlRedirect object was added

  • UrlRedirectImport object was added

  • UrlRedirectImportPreview object was added

  • UrlRedirectInput input object was added

  • UrlRedirectImportUserError type was added

  • UrlRedirectUserError type was added

    New fields

  • urlRedirect field was added to object QueryRoot

  • urlRedirectSavedSearches field was added to object QueryRoot

  • urlRedirectImport field was added to object QueryRoot

    New connections

  • urlRedirects connection was added to object QueryRoot

    New values

  • urlRedirects value was added to enum ResourceType

  • urlRedirects value was added to enum ResourceExportableType

  • urlRedirect value was added to enum SearchResultType

Anchor to New code for unrecognized currencies ,[object Object]New code for unrecognized currencies

As of API version 2021-07, the GraphQL Admin API returns XXX in response to an unrecognized currency code. XXX is the ISO code used to denote transactions that involve no currency.

In mutations, a CurrencyCode input value of XXX is invalid. XXX can only be returned as a result and not as an input value.

This change prevents order pages from breaking if payments include a currency code that's not in the list of valid values for the CurrencyCode object.

Anchor to Expose writable tax line attributes ,[object Object]Expose writable tax line attributes

As of API version 2021-07, you can use the channelLiable field on the TaxLine object to determine whether the channel that submitted the tax line is liable for remitting.

A value of null indicates unknown liability for the tax line.

New field

  • channelLiable field was added to the TaxLine object

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

Below are all the changes currently introduced in the 2021-07 version of the GraphQL Storefront API.

Anchor to Local pickup ,[object Object]Local pickup

As of API version 2021-07, you can display whether a product is in stock and available for local pickup using the Storefront API. Customers can then pick up their online orders at a retail store, curbside, or any location that a merchant chooses.

For more information, refer to Support local pickup on storefronts.

New types

  • Location object was added
  • StoreAvailability object was added
  • locations connection was added to QueryRoot
  • preferredLocationId argument was added to InContext directive

Anchor to Subscription products ,[object Object]Subscription products

As of API version 2021-07, you can use the Storefront API to retrieve subscription products on a storefront. Subscription products can be accessed from the sellingPlans object.

To learn how to retrieve information about selling plans, including price adjustments and selling plan allocations, and creating a cart with a subscription line item, refer to Manage subscription products on storefronts.

New types

  • SellingPlanAllocation object was added
  • SellingPlanPriceAdjustment object was added
  • SellingPlanAllocationPriceAdjustment object was added
  • SellingPlanFixedAmountPriceAdjustment object was added
  • SellingPlanPercentagePriceAdjustment object was added
  • SellingPlanGroupOption object was added
  • SellingPlanGroup object was added
  • SellingPlan object was added
  • sellingPlanAllocations connection was added to ProductVariant object
  • requiresSellingPlan field was added to Product object
  • SellingPlanPriceAdjustmentValue union was added

Anchor to Checkout queue tokens ,[object Object]Checkout queue tokens

As of API version 2021-07, the Storefront API can be used for checkouts during a flash sale.

The checkoutCreate mutation now accepts an optional queueToken argument, which allows apps to bypass the checkout throttle after they have completed polling.

Previously, when a checkout queue was in use, apps calling the checkoutCreate mutation received a Throttled response. There was no way for apps to bypass the queue, and the only option was to wait for the queue to disengage before retrying the request again.

The queue now engages as soon as the rate per second threshold is crossed.

Note

The queueToken argument is available only to selected stores.

New types

  • queueToken argument was added to CheckoutCreate mutation
  • queueToken return field was added to CheckoutCreate mutation
  • THROTTLED_DURING_CHECKOUT error was added to CheckoutUserError
  • EXPIRED_QUEUE_TOKEN error was added to CheckoutUserError
  • INVALID_QUEUE_TOKEN error was added to CheckoutUserError

Anchor to Query available countries and currencies ,[object Object]Query available countries and currencies

As of API version 2021-07, you can use the Storefront API to retrieve a list of available countries and corresponding currencies for a store.

New types

  • Localization object was added
  • Country object was added
  • Currency object was added

Anchor to Support international pricing on storefronts ,[object Object]Support international pricing on storefronts

The prices that display in a storefront can vary based on the customer's location. As of API version 2021-07, you can use the Storefront API to query international prices for products and orders, and explicitly set the context of a checkout.

International pricing is determined based on the customer's shipping address and is enforced at checkout.

Note

International pricing replaces the deprecated presentment currencies functionality.

New types

  • inContext directive was added

  • CheckoutBuyerIdentity object was added

  • CheckoutBuyerIdentityInput input object was added

  • INVALID_COUNTRY_AND_CURRENCY error code was added to CheckoutUserError

    New fields

  • buyerIdentity field was added to Checkout object

  • buyerIdentity input argument was added to checkoutCreate mutation

Anchor to Support for metafields on more resources ,[object Object]Support for metafields on more resources

As of API version 2021-07, the GraphQL Storefront API supports metafields on additional resources. You can retrieve metafields with the Storefront API to access additional information from different types of resources.

Previously, metafields were only supported on the Product and ProductVariant resources.

New types

The following types now also support metafields:

  • Article object was added to MetafieldParentResource union
  • Blog object was added to MetafieldParentResource union
  • Collection object was added to MetafieldParentResource union
  • Customer object was added to MetafieldParentResource union
  • Order object was added to MetafieldParentResource union
  • Page object was added to MetafieldParentResource union
  • Shop object was added to MetafieldParentResource union

Anchor to New code for unrecognized currencies ,[object Object]New code for unrecognized currencies

As of API version 2021-07, the Storefront API returns XXX in response to an unrecognized currency code. XXX is the ISO code used to denote transactions that involve no currency.

In mutations, a CurrencyCode input value of XXX is invalid. XXX can only be returned as a result and not as an input value.

This change prevents order pages from breaking if payments include a currency code that's not in the list of valid values for the CurrencyCode object.

Anchor to GraphQL Payments Apps API changesGraphQL Payments Apps API changes

The Payments Apps API is a new API that is available as of the 2021-07 release. The Payments Apps API lets you programmatically access data related to your payments app configuration.

Anchor to Capture session ,[object Object]Capture session

As of API version 2021-07, you can use new mutations to reject or resolve an open capture session.

New type

  • CaptureSession object was added

    New mutations

  • captureSessionReject mutation was added

  • captureSessionResolve mutation was added

Anchor to Void session ,[object Object]Void session

As of API version 2021-07, you can use new mutations to reject or resolve a void session.

New type

  • VoidSession object was added

    New mutations

  • voidSessionReject mutation was added

  • voidSessionResolve mutation was added

Anchor to Authorized payment session expiry ,[object Object]Authorized payment session expiry

As of API version 2021-07, a new argument authorizationExpiresAt can be included with the paymentSessionResolve mutation.

New field

  • authorizationExpiresAt field was added to PaymentSession object

    New argument

  • authorizationExpiresAt argument was added to paymentSessionResolve mutation

Anchor to REST Admin API changesREST Admin API changes

Below are all the changes currently introduced in the 2021-07 version of the REST Admin API.

Anchor to Deprecated field on Shop resourceDeprecated field on Shop resource

Anchor to BreakingBreaking

As of API version 2021-07, the force_ssl field on the REST Shop resource has been removed. Previously, this field had indicated whether requests made to the REST Shop resource connected over SSL using HTTPS. All requests now use HTTPS, so force_ssl is always true.

Removed fields

  • force_ssl field was removed from Shop resource
  • force_ssl field was removed from shop/update webhook topic
  • force_ssl field was removed from app/uninstalled webhook topic

Anchor to Explicit user permissionsExplicit user permissions

Anchor to BreakingBreaking

As of API version 2021-07, the complete list of explicit permissions that a user with the full permission has access to is returned in the permissions property of the REST User resource.

New values

The following new values have also been added to the permissions property:

  • billing_charges: The user can view and export billing charges.
  • billing_invoices_view: The user can view billing invoices.
  • billing_payment_methods_view: The user can view billing payment methods.
  • staff_management_activation: The user can activate or deactivate staff in the store.
  • staff_management_create: The user can add staff to the store.
  • staff_management_delete: The user can delete staff from the store.

Anchor to Deprecated property on Metafield resource ,[object Object]Deprecated property on Metafield resource

As of API version 2021-07, the value_type property on the Metafield resource has been deprecated.

You should use the type property instead of the value_type property to access or set the type of a Metafield resource. For more information about this transition, refer to this changelog entry.

You can set the type property of the Metafield resource using any of the new values introduced below.

New properties

  • type property was added to resource Metafield

    New values

  • single_line_text_field value was added to resource Metafield

  • multi_line_text_field value was added to resource Metafield

  • page_reference value was added to resource Metafield

  • product_reference value was added to resource Metafield

  • variant_reference value was added to resource Metafield

  • file_reference value was added to resource Metafield

  • number_integer value was added to resource Metafield

  • number_decimal value was added to resource Metafield

  • date value was added to resource Metafield

  • date_time value was added to resource Metafield

  • url value was added to resource Metafield

  • json value was added to resource Metafield

  • boolean value was added to resource Metafield

  • color value was added to resource Metafield

  • weight value was added to resource Metafield

  • volume value was added to resource Metafield

  • dimension value was added to resource Metafield

  • url value was added to resource Metafield

Anchor to Duties and international taxes ,[object Object]Duties and international taxes

As of API version 2021-07, you can use the FulfillmentOrder resource to retrieve information about whether the duties and international taxes associated with an order were charged at checkout.

New properties

  • international_duties property was added to resource FulfillmentOrder

Anchor to Estimated taxes on orders ,[object Object]Estimated taxes on orders

As of API version 2021-07, you can use the estimated_taxes property on the REST Order resource to determine whether taxes on an order are estimated.

The property returns false when taxes on an order are finalized and aren't subject to any changes.

New property

  • estimated_taxes property was added to Order resource

Anchor to Expose writable tax line attributes ,[object Object]Expose writable tax line attributes

As of API version 2021-07, you can use the channel_liable property on the Order and Abandoned checkouts resources to determine whether the channel that submitted the tax line is liable for remitting.

A value of null indicates unknown liability for the tax line.

New properties

  • channel_liable property was added to Order resource
  • channel_liable property was added to Abandoned checkouts resource
Was this page helpful?