Developer changelog

Starting with API version 2022-10, we’re introducing updated requirements for apps that use customer data. Updated requirements will be published prior to the release of API version 2022-10.

The protected customer data requirements focus on data minimization, transparency, and security so that Partners can better support merchants' paths towards compliance with privacy and data protection rules.

Learn more about how you can be ready for protected customer data.

As of GraphQL Admin API version 2022-07, a new statistics field has been added to the Customer object for computed customer statistics. It includes a new field predictedSpendTier which indicates the predicted spend of a customer with a shop.

For more information, refer to the CustomerStatistics field in the GraphQL Admin API reference.

With Checkout Extensibility, you can now build apps to customize checkout and Shop Pay. You can leverage Checkout UI extensions and Shopify Functions to surface new functionality, Checkout Branding API to customize styling, and Pixels to track events.

Checkout Extensibility is now available in developer preview.

Learn more about Checkout Extensibility on Shopify.dev.

As of GraphQL Admin API version 2022-07, you can use the Discount APIs to modify combination settings on a discount. This allows a customer to apply more than one discount to their order.

Discount combinations are available now as part of the Checkout extensibility developer preview.

Learn more about how discount combinations work.

The updated Shopify CLI 3.0 is both easier to use and more powerful than ever. With Shopify CLI 3.0, we’ve simplified the development process by reducing the number of commands that you need to get started from 13 to 5.

You can also now leverage a single project for your app and extensions, preview your entire project with one command, and push your entire project together with a single command when you’re finished.

Learn more about Shopify CLI 3.0.

Shopify Functions lets you extend or replace key parts of Shopify’s backend with custom logic. Functions run on Shopify infrastructure, making them both scalable and performant.

Functions are now available in developer preview for product, order, and shipping discounts.

Learn more about Shopify Functions on Shopify.dev.

With the latest App Bridge enhancements, your app will now look, feel, and perform like it’s a part of Shopify.

More specifically, App Bridge mobile apps can now load 85% faster from the Shopify iOS and Android apps when you enable mobile optimization for your embedded app. App Bridge apps can also now leverage full-screen mode, just like our first-party apps, for complex workflows in the Shopify admin. Lastly, apps that use the NavigationMenu component will now have their navigation embedded into the Shopify admin for faster, more natural access.

Learn more about App Bridge on Shopify.dev.

What a relief - app distribution is now decoupled from the app creation flow in the Partner Dashboard! This means you no longer have to select a public or custom app type before you start coding.

We’ve also improved the navigation within the Partner Dashboard and added a Distribution page, where can manage your Shopify App Store listing or generate your merchant install link. Also, if you’re building your app using Shopify CLI, you’ll be able to copy and paste the commands you need to get started right from the dashboard.

Learn more about app distribution and selecting a distribution method.

As of GraphQL Admin API version 2022-07, we have introduced new APIs that enable you to collect deferred payment on an order using a vaulted card belonging to the customer. The orderCreateMandatePayment mutation will be available for charging payments against a vaulted credit card. This API returns a GraphApi::Job and paymentReferenceId. This paymentReferenceId can be used to poll the status of the payment using the orderPaymentStatus query.

As of GraphQL Admin API version 2022-07, we have expanded the Selling Plan API enabling you to integrate support for new deferred purchase options like pre-orders and try before you buy into the Shopify Checkout.

As of GraphQL Admin API version 2022-07, the SellingPlanAnchorInput type has an additional optional field.

cutoff_day represents a fixed cutoff day for each anchor, to be used for monthly and weekly selling plans. Use this method if the cutoff should land on the same day each month.

You can also specify a cutoff using the cutoff field of the SellingPlanRecurringDeliveryPolicyInput type, which represents a duration. Using cutoff, the exact cutoff day could be different based on the number of days in the month.

As part of the GraphQL Storefront API 2022-07 API release, the following are changes to have been made to the Cart and CartLine object:

