2021-07 release notes
| Release date | Date version is no longer supported |
|---|---|
| July 1, 2021 | July 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
stagedUploadCreatemutation, 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.
Breaking changes
Anchor link to section titled "Breaking 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.
Deprecated connection on Shop object
Anchor link to section titled "Deprecated 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.
Deprecated field on Shop resource
Anchor link to section titled "Deprecated 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.
Deprecated field on Metafield object
Anchor link to section titled "Deprecated 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.
Deprecated property on Metafield resource
Anchor link to section titled "Deprecated 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.
Explicit user permissions
Anchor link to section titled "Explicit 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.
Empty selling plan groups
Anchor link to section titled "Empty 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.
Pricing policies for selling plans
Anchor link to section titled "Pricing 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
sellingPlanGroupUpdatemutation. - 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.
GraphQL Admin API changes
Anchor link to section titled "GraphQL Admin API changes"Below are all the changes currently introduced in the 2021-07 version of the GraphQL Admin API.
Deprecated connection on Shop object type
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.
Empty 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.
Pricing 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
sellingPlanGroupUpdatemutation. - 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.
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
typefield was added to objectMetafield
New values
single_line_text_fieldvalue was added to objectMetafieldmulti_line_text_fieldvalue was added to objectMetafieldpage_referencevalue was added to objectMetafieldproduct_referencevalue was added to objectMetafieldvariant_referencevalue was added to objectMetafieldfile_referencevalue was added to objectMetafieldnumber_integervalue was added to objectMetafieldnumber_decimalvalue was added to objectMetafielddatevalue was added to objectMetafielddate_timevalue was added to objectMetafieldurlvalue was added to objectMetafieldjsonvalue was added to objectMetafieldbooleanvalue was added to objectMetafieldcolorvalue was added to objectMetafieldweightvalue was added to objectMetafieldvolumevalue was added to objectMetafielddimensionvalue was added to objectMetafieldurlvalue was added to objectMetafield
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_dutiesfield was added to objectFulfillmentOrder
New types
FulfillmentOrderInternationalDutiesobject was added
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
estimatedTaxesfield was added toOrderobject
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
customerPaymentMethodRemoteCreatemutation was addedCustomerPaymentMethodRemoteUserErrorwas added
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
FileCreatemutation was addedFileDeletemutation was addedFileUpdatemutation was added
New types
FileErrorobject was addedGenericFileobject was addedFileCreateInputinput object was addedFileUpdateInputinput object was addedFileinterface was addedFileContentTypeenum was addedFileErrorCodeenum was addedfile_storage_limit_exceedederror code was added to enumMediaErrorCodegeneric_file_download_failureerror code was added to enumMediaErrorCodegeneric_file_invalid_sizeerror code was added to enumMediaErrorCodeinvalid_image_aspect_ratioerror code was added to enumMediaErrorCodeinvalid_image_resolutionerror code was added to enumMediaErrorCode
New errors
FilesUserErrorerror was added
New fields
FileStatusfield was added toMediainterface
New connections
file_saved_searchesconnection added to objectQueryRootfilesconnection added to objectQueryRoot
New values
FILEvalue was added to enumUploadResourceFilevalue was added to enumSearchResultType
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
bulkOperationRunMutationmutation was added
New types
BulkOperationTypeenum was addedBulkMutationUserErrortype was addedcurrentBulkOperationconnection was added to objectQueryRootBULK_MUTATION_VARIABLESvalue was added to enumStagedUploadTargetGenerateUploadResource
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
productVariantsBulkCreatemutation was addedproductVariantsBulkUpdatemutation was addedproductVariantsBulkDeletemutation was addedproductVariantsBulkReordermutation was added
New types
ProductVariantsBulkInputinput object was addedProductVariantsBulkCreateUserErrorwas addedProductVariantsBulkUpdateUserErrorwas addedProductVariantsBulkDeleteUserErrorwas added
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
pubSubWebhookSubscriptionCreatemutation was addedpubSubWebhookSubscriptionUpdatemutation was added
New input
pubSubWebhookSubscriptionInputwas added
New type
WebhookPubSubEndpointobject was addedPubSubWebhookSubscriptionInputwas addedPubSubWebhookSubscriptionCreatePayloadwas addedPubSubWebhookSubscriptionUpdatePayloadwas added
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
UrlRedirectBulkDeleteAllmutation was addedUrlRedirectBulkDeleteByIdsmutation was addedUrlRedirectBulkDeleteBySavedSearchmutation was addedUrlRedirectBulkDeleteBySearchmutation was addedUrlRedirectCreatemutation was addedUrlRedirectDeletemutation was addedUrlRedirectImportCreatemutation was addedUrlRedirectImportSubmitmutation was addedUrlRedirectUpdatemutation was added
New types
UrlRedirectobject was addedUrlRedirectImportobject was addedUrlRedirectImportPreviewobject was addedUrlRedirectInputinput object was addedUrlRedirectImportUserErrortype was addedUrlRedirectUserErrortype was added
New fields
urlRedirectfield was added to objectQueryRooturlRedirectSavedSearchesfield was added to objectQueryRooturlRedirectImportfield was added to objectQueryRoot
New connections
urlRedirectsconnection was added to objectQueryRoot
New values
urlRedirectsvalue was added to enumResourceTypeurlRedirectsvalue was added to enumResourceExportableTypeurlRedirectvalue was added to enumSearchResultType
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.
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
channelLiablefield was added to theTaxLineobject
GraphQL Storefront API changes
Anchor link to section titled "GraphQL Storefront API changes"Below are all the changes currently introduced in the 2021-07 version of the GraphQL Storefront API.
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
Locationobject was addedStoreAvailabilityobject was addedlocationsconnection was added toQueryRootpreferredLocationIdargument was added toInContextdirective
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
SellingPlanAllocationobject was addedSellingPlanPriceAdjustmentobject was addedSellingPlanAllocationPriceAdjustmentobject was addedSellingPlanFixedAmountPriceAdjustmentobject was addedSellingPlanPercentagePriceAdjustmentobject was addedSellingPlanGroupOptionobject was addedSellingPlanGroupobject was addedSellingPlanobject was addedsellingPlanAllocationsconnection was added toProductVariantobjectrequiresSellingPlanfield was added toProductobjectSellingPlanPriceAdjustmentValueunion was added
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.
New types
queueTokenargument was added toCheckoutCreatemutationqueueTokenreturn field was added toCheckoutCreatemutationTHROTTLED_DURING_CHECKOUTerror was added toCheckoutUserErrorEXPIRED_QUEUE_TOKENerror was added toCheckoutUserErrorINVALID_QUEUE_TOKENerror was added toCheckoutUserError
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
Localizationobject was addedCountryobject was addedCurrencyobject was added
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.
New types
inContextdirective was addedCheckoutBuyerIdentityobject was addedCheckoutBuyerIdentityInputinput object was addedINVALID_COUNTRY_AND_CURRENCYerror code was added toCheckoutUserError
New fields
buyerIdentityfield was added toCheckoutobjectbuyerIdentityinput argument was added tocheckoutCreatemutation
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:
Articleobject was added toMetafieldParentResourceunionBlogobject was added toMetafieldParentResourceunionCollectionobject was added toMetafieldParentResourceunionCustomerobject was added toMetafieldParentResourceunionOrderobject was added toMetafieldParentResourceunionPageobject was added toMetafieldParentResourceunionShopobject was added toMetafieldParentResourceunion
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.
GraphQL Payments Apps API changes
Anchor link to section titled "GraphQL 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.
Capture session
As of API version 2021-07, you can use new mutations to reject or resolve an open capture session.
New type
CaptureSessionobject was added
New mutations
captureSessionRejectmutation was addedcaptureSessionResolvemutation was added
Void session
As of API version 2021-07, you can use new mutations to reject or resolve a void session.
New type
VoidSessionobject was added
New mutations
voidSessionRejectmutation was addedvoidSessionResolvemutation was added
Authorized payment session expiry
As of API version 2021-07, a new argument authorizationExpiresAt can be included with the paymentSessionResolve mutation.
New field
authorizationExpiresAtfield was added toPaymentSessionobject
New argument
authorizationExpiresAtargument was added topaymentSessionResolvemutation
REST Admin API changes
Anchor link to section titled "REST Admin API changes"Below are all the changes currently introduced in the 2021-07 version of the REST Admin API.
Deprecated 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.
Removed fields
force_sslfield was removed fromShopresourceforce_sslfield was removed fromshop/updatewebhook topicforce_sslfield was removed fromapp/uninstalledwebhook topic
Explicit user permissions
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.
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
typeproperty was added to resourceMetafield
New values
single_line_text_fieldvalue was added to resourceMetafieldmulti_line_text_fieldvalue was added to resourceMetafieldpage_referencevalue was added to resourceMetafieldproduct_referencevalue was added to resourceMetafieldvariant_referencevalue was added to resourceMetafieldfile_referencevalue was added to resourceMetafieldnumber_integervalue was added to resourceMetafieldnumber_decimalvalue was added to resourceMetafielddatevalue was added to resourceMetafielddate_timevalue was added to resourceMetafieldurlvalue was added to resourceMetafieldjsonvalue was added to resourceMetafieldbooleanvalue was added to resourceMetafieldcolorvalue was added to resourceMetafieldweightvalue was added to resourceMetafieldvolumevalue was added to resourceMetafielddimensionvalue was added to resourceMetafieldurlvalue was added to resourceMetafield
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_dutiesproperty was added to resourceFulfillmentOrder
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_taxesproperty was added toOrderresource
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_liableproperty was added to Order resourcechannel_liableproperty was added to Abandoned checkouts resource