Skip to main content

2021-10 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
October 1, 2021October 1, 2022

The 2021-10 version of Shopify's APIs includes significant improvements to the Storefront API, including a new Cart API and the ability to fetch specific resources by ID. This version also includes bulk operation webhooks, manual fulfillment holds for pre-orders, and SMS marketing consent endpoints to represent a customer’s willingness to receive SMS marketing communications.

What’s new in 2021-10

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

  • You can now interact directly with carts using the Storefront API. The Cart API allows you to get all the contextual information about an upcoming order without the need to create a checkout until the customer is ready to pay.
  • New fields were added to the Storefront API QueryRoot object to fetch individual resources directly. You can query blogs, collections, pages, and products by ID or a handle.
  • The Bulk Operations API now includes the bulk_operations/finish webhook. You can subscribe to this webhook to be notified when a bulk operation has completed, failed, or been cancelled.
  • The Fulfillment Orders API now supports apps placing fulfillment holds on items for backorders or pre-orders before the item is available for fulfillment.
  • API clients can now use the Customer API to retrieve, add, and update customers' consent to receive marketing materials by SMS.
  • You can now use metafield definitions to create additional validation constraints for metafields. You can also use standard metafield definitions, which have specific meanings for common use cases and help merchants manage their data.

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 Removed full permission on User resourceRemoved full permission on User resource

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

As of API version 2021-10, only the complete list of explicit permissions that a user with the full permission has access to is returned in the permissions property. The full permission value is excluded from the response.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

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

Anchor to App added to orders ,[object Object]App added to orders

Use the GraphQL Admin API find out what application created an order.

New field

  • orderApp field was added to Order object

    New type

  • orderApp object was added

Anchor to Bulk operations ,[object Object]Bulk operations

Use the GraphQL Admin API to query the type of the bulk operation. You can also subscribe to the bulk_operations/finish webhook topic to be notified when a bulk operation has completed, failed, or been cancelled.

The bulkProductResourceFeedbackCreate mutation allows you to create up to 50 feedback entries on a product resource in a single API request. You can also query for product resource feedback with the productResourceFeedback field.

New field

  • type field was added to BulkOperation object

  • productResourceFeedback field was added to object QueryRoot

    New types

  • bulkProductResourceFeedbackCreate mutation was added

  • ProductResourceFeedbackInput input object was added

  • ProductResourceFeedback object was added

  • ResourceFeedbackState enum was added

    New topics

  • BULK_OPERATIONS_FINISH value was added to enum WebhookSubscriptionTopic

Anchor to Channel apps: onboarding merchants ,[object Object]Channel apps: onboarding merchants

Use the GraphQL Admin API to query whether a shop is approved for onboarding to channel apps. Use this query to accelerate the onboarding process for verified merchants.

New types

  • MerchantApprovalSignals object type was added

    New fields

  • verifiedByShopify field was added

  • identityVerified field was added

Anchor to Contextual pricing for products,[object Object]Contextual pricing for products

Use the GraphQL Admin API to return the price a customer will pay for a product given a particular context, such as the customer's country. Using contextual pricing, you can query the Product object for a price range, or the ProductVariant object for a price, based on the specified context.

New field

  • contextualPricing field was added to Product and ProductVariant objects

    New types

  • ProductContextualPricing object was added

  • ProductVariantContextualPricing object was added

  • Contextual​Pricing​Context input object was added

Anchor to Customer credit cards ,[object Object]Customer credit cards

Use the GraphQL Admin API to query the source (for example, Apple Pay) and the last four digits of a customer's credit card.

New fields

  • source field was added to CustomerCreditCard object
  • virtualLastDigits field was added to CustomerCreditCard object

Anchor to Fulfillment orders: location address,[object Object]Fulfillment orders: location address

Use the GraphQL Admin API to query the address of the location where an order was fulfilled.

New types

  • FulfillmentOriginAddressInput input object was added
  • originAddress field was added to FulfillmentV2Input input object
  • originAddress field was added to Fulfillment object
  • originAddress field was added to fulfillmentCreate mutation

Anchor to Manual fulfillment holds ,[object Object]Manual fulfillment holds