• New attribute field with a key argument
• estimatedCost is renamed to cost on Cart.
• estimatedCost is renamed to cost on CartLine.
• Add subtotalAmountEstimated, totalAmountEstimated, totalTaxAmountEstimated, totalDutyAmountEstimated to CartCost
• amount is renamed to amountPerQuantity on CartLineCost.
• compareAtAmount is renamed to compareAtAmountPerQuantity on CartLineCost.

Learn more about the Cart object on Shopify.dev.

As of GraphQL Admin API version 2022-07, app developers can now choose their preferred update behavior when upgrading or downgrading merchant application subscriptions.

By specifying the desired AppSubscriptionReplacementBehavior type, app developers can control whether the new subscription goes into effect immediately or is deferred to the end of the current subscription's billing cycle. By default, all app subscription changes will continue with the existing behavior.

Learn more about specifying app subscription replacement behavior on Shopify.dev.

When developing a theme using Shopify CLI, you can now preview your local changes using any theme in a store. To specify a theme, run the Shopify CLI theme serve command with the new -t or --theme flag:

shopify theme serve -t my-unpublished-theme

Previously, developers could only preview changes using development themes.

Caution: Before running shopify theme serve, pull your remote theme to ensure that any recent changes don't get overwritten by your local development files.

Learn more about previewing your theme using Shopify CLI.

In the 2022-01 Storefront API release we removed several deprecated fields. With the 2022-07 release, we're continuing with that effort and removing the following deprecated checkout mutations:

• checkoutGiftCardApply
• checkoutGiftCardRemove
• checkoutEmailUpdate
• checkoutDiscountCodeApply
• checkoutCustomerAssociate
• checkoutCustomerDisassociate
• checkoutCompleteWithTokenizedPayment
• checkoutCompleteWithTokenizedPaymentV2
• checkoutShippingAddressUpdate
• checkoutCompleteWithCreditCard
• checkoutAttributesUpdate

These mutations will continue to be available within the 2022-04 API version until it's sunset in April 2023. For more information on Shopify API versioning, refer to our documentation.

Starting in version 2022-07, support for the XML response format and XML payloads in the Admin REST API is removed. Requests expecting an XML response will result in a 404. Requests that send an XML payload will result in a 415.

As of May 9, 2022, you can use the GraphQL Admin API unstable version to surface custom content to buyers in a specific market, including custom content for a store’s default language.

This feature enables merchants to provide the following kinds of localized and custom content:

• Support showing regional spelling or preferred terms. For example, a “Sweaters” menu title for a United States market, and a “Jumpers” menu title for a United Kingdom market.
• Display promotional content based on the buyer’s market. For example, a custom Thanksgiving announcement bar in October for Canadian buyers.

For more information, refer to examples in our developer documentation for the translationsRegister, translationsRemove, and translatableResource mutations.

A much wider range of optimized GIFs, including LZW compression, are now accepted for upload.

To learn more about which image formats Shopify accepts refer to: https://help.shopify.com/en/manual/online-store/images/theme-images#image-formats

Google Pay payments are now accepted for recurring transactions. For these transactions, the CustomerCreditCard will have a source of google_pay.

For more information, refer to Building subscription apps.

Based on your feedback, we've updated the number of sections and blocks you can add within a template. You can now add up to 25 sections per template and 50 blocks per section within each template.

This will support use cases like: * Adding more blocks to an FAQ section * Adding multiple profile sections on the About Us page * Creating multiple areas of focus on the homepage * Section and block support for very large collections

You can specify a lower limit with the max_blocks attribute.

Learn more about section and block limits in our theme architecture documentation.

The TranslationsRemove endpoint now supports deleting translations that are stored in asset files.

Learn more about the TranslationsRemove endpoint.

As of GraphQL Storefront API version 2022-04, a new checkoutChargeAmount field has been added to Cart. It indicates the subtotal amount to be paid for this cart at checkout, not including any deferred payments. This field is currently restricted behind the extend_selling_plans_api beta flag.

The checkoutChargeAmount field is similar to the subtotal field. The subtotal field indicates the subtotal that will be paid altogether, including any payments that will be made at a later date. The checkoutChargeAmount is the actual price that will be paid at the time of checkout.

The visibility of an app block, or app embed block, of a theme app extension can now be controlled based on a custom condition.

The condition can be included in the block's schema with the available_if attribute, and the state of the condition is stored in an app-owned metafield. The metafield can be accessed through the Liquid app object.

To learn more about conditional app blocks, refer to Theme app extensions framework.

A new Liquid app object is available for use within the context of theme app extensions and app proxies. The app object can be used to access an app's metafields.

Refer to the app object documentation for more information.

As of GraphQL Admin API version 2022-04, a new deliveryGroups connection has been added to cart. It consists of a group of delivery options available for the line items in the cart, for a specified shipping address. Delivery groups are only available for logged-in customers with a full default address.

Refer to our documentation on cartCreate and customerCreate to learn more about how to create a cart associated with a logged-in customer.

The accepts marketing and related fields were used to indicate if a customer subscribed to all marketing channels. In 2021, we started separating marketing consent into SMS and email channels by introducing SMS marketing consent.

In API version 2022-04, we’re completing that split by deprecating the accepts marketing fields and replacing them with email marketing consent fields. You’ll need to update your apps to use the SMS and email marketing consent fields to send the opt-in level, consent state and the time at which the consent was granted, instead of a simple Boolean to express the marketing consent of customers.

As of GraphQL Admin API version 2022-04, we're deprecating the acceptsMarketing, acceptsMarketingUpdatedAt and marketingOptInLevel fields on the Customer object and CustomerInput input object.

The deprecated fields are replaced by the following new fields, that you can access using the emailMarketingConsent field on the CustomerInput object:

• marketingState
• consentUpdatedAt
• marketingOptInLevel

For more information, refer to the CustomerInput input object on Shopify.dev.

As of REST Admin API version 2022-04, we're deprecating the accepts_marketing, accepts_marketing_updated_at and marketing_opt_in_level fields on the Customer resource.

The deprecated fields are replaced by the following properties on the new email_marketing_consent field for the Customer resource:

• state
• consent_updated_at
• opt_in_level

For more information, refer to the Customer resource on Shopify.dev.

The following are changes to the GraphQL Admin API's Customer object:

• The orders_count field is renamed to number_of_orders.
• The total_spent and total_spent_v2 fields are replaced by amount_spent.
• The has_note field is removed. The note field still exists on the customer.
• The has_timeline_comment field is removed. To query for comments on the timeline, use the events connection and a query argument containing verb:comment, or look for a CommentEvent in the __typename of events.

For more information, refer to the Customer object.

As of the 2022-04 version of the Storefront API, you can fetch a navigation menu by handle with the menu field. The new field returns a Menu object, and can be used to replicate a merchant's Online Store menus on custom storefronts.

As of API version 2022-04, the GraphQL Admin API's FilterType enum has a new value(BOOLEAN). The BOOLEAN value is assigned when a filter is based off a boolean type metafield definition.

For more information, refer to the Filter object.

As of version 2022-04, the @inContext directive in the Storefront API accepts a language argument in addition to country. If the requested language is active for the given country, as configured within the shop's Market settings, then the query will return translated values.

The list of available languages can be accessed with this query:

query Localization @inContext(country: CA, language: FR) {
  localization {
    # for the current country
    availableLanguages {
      isoCode
      endonymName
    }
    # and for non-current countries
    availableCountries {
      isoCode
      name
      availableLanguages {
        isoCode
        endonymName
      }
    }
  }
}

If an unsupported language or country is requested via @inContext, the response will fall back to supported values. In all cases, the actual country and language context will be returned as a response extension.

{
  "data": {
    "productByHandle": {
      "title": "Cat bed",
      "variants": {
        "edges": [
          {
            "node": {
              "priceV2": {
                "amount": "100.0",
                "currencyCode": "CAD"
              }
            }
          }
        ]
      }
    }
  },
  "extensions": {
    "context": {
      "country": "CA",
      "language": "EN"
    }
  }
}

Learn more about supporting multiple languages on storefronts.

As of Admin API version 2022-04, two new fields, source_url and source_identifier have been added to the Orders and Checkout objects in both the REST and Graph APIs. The source_name field will also be updated across these APIs for the Orders, Draft Orders and Checkout object. By adding a valid source_name, the order will be attributed to a list of sales channels found within the partner's dashboard.

More information can be found here

As of GraphQL Admin API version 2022-04, a new checkoutCharge field has been added to sellingPlan. It consists of a charge type (either percentage or price), and an amount, indicating how much of the product's cost will be charged at the time of checkout. This field is currently restricted behind the extend_selling_plans_api beta flag.

In the 2022-04 release of the Payments Apps GraphQL API, we're introducing a way to mark payments as pending. To support this, a new mutation can be used in cases where a payment cannot be completed quickly.

New pending mutation

The pending payments feature is now officially available for payments apps. You can mark a payment as pending if the payment can't be completed within a reasonable amount of time. This means buyers won't need to wait for slow transactions to finish before their order is completed. Learn more about pending a payment on Shopify.dev.

Updated pending behaviour in the Admin

While the payment is pending, the actions a merchant can take on the order will be restricted so as to not interfere with the payment that is pending. These restrictions are lifted as soon as the payment is completed or expires. A pending payment will expire if you fail to complete the payment within a reasonable time. Learn more about pending payments in the Shopify Help Center.

Status field deprecation

The status field on payment, refund, capture, and void session objects is deprecated and replaced by the state field introduced in the 2022-04 API release. Pending payments are not supported by the status field and will raise an error.

As of GraphQL Storefront API version 2022-07, the Collection object has a new field: SEO. This field returns an SEO object.

Learn more about this API on Shopify.dev.

As of the 2022-04 version of the Admin GraphQL API, the customAttributes field will be present on the SubscriptionContract, SubscriptionDraft, and SubscriptionDraftIndex objects. Those new fields correspond to the existing field of the same name on the Order object.

This allows you to update a subscription contract draft with new custom attributes. Those attributes will be copied over to new orders created from that subscription contract.

Learn more about SubscriptionContract and subscriptionDraftUpdate on Shopify.dev.

As of GraphQL Admin API version 2022-04, a new originTime field has been added to subscriptionBillingAttempt. Fulfilment intervals for subscriptions are normally calculated using the billing attempt date, but may be overridden with this new field if the billing happens to occur after the current anchor date. This can be done to prevent fulfilment from being pushed to the next anchor date when billing is delayed.

Visit our documentation on Creating a Billing Attempt and Advanced Delivey Behaviours for Subscriptions to learn more about this new field.

As of GraphQL Admin API version 2022-04, the CustomerPaymentMethodRevocationReason object has a new enum value: MERGED. This value is assigned when a customer replaces one payment method with another existing payment method, leaving this revoked payment method with no associated subscription contracts.

Learn more about this API on Shopify.dev.

As of API version 2022-04, the DigitalWallet enum has a new value, FACEBOOK_PAY. This change affects both GraphQL Admin and Storefront APIs.

For more information, refer to the DigitalWallet enum in the GraphQL Admin API reference or Storefront API reference.

As of GraphQL Admin API version 2022-04, app partners can issue prorated credits for the unused portion of the app subscription when a recurring app charge is cancelled. This enables developers to automatically provide app credits to merchants when they uninstall an app or cancel a subscription, and reduce support requests to app partners for refund requests.

For more information, refer to the appSubscriptionCancel mutation.

As of GraphQL Admin API version 2022-04, a new owner type ApiPermission is now available for metafields. A metafield with this permission type will only be readable and writable by the app that owns the metafield.

With the launch of the Markets API as of version 2022-04, price lists are no longer associated with a country, but with a market. We've deprecated the countries field on the PriceListContextRuleInput object and replaced it with a new field called marketId.

For more information, refer to the PriceListContextRuleInput object.

You can now create videos and transcode them to multiple formats, using the FileCreate mutation.

You can also attach videos to metafields using file_reference. These videos are also available using the Storefront API.

As of GraphQL Admin API version 2022-04, checkoutChargeAmount and remainingBalanceChargeAmount fields have been added to sellingPlanAllocation. These fields indicate how much of a product variant's price must be paid upfront, and how much must be paid at a later date. This field is currently restricted behind the extend_selling_plans_api beta flag.

We are introducing new flexible ways for app partners to offer merchants incentives for app subscriptions.

Recurring App Discounts

As of GraphQL Admin API version 2022-04, app developers can now offer limited time discounts on recurring app charges through the Billing API. Partners may define a percentage or fixed amount discount that will be applied to a designated number of billing cycles (e.g. 20% of 6 billing cycles). This will enable app partners to create introductory offers for new merchants.

Learn more about app billing discounts on Shopify.dev.

App Trial Extensions

App developers can increase the number of trial days offered to a recurring app charge by using the new appSubscriptionTrialExtend offered without merchants accepting a new app subscription. This will enable developers to provide new merchants additional time to trial products. App trial extension is currently available in the unstable version of the GraphQL Admin API.

Learn more about trial extensions on Shopify.dev.

In addition to edges, GraphQL connections now have a nodes field. When you only query node on edges, you can simplify the query.

For example:

{ connection { edges { node { fields } } }

can be simplified to:

{ connection { nodes { fields } } }

PageInfo has been expanded as well to include startCursor and endCursor.

When these fields are used in tandem, it can simplify the shape of return data for pagination.

Previous query format:

{ connection { edges { cursor node { fields } } pageInfo { hasNextPage } } }

Improved query format:

{ connection { nodes { fields } pageInfo { hasNextPage endCursor } } }

GraphQL Admin API

As of GraphQL Admin API version 2022-04, we're adding the fulfillBy to the FulfillmentOrder object. The field represents the latest date and time when all items in the fulfillment order need to be fulfilled.

We're also adding the maxDeliveryDateTime and minDeliveryDateTime fields to the DeliveryMethod object. When combined, they represent a range of time when the delivery is expected to be completed.

Learn more about FulfillmentOrder and DeliveryMethod objects.

REST Admin API

As of REST Admin API version 2022-04, the following properties are added to the FulfillmentOrder resource:

• fulfill_by
• delivery_method.max_delivery_date_time
• delivery_method.min_delivery_date_time

Learn more about the FulfillmentOrder resource.

After the release of Shopify Markets, we are following up with the Markets API in version 2022-04. The API allows you to create, update, and delete markets and their settings.

Shopify Markets unlocks the ability to create high-performing, localized buyer experiences by allowing merchants to specify the domain, language, currency and price that international buyers see when browsing a merchant's storefront.

You can learn more about the Markets API on shopify.dev.

Although the INVALID_LOCALE_FOR_SHOP error code was introduced in the 2020-07 version, it has never been used to represent a locale field related error when calling the translationsRegister mutation.

As of GraphQL Admin API version 2022-04, the INVALID_LOCALE_FOR_SHOP error code is used to represent all errors related to the locale field on the Translation object.

Previous verions will still use the INVALID_CODE error code to represent errors related to the locale field.

Theme developers can now use the Shopify CLI theme serve command with the new --theme-editor-sync flag. When active, theme editor changes are automatically synced back to the local development files.

Learn more about Shopify CLI theme commands.

Developers can now programmatically push their scripts and extensions to Shopify from their CI/CD pipelines with CLI authentication tokens.

For more information on how to set up CI/CD for your scripts and extensions, visit our developer documentation.