--- title: 2021-10 release notes description: Update your app from API version 2021-07 to 2021-10. api_name: release-notes source_url: html: 'https://shopify.dev/docs/api/release-notes/previous-versions/2021-10' md: 'https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md' --- ExpandOn this page * [Breaking changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#breaking-changes) * [Graph​QL Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#graphql-admin-api-changes) * [Graph​QL Storefront API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#graphql-storefront-api-changes) * [REST Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#rest-admin-api-changes) # 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](https://shopify.dev/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 date | Date version is no longer supported | | - | - | | October 1, 2021 | October 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](https://shopify.dev/docs/api/storefront/reference/cart) 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](https://shopify.dev/docs/api/storefront/reference/common-objects/queryroot) object to fetch individual resources directly. You can query blogs, collections, pages, and products by ID or a handle. * The [Bulk Operations API](https://shopify.dev/docs/api/admin-graphql/latest/objects/bulkoperation) 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](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentorderhold) 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/customer) to retrieve, add, and update customers' consent to receive marketing materials by SMS. * You can now use [metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions) to create additional validation constraints for metafields. You can also use [standard metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-standard-definitions), which have specific meanings for common use cases and help merchants manage their data. *** ## 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. ### Removed full permission on User resource In API version 2021-07, the `permissions` property in the [REST User resource](https://shopify.dev/docs/api/admin-rest/latest/resources/user) 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. *** ## Graph​QL Admin API changes Below are all the changes currently introduced in the 2021-10 version of the GraphQL Admin API. ### App added to orders Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/orderapp) find out what application created an order. **New field** * `orderApp` field was added to `Order` object **New type** * `orderApp` object was added ### Bulk operations Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/bulkoperation) 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) ### Channel apps: onboarding merchants Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/shop) 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 ### 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`](https://shopify.dev/docs/api/admin-graphql/objects/product) object for a price range, or the [`ProductVariant`](https://shopify.dev/docs/api/admin-graphql/objects/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 ### Customer credit cards Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/customercreditcard) 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 ### Fulfillment orders: location address Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/fulfillment) 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 ### Manual fulfillment holds Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/fulfillmentorderhold) 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 ### Metafield definitions Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/metafielddefinition) to create and manage metafield definitions, which add validation constraints for metafields. You can also use [standard metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-standard-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 ### Payment methods #### Breaking As of API version 2021-10, you need to implement the new [CustomerShopPayAgreement](https://shopify.dev/docs/api/admin-graphql/latest/objects/customershoppayagreement) instrument associated with subscription contracts paid using Shop Pay. Use the [CustomerShopPayAgreement](https://shopify.dev/docs/api/admin-graphql/latest/objects/customershoppayagreement) object and [CustomerPaymentInstrument](https://shopify.dev/docs/api/admin-graphql/latest/unions/customerpaymentinstrument) union to store Shop Pay agreements in Shopify that can be used by [subscription contracts](https://shopify.dev/docs/api/admin-graphql/latest/objects/subscriptioncontract). Use the [`customerPaymentMethodGetUpdateUrl`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerpaymentmethodgetupdateurl) mutation to return a URL that allows a customer to [update a specific payment method](https://shopify.dev/docs/apps/build/purchase-options/customer-portal/create-customer-portal#step-4-update-a-customers-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 ### Payment terms Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/paymentterms) 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`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) * `PAYMENT_TERMS_UPDATE` value was added to enum [`WebhookSubscriptionTopic`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) * `PAYMENT_TERMS_DELETE` value was added to enum [`WebhookSubscriptionTopic`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) ### Post-purchase: app identifier Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/app) 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](https://shopify.dev/docs/apps/build/checkout/product-offers/build-a-post-purchase-offer). **New field** * `isPostPurchaseAppInUse` field was added to `App` object ### Post-purchase: subscriptions Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/sellingplangroup) 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` ### Shopify Payments: refund transactions Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/mutations/shopifypaymentsrefundset) 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 ### SMS consent Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/customer) 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`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) ### 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](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts#subscription-related-webhooks) and [selling plans-related webhooks](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans#selling-plans-related-webhooks). **New topics** * `SUBSCRIPTION_BILLING_ATTEMPTS_CHALLENGED` value was added to enum [`WebhookSubscriptionTopic`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) * `SELLING_PLAN_GROUPS_CREATE` value was added to enum [`WebhookSubscriptionTopic`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) * `SELLING_PLAN_GROUPS_UPDATE` value was added to enum [`WebhookSubscriptionTopic`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) * `SELLING_PLAN_GROUPS_DELETE` value was added to enum [`WebhookSubscriptionTopic`](https://shopify.dev/docs/api/admin-graphql/latest/enums/webhooksubscriptiontopic) ### Translatable resources types added to the Translation API Use the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/objects/translation) 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** * `ONLINE_STORE_MENU` value was added to enum [`Translatable​Resource​Type`](https://shopify.dev/docs/api/admin-graphql/latest/enums/translatableresourcetype) * `PACKING_SLIP_TEMPLATE` value was added to enum [`Translatable​Resource​Type`](https://shopify.dev/docs/api/admin-graphql/latest/enums/translatableresourcetype) *** ## Graph​QL Storefront API changes Below are all the changes currently introduced in the 2021-10 version of the GraphQL Storefront API. ### Cart Use the Storefront API to interact with [a cart](https://shopify.dev/docs/api/storefront/reference/cart/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](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage). **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 ### Online store Use [`QueryRoot`](https://shopify.dev/docs/api/storefront/reference/common-objects/queryroot) to fetch a specific blog, collection, page, or product by its unique attributes. You can also use the [`OnlineStorePublishable`](https://shopify.dev/docs/api/storefront/reference/common-objects/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 *** ## REST Admin API changes Below are all the changes currently introduced in the 2021-10 version of the REST Admin API. ### 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](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource ### Fulfillment: fulfillment line item ID Use the [REST Admin API](https://shopify.dev/docs/api/admin-rest/latest/resources/fulfillment) 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 ### Fulfillment orders: location address Use the [REST Admin API](https://shopify.dev/docs/api/admin-rest/latest/resources/fulfillment) to request the address of the location where an order was fulfilled. **New property** * `origin_address` property was added to `Fulfillment` resource ### Manual fulfillment holds Use the [REST Admin API](https://shopify.dev/docs/api/admin-rest/latest/resources/fulfillmentorder#hold-2021-10) 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 ### Payment terms Use the [Order](https://shopify.dev/docs/api/admin-rest/latest/resources/order) and [Draft Order](https://shopify.dev/docs/api/admin-rest/latest/resources/draftorder) 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](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource * `payment_terms/update` topic was added to [Webhook](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource * `payment_terms/delete` topic was added to [Webhook](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource ### SMS consent Use the [Checkout](https://shopify.dev/docs/api/admin-rest/latest/resources/checkout) and [Abandoned checkouts](https://shopify.dev/docs/api/admin-rest/latest/resources/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](https://shopify.dev/docs/api/admin-rest/latest/resources/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](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource ### Shopify Payments: refund transactions Use the [REST Admin API](https://shopify.dev/docs/api/admin-rest/latest/resources/transaction) 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 ### 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](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts#subscription-related-webhooks) and [selling plans-related webhooks](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/selling-plans#selling-plans-related-webhooks). **New topics** * `selling_plan_groups/create` topic was added to [Webhook](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource * `selling_plan_groups/update` topic was added to [Webhook](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource * `selling_plan_groups/delete` topic was added to [Webhook](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource * `subscription_billing_attempts/challenged` topic was added to [Webhook](https://shopify.dev/docs/api/admin-rest/latest/resources/webhook) resource ### User permissions #### Breaking As of API version 2021-10, the `full` permission is no longer a potential value of the `permissions` property on the [REST User resource](https://shopify.dev/docs/api/admin-rest/latest/resources/user). 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 *** * [Breaking changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#breaking-changes) * [Graph​QL Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#graphql-admin-api-changes) * [Graph​QL Storefront API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#graphql-storefront-api-changes) * [REST Admin API changes](https://shopify.dev/docs/api/release-notes/previous-versions/2021-10.md#rest-admin-api-changes)