Use the GraphQL Admin API to manually create a fulfillment hold when an order isn't ready for fulfillment immediately. For example, you could create a fulfillment hold if one of the items is backordered, or if an item was preordered before the item's release date.

New values

  • release_hold value was added to FulfillmentOrderAction enum

  • hold value was added to FulfillmentOrderAction enum

    New mutations

  • FulfillmentOrderHold mutation was added

  • FulfillmentOrderReleaseHold mutation was added

    New types

  • FulfillmentHold object type was added

  • FulfillmentHoldReason enum was added

    New fields

  • fulfillment_holds field was added to FulfillmentOrder object

Anchor to Metafield definitions ,[object Object]Metafield definitions

Use the GraphQL Admin API to create and manage metafield definitions, which add validation constraints for metafields. You can also use standard metafield definitions, which have specific meanings for common use cases and help merchants manage their data.

New mutations

  • MetafieldDefinitionCreate mutation was added

  • MetafieldDefinitionDelete mutation was added

  • MetafieldDefinitionPin mutation was added

  • MetafieldDefinitionUnpin mutation was added

  • MetafieldDefinitionUpdate mutation was added

  • MetafieldsSet mutation was added

  • StandardMetafieldDefinitionEnable mutation was added

    New types

  • MetafieldDefinition object was added

  • MetafieldDefinitionType object was added

  • MetafieldDefinitionValidation object was added

  • MetafieldDefinitionSupportedValidation object was added

  • StandardMetafieldDefinitionTemplate object was added

  • MetafieldDefinitionInput input object was added

  • MetafieldDefinitionDeleteInput input object was added

  • MetafieldDefinitionUpdateInput input object was added

  • MetafieldDefinitionValidationInput input object was added

  • MetafieldDefinitionPinnedStatus enum was added

  • MetafieldDefinitionValidationStatus enum was added

  • MetafieldValidationStatus enum was added

  • HasMetafieldDefinitions interface was added

  • MetafieldReference union was added

  • MetafieldDefinitionSortKeys sort keys type was added

    New fields

  • definition field was added to Metafield object

  • reference field was added to Metafield object

  • owner field was added to Metafield object

Anchor to Payment methodsPayment methods

Anchor to BreakingBreaking

As of API version 2021-10, you need to implement the new CustomerShopPayAgreement instrument associated with subscription contracts paid using Shop Pay. Use the CustomerShopPayAgreement object and CustomerPaymentInstrument union to store Shop Pay agreements in Shopify that can be used by subscription contracts.

Use the customerPaymentMethodGetUpdateUrl mutation to return a URL that allows a customer to update a specific payment method.

New types

  • CustomerShopPayAgreement object was added

  • CustomerShopPayAgreement object was added as a possible type on CustomerPaymentInstrument union

    New mutation

  • customerPaymentMethodGetUpdateUrl mutation was added

Anchor to Payment terms ,[object Object]Payment terms

Use the GraphQL Admin API to set and track payment terms as part of an order or draft order. Payment terms represent the terms and conditions (for example, payment methods and payment schedules) under which a payment should be processed.

New types

  • PaymentTerms object was added

  • PaymentSchedule object was added

  • PaymentTermsTemplate object was added

  • PaymentTermsType enum was added

    New mutations

  • paymentTermsCreate mutation was added

  • paymentTermsUpdate mutation was added

  • paymentTermsDelete mutation was added

    New fields

  • paymentTermsTemplates field was added to QueryRoot object

  • paymentTerms field was added to Order object

  • paymentTerms field was added to DraftOrder object

  • paymentTerms field was added to DraftOrder input object

    New values

  • PAYMENT_TERMS_CREATE value was added to enum WebhookSubscriptionTopic

  • PAYMENT_TERMS_UPDATE value was added to enum WebhookSubscriptionTopic

  • PAYMENT_TERMS_DELETE value was added to enum WebhookSubscriptionTopic

Anchor to Post-purchase: app identifier,[object Object]Post-purchase: app identifier

Use the GraphQL Admin API to find out whether your app is the post-purchase app in use. For example, you might want to let merchants know that your app isn't the one they have selected and prompt them to select your app on the checkout post-purchase page.

New field

  • isPostPurchaseAppInUse field was added to App object

Anchor to Post-purchase: subscriptions,[object Object]Post-purchase: subscriptions

Use the GraphQL Admin API to query the SellingPlanGroup and select the appropriate selling plans in a post-purchase subscription offer using the SellingPlanID.

New connection

  • sellingPlanGroups was added to object Product and ProductVariant

Anchor to Shopify Payments: refund transactions ,[object Object]Shopify Payments: refund transactions

Use the GraphQL Admin API to query Shopify Payments information related to an order refund. For example, you can retrieve the Acquirer Reference Number (ARN) that's generated for Visa or Mastercard refund transactions.

New type

  • ShopifyPaymentsRefundSet object was added

    New field

  • refundSet field was added to ShopifyPaymentsTransactionSet object

Anchor to SMS consent ,[object Object]SMS consent

Use the GraphQL Admin API to retrieve, add, and update a customer's consent to receive marketing material by SMS. You can also subscribe to the CUSTOMERS_MARKETING_CONSENT_UPDATE topic to get notified when a customer updates their SMS marketing consent.

New types

  • CustomerSmsMarketingConsentInput object type was added

  • CustomerSmsMarketingConsentUpdateInput input object was added

  • CustomerConsentCollectedFrom object was added

  • CustomerSmsMarketingConsentErrorCode enum was added

  • CustomerSmsMarketingConsentState enum was added

  • CustomerSmsMarketingConsentUpdatePayload object was added

  • CustomerSmsMarketingState enum was added

    New mutations

  • CustomerSMSMarketingConsentUpdate mutation was added

    New fields

  • smsMarketingConsent was added to CustomerInput mutation

  • smsMarketingConsent was added to Customer object

    New errors

  • CustomerSmsMarketingConsentError error was added

    New values

  • CUSTOMERS_MARKETING_CONSENT_UPDATE value was added to enum WebhookSubscriptionTopic

Anchor to Subscriptions,[object Object]Subscriptions

Subscribe to the SUBSCRIPTION_BILLING_ATTEMPTS_CHALLENGED webhook topic to get notified when a financial institution challenges the subscription billing attempt charge as per 3D Secure. You can also subscribe to SELLING_PLAN_GROUPS webhook topics to get notified when a selling plan group is created, updated, or deleted.

For detailed information about required scopes and payloads, refer to subscriptions-related webhooks and selling plans-related webhooks.

New topics

Anchor to Translatable resources types added to the Translation API ,[object Object]Translatable resources types added to the Translation API

Use the GraphQL Admin API to create and retrieve translated content for Shopify resources. You can now retrieve the translations for an online store menu title and the body of a packing slip template.

New values

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

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

Anchor to Cart ,[object Object]Cart

Use the Storefront API to interact with a cart during a customer's session. A cart contains the merchandise that a customer intends to purchase, and the estimated cost associated with the cart.

To learn how to create a cart and retrieve it, update cart line items and customer information, and retrieve a checkout URL, refer to Manage a cart with the Storefront API.

New types

  • CartAutomaticDiscountAllocation object type was added

  • CartBuyerIdentityInput input object was added

  • CartBuyerIdentity object type was added

  • CartCodeDiscountAllocation object type was added

  • CartDiscountAllocation interface type was added

  • CartDiscountCode object type was added

  • CartEstimatedCost object type was added

  • CartInput input object was added

  • CartLineEstimatedCost object type was added

  • CartLineInput input object was added

  • CartLineUpdateInput input object was added

  • CartLine object was added

  • CartUserError was added

  • Cart object type was added

  • Merchandise union type was added

    New mutations

  • CartAttributesUpdate mutation was added

  • CartBuyerIdentityUpdate mutation was added

  • CartCreate mutation was added

  • CartDiscountCodesUpdate mutation was added

  • CartLinesAdd mutation was added

  • CartLinesRemove mutation was added

  • CartLinesUpdate mutation was added

  • CartNoteUpdate mutation was added

Anchor to Online store ,[object Object]Online store

Use QueryRoot to fetch a specific blog, collection, page, or product by its unique attributes. You can also use the OnlineStorePublishable interface type to access resources that can be published to the Online Store sales channel (Article, Blog, Collection, Page, and Product).

New fields

  • blog field was added to QueryRoot object

  • collection field was added to QueryRoot object

  • page field was added to QueryRoot object

  • product field was added to QueryRoot object

    New types

  • Article object was added to OnlineStorePublishable interface type

  • Blog object was added to OnlineStorePublishable interface type

  • Collection object was added to OnlineStorePublishable interface type

  • Page object was added to OnlineStorePublishable interface type

  • Product object was added to OnlineStorePublishable interface type

Anchor to REST Admin API changesREST Admin API changes

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

Anchor to Bulk operations ,[object Object]Bulk operations

Subscribe to the bulk_operations/finish webhook topic to be notified when a bulk operation has completed, failed, or been cancelled.

New topics

  • bulk_operations/finish topic was added to Webhook resource

Anchor to Fulfillment: fulfillment line item ID,[object Object]Fulfillment: fulfillment line item ID

Use the REST Admin API to retrieve the fulfillment line item ID associated with a fulfillment. A fulfillment line item represents the quantity of items from an order line item that are included in the fulfillment.

New property

  • fulfillment_line_item_id property was added to Fulfillment resource

Anchor to Fulfillment orders: location address ,[object Object]Fulfillment orders: location address

Use the REST Admin API to request the address of the location where an order was fulfilled.

New property

  • origin_address property was added to Fulfillment resource

Anchor to Manual fulfillment holds ,[object Object]Manual fulfillment holds

Use the REST Admin API to manually create a fulfillment hold when an order isn't ready for fulfillment immediately. For example, you could create a fulfillment hold if one of the items is backordered, or if an item was preordered before the item's release date.

New property

  • fulfillment_holds property was added to FulfillmentOrder resource

Anchor to Payment terms ,[object Object]Payment terms

Use the Order and Draft Order resources to retrieve payment terms as part of an order or draft order. Payment terms represent the terms and conditions (for example, payment methods and payment schedules) under which a payment should be processed.

New properties

  • payment_terms property was added to /admin/api/2021-10/draft_orders.json

  • payment_terms property was added to /admin/api/2021-10/orders.json

    New topics

  • payment_terms/create topic was added to Webhook resource

  • payment_terms/update topic was added to Webhook resource

  • payment_terms/delete topic was added to Webhook resource

Anchor to SMS consent ,[object Object]SMS consent

Use the Checkout and Abandoned checkouts resources to retrieve whether a customer consents to receive marketing material by SMS and the phone number to which material is sent.

Use the Customer resource to retrieve, add, and update a customer's consent to receive marketing material by SMS.

Subscribe to the customers_marketing_consent/update topic to get notified when a customer updates their SMS marketing consent.

New properties

  • buyer_accepts_sms_marketing property was added to Checkout and Abandoned checkouts resources

  • sms_marketing_phone property was added to Checkout and Abandoned checkouts resources

  • sms_marketing_consent property was added to Customer resource

    New topics

  • customers_marketing_consent/update topic was added to Webhook resource

Anchor to Shopify Payments: refund transactions ,[object Object]Shopify Payments: refund transactions

Use the REST Admin API to query Shopify Payments information related to an order refund. For example, you can retrieve the Acquirer Reference Number (ARN) that's generated for Visa or Mastercard refund transactions.

New property

  • payments_refund_attributes property was added to Transaction resource

Anchor to Subscriptions,[object Object]Subscriptions

Subscribe to the subscription_billing_attempts/challenged webhook topic to get notified when a financial institution challenges the subscription billing attempt charge as per 3D Secure. You can also subscribe to selling_plan_groups webhook topics to get notified when a selling plan group is created, updated, or deleted.

For detailed information about required scopes and payloads, refer to subscription-related webhooks and selling plans-related webhooks.

New topics

  • selling_plan_groups/create topic was added to Webhook resource
  • selling_plan_groups/update topic was added to Webhook resource
  • selling_plan_groups/delete topic was added to Webhook resource
  • subscription_billing_attempts/challenged topic was added to Webhook resource

Anchor to User permissionsUser permissions

Anchor to BreakingBreaking

As of API version 2021-10, the full permission is no longer a potential value of the permissions property on the REST User resource. This update follows the change to API version 2021-07, which returned a complete list of explicit permissions for a user.

Removed values

  • full value was removed from permissions property
Was this page helpful?