2021-10 release notes

Release date Date version is no longer supported
October 1, 2021 October 1, 2022

The 2020-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.

Breaking changes

These changes require special attention. If your app uses these API resources and you don’t upgrade to a more recent API version, then your app will break.

Removed 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.

GraphQL Admin API changes

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

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

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

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

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

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

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

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

Use the GraphQL Admin API to specify the Multipurpose Internet Mail Extensions (MIME) type of generic files being created, updated, or deleted. Response bodies will return either nil or the MIME type of the generic file, such as video/mp4, model/usd, or application/pdf.

New field

  • mimeType was added to GenericFile object

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

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

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

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

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

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

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

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

GraphQL Storefront API changes

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

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

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

REST Admin API changes

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

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

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

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

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

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

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

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

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

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