Developer changelog

The .dev Assistant now converts REST requests to GraphQL operations. Just copy and paste your REST request, and receive the equivalent GraphQL Admin API query or mutation.

Plus, your conversations with the .dev Assistant just got smarter! You can now ask follow-up questions while maintaining context from your original prompt - no need to start over.

Ready to try it? Head to Shopify.dev and give it a spin.

As of Dec 4th, 2024, you can use the settings under checkoutBrandingInput (see: merchandiseThumbnail) in the Checkout Branding API to modify the appearance of line items in Checkout and Customer Accounts order summary for Shopify Plus merchants.

These line-item customizations include the ability to configure custom aspect ratios for product thumbnails, adjust image fit, and modify the background color of quantity badges. 

Note: The aspect ratio setting is only available on the current unstable release. 

Learn more under checkoutBrandingInput in the Checkout Branding API documentation.

Starting December 5, 2024, app extensions, including admin links, checkout extensibility, and theme app extensions can’t be used to advertise your app, promote related apps, or request reviews.

As of December 4th, 2024, you can now request access to the Chat API to offer real-time customer support on the Checkout and Thank you pages. You will get a new chat component to embed your chat app into Checkout and have complete control over the styling of your interface.

The Chat API allows your chat widget to communicate with your app to query information about the Checkout and Store, like cart details, buyer information, store settings, etc.

Request access to the Chat API through your partner dashboard.

Starting in API version 2025-01, PrivateMetafield will be removed from the GraphQL Admin API. Use app-data metafields instead. If the metafield is needed per resource, consider the migration guide for using app-reserved namespaces.

Apps on Admin API version 2024-10 can use the new optional_scopes app configuration to:

• Separate required scopes from optional
• Request unique sets of access scopes on a store-by-store basis
• Revoke optional scopes granted to the app from a store
• Request and revoke scopes in-context, at app runtime

All while taking advantage of Shopify managed install.

Declaring optional scopes

In your app configuration, specify optional scopes that your app may request, in addition to your app’s required scopes:

[access_scopes]
scopes = "read_products"
optional_scopes = [ "write_products", "read_discounts", "read_themes" ]

Requesting, revoking, and querying optional scopes at runtime

With optional scopes, apps can prompt merchants to grant their app access either from a server-side API, or from a client-side App Bridge API for a more integrated experience. See our documentation on how to request access scopes dynamically for details.

Granted optional scopes can be dynamically revoked from stores by apps. Our APIs supply a revoke method for this, and we also provide a GraphQL appRevokeAccessScopes mutation.

With optional scopes, apps may need to know which scopes are granted on the current store. We supply a query method that lists the granted scopes on the store. Apps can also manually query the accessScopes field on the AppInstallation object.

Learn more

To learn more about optional scopes, see our documentation on how to manage access scopes. See also our client-side App Bridge Scopes API, and our server-side Remix Scopes API.

The JS Buy SDK is deprecated as of January, 2025. It will no longer be updated or maintained by Shopify past that point. A final major version will be released in January 2025 to remove the SDK's dependency on the deprecated Checkout APIs, replacing them with Cart APIs. Updating to this new version will allow the SDK to continue to function for most use cases.

If you are using the JS Buy SDK, you have two options:

1. Recommended Option: switch to the Storefront API Client a. The Storefront API Client manages the API's authentication information and provides various methods that enable devs to interact with the API. This is the preferred and more future-proof solution. See this migration guide to help you transition.

2. Stopgap Option: Upgrade to JS Buy SDK V3 (coming soon) a. This allows you to maintain your current setup with minimal changes for use cases that are supported by the Cart API. A migration guide with details on supported use cases will be available soon. If you choose this option, we still recommend that you switch to the Storefront API Client in the future.

Critical Deadline: July 1st, 2025. You must implement one of these changes by this date, or customers will not be able to complete purchases. Please choose the option that best suits your needs and timelines.

As of 2025-01, you can use the PickupAddress field in both SubscriptionDeliveryMethodPickupOption and SubscriptionPickupOption to query for a customer pickup address.

Learn more about this field at PickupAddress

We've expanded the capability of our discount management system by increasing the limit for automatic app-based discounts from 5 to 25.

This update allows developers to create and manage a larger number of concurrent discount campaigns, offering more flexibility and targeted promotional strategies for merchants. The limit increase enables developers who are currently managing multiple promotions using Shopify Scripts to migrate to Shopify Functions. With the limit increase on Shopify Functions, each discount can be configured with its own start and end dates, giving merchants better precision in promotional timing and controls to govern which discounts can coexist on a cart.

Learn more about discount combinations & limits in the Shopify Dev Docs.

Merchants can now search and browse apps based on a specific category feature in the Shopify App Store. Keep your apps updated with the most relevant category features and follow our best practices.

You can now use more dynamic source attributes in the online store editor. The following new attributes have been added:

• Product: url, featured_image, description
• Collection: url, description
• Article: author, comments_count, content, excerpt
• Blog: content

Learn more about dynamic sources on Shopify.dev.

Apps that are strongly-matched to brand term searches will now be highlighted in search results.

• When a merchant searches for a specific app (e.g. Shopify Inbox), we use organic search results and behavioral data to find the matching app. The high-match app is now prominently featured at the top of search results, above ads.
• This treatment is automatically applied when your app listing is optimized and shows strong branded search match.
• Make sure your app has a specific brand name and follow our best practices around improving organic search.

In addition, we’ve removed the list of restricted keywords previously implemented for search ads.

• More keywords are now available for bidding, including previously restricted brand terms.
• We are ensuring a more equitable advertising environment and to align Shopify's ad products with industry standards and the familiar patterns of other search ad platforms.

As a part of the Customer Account Extensibility Developer Preview, you can now add, remove, or edit menu items in your customer account header menu. This update helps you better understand how merchants will be able to add any type of link to their customer accounts main menu.

Included in this update:

All full-page extensions are now linkable - Before this update, full-page extensions had to be explicitly declared as linkable. Now, all full-page extensions will be linkable by default and merchants will be prompted in the checkout & accounts editor to add a link to your full-page extension in the header menu. To take advantage of this change, deploy a new version of your extension.

To prevent merchants from linking to your page, declare your extension as not linkable.

Add any type of link - Including links to default online store pages (products, collections, pages), customer account pages (order, profile and settings), customer account apps (full-page extensions), as well as any URL. By default, the menu will link to online store (Home), and Orders.

Use the same menu across online store & customer accounts - Merchants will be able to use the same menu in their online store and customer accounts.

Navigation has moved - You can now find the navigation tool in Admin > Content > Menus. It has been moved from its original location of Online Store > Navigation.

You can learn more about full-page extensions here.

As of GraphQL Admin API version 2025-01, the manualPaymentGateway field will be added to orderTransaction object. This field indicates if the transaction is processed by a manual payment gateway.

Category-specific criteria are now available. This feature gives developers more clarity on the category-specific criteria that apply to certain Built for Shopify apps. To view or update your app's category, check its distribution page in your Partner Dashboard.

Your app's pre-selected category is based on its categorization in the Shopify App Store. You can update your category based on your app's functionality. Built for Shopify reviewers have final approval on all categorizations.

Starting in January 2025, all Built for Shopify reviews will require accurate categorization. This applies to existing Built for Shopify apps, as well as new applications.

As of Shopify CLI 3.70, existing Marketing Activity Extensions can be migrated from the Partner Dashboard to CLI. Learn more about how to import and migrate your Marketing Activity Extensions to CLI here

As of Nov 12, 2024, you can use the HideOperation in the Payment Customization Function API to disable native gift card functionality and Shopify-integrated third-party gift card systems. Disabling gift cards hides the gift card field, removes any applied gift cards, and prevents any gift cards from being applied by UI extensions.

The ability to disable the gift card field is available in the unstable API version and will be released to the stable 2025-01 API version.

Learn more about payment customizations.

As part of a move towards open-source fonts, and in an effort to refine our font offerings, we have deprecated some fonts in our library. We’re also expanding the library of open-source fonts, with 32 new high quality typefaces available today.

Action Required: For theme developers with published themes in the Shopify theme store using any of the deprecated fonts, please replace your default font for each preset by January 3, 2025. We have provided recommended replacements in the developer documentation that maintain a similar style to the deprecated font, or you can choose any other available font from our library.

Merchants who are currently using deprecated fonts will be prompted to make updates at a later date.

As of today discount apps can use Admin UI extensions to embed discount configuration UI directly into the discount details page.

Admin UI extensions are hosted by Shopify, which means you no longer need to build and maintain your own web infrastructure to host the UI that configures your discount function's metafields.

Learn more by following this tutorial on building a discount UI with UI extensions and browse the available Admin UI components here.

The Built for Shopify category-specific criteria assessments are now available for Fulfillment service apps. You can review whether these requirements apply to your Built for Shopify app by checking its distribution page through your Partner Dashboard.

These assessments apply to existing Built for Shopify apps, as well as new applications.

On February 28, 2025, POS Links, POS cart app extensions, and POS product recommendations will be deprecated. Developers and merchants will no longer be able to view or access these extensions in Shopify POS.

We recommend you rebuild legacy extensions with POS UI Extensions. Not only do POS UI Extensions have extensive capabilities today, but we’ll continue to grow these capabilities into the future.

POS Links: * Recommendation: Rebuild using POS UI Extensions * Alternative: Embed your app within Shopify POS via the Partner Dashboard, Please note that merchants can manually add and access these from the smart grid.

Cart App Extensions and Product Recommendation Extensions: * Recommendation: Rebuild using POS UI Extensions. POS UI extensions provide necessary components and APIs to develop extensions that run natively on Shopify POS.

If you have any questions, please contact partner support for assistance.

As of 2025-01 the metafieldDelete Admin API method is being removed. The metafieldsDelete method should be used instead. The former relies on the Metafield GID, while the latter takes an array of Metafield Identifiers composed of ownerId, namspace, and key. Note that the Metafield GID is not an option in metafieldsDelete.

As of the latest Shopify’s Standard Product Taxonomy version 2024-10, you can now find additional categories, attributes and values across product areas such as Apparel & Accessories, Home & Garden, Sporting Goods, and more. The taxonomy is an evolving library that’s informed by user feedback and market insights, with each release aiming to help you more accurately classify your products.

More details about this update can be found in the release notes.

The handling of GraphQL requests via HTTP will evolve slightly as of 2025-01 API versions in accordance with the GraphQL over HTTP spec. These changes refine how a request's Content-Type and Accept headers work, and offer additional granularity in response status codes.

New response format

A new application/graphql-response+json response format is available. Requests may select this format using the Accept header, for example:

Accept: application/graphql-response+json, application/json

The above favors receiving a application/graphql-response+json response by listing it first. This new format is the same as JSON aside from its status codes:

200 OK

• For application/graphql-response+json, this status indicates that the JSON payload was valid and that the submitted GraphQL document attempted execution on the server. Note that the response payload may still contain errors encountered during execution along with partial data.
• For application/json, this status only indicates that the JSON payload was valid.

400 Bad Request

• For application/graphql-response+json, this status indicates that the JSON payload was invalid, or that the submitted GraphQL parameters failed static validation and were not executed.
• For application/json, this status only indicates that the JSON payload was invalid.

Usage summary

For requests to 2025-01 versions and after:

• Use the /graphql endpoint. Using /graphql.json will automatically respond with application/json as it does now.
• The request body must contain a spec JSON encoding.
• The Content-Type header must specify application/json. The legacy application/graphql request format is no longer supported. Requests with no supported content type will receive a 415 Unsupported Media Type response.
• The Accept header now supports application/graphql-response+json and/or application/json response formats. Requests with no supported accept types will receive a 406 Not Acceptable response.
• Accepting */* will default to a application/graphql-response+json response.

These changes do NOT affect unstable versions at this time, or Storefront API. A breaking change announcement with migration timeline will be announced prior to any unstable transition.

The Content-Type: application/graphql request format is deprecated and will no longer be accepted as of 2025-01 schema versions. As of 2025-01 schemas, all requests must specify Content-Type: application/json and post a spec encoded body. See GraphQL Over HTTP update for more details.

As of the 2025-01 release of the Admin GraphQL API, the deprecated multiLocation field on ShopFeatures will be removed.

Use the locationsCount query to determine how many locations a shop has.

As of Oct 31, 2024, merchants can now manage their apps using the new Apps tab, which includes app extension collections.

Note: If your app contains customer account UI extensions, these extensions won't be shown to merchants until customer account UI extensions is released in December.

Learn more about the Apps tab in the Shopify Help Center.

We've added two new theme setting types: metaobject and metaobject_list so theme and app developers can write sections and blocks that consume metaobjects of a specified type.

For theme store themes, developers must only use standard metaobject definitions since custom metaobject definitions are unique to a store.

Learn more about the new metaobject and metaobject_list theme settings on Shopify.dev.

Hydrogen v2024.10.0 is out today. The October 2024 Hydrogen release supports the 2024-10 Storefront API and contains several optimizations and bug fixes, including:

• Cart warnings support (#2572)
• Product option updates (#2538)
• Hydrogen supports worker compatibility date (#2380)
• Shopify cookie banner no longer is the default set up in skeleton (#2588)
• Update createWithCache (#2546)
• Release stable sitemaps utility functions (#2589)
• Decode product variant encoding functions (#2425)
• Route warnings (#2613)
• Analytics fixes (#2538)
• Optimistic cart banner (#2502)
• Aside improvements (#2503)
• Use datalist for query suggestions (#2506)
• Remove unstable re-exports from remix-oxygen package (#2551)
• Update MiniOxygen to latest workerd version (#2567)
• <Image/> local asset fix (#2573)
• Update <ProductPrice> to remove deprecated code usage for priceV2 and compareAtPriceV2. Remove export for getCustomerprivacy (#2601)
• Remove deprecated --worker Shopify CLI flag (#2603)
• Allow generated codegen files to be placed anywhere in the directory (#2600)
• Add optional headers param for customer logout redirect (#2602)

Check out our full Hydrogen October 2024 release blog post for more details. And please drop your comments, feedback, and suggestions in GitHub Discussions!

Effectively immediately, metafields without a type value will return "string" instead of blank. For example, this check will no longer be true

{% if metafield.type == blank %}
  This will no longer render.
{% endif %}

Instead, a value of string will be returned:

{% if metafield.type == 'string' %}
  This metafield is of type `string`.
{% endif %}

Action Required: Developers currently using the BOOMR variables for theme identification and customization should begin transitioning to window.Shopify.theme properties. The BOOMR variables will be removed on 31/01/2025, after which window.Shopify.theme.schema_name and window.Shopify.theme.schema_version should be used exclusively.

Deprecation of BOOMR Script: The BOOMR (Boomerang) JavaScript library was used for collecting Web Performance data on storefronts and it’s now been replaced with a leaner and more conformant library. Some theme and app developers had been relying on a few variables set by BOOMR. These variables include: - BOOMR.themeName - BOOMR.themeVersion

These variables will continue to be available until 31st Janurary 2025, allowing developers to transition to the new method of accessing theme information.

Introduction of Enhanced Theme Information on window.Shopify.theme: In response to developer feedback, we are enhancing the window.Shopify.theme object. Starting today, it will include two new properties: - schema_name: Reflects the name attribute from the theme's settings_schema.json. - schema_version: Reflects the version attribute from the theme's settings_schema.json.

These additions aim to provide a standardized and reliable method for accessing theme information directly from the Shopify global object.

We’re rolling out new standard events to web pixels that enable you to better understand the issues that buyers encounter in checkout. Merchants can now capture specific alerts seen by buyers, such as inline field validations and page-level alerts, and errors from Checkout UI Extensions. Any pixels subscribing to all standard events will automatically receive these new types.

Learn more about the new events here.

From the week commencing 28th October 2024, the following changes to CAPTCHA protection will occur:

Classic Customer Accounts: Removal of the /challenge page for Login, Create Account and Reset Password flows

If hCaptcha is enabled in Admin for these forms, they will now require a valid hCaptcha token as part of the form submission, otherwise a 400 error response will be returned.

Form submissions that fail the hCaptcha assessment will also return a 400 error response.

The vast majority of form submissions already comply with this requirement, due to hCaptcha being automatically wired up to forms with the correct markup. More information is available in the dev docs

Full deprecation of reCAPTCHA on Storefront forms

The recent migration to hCaptcha on all Storefront forms is now complete. Applications or themes that have bespoke code that submits a reCAPTCHA v3 token (site key 6LeHG2ApAAAAAO4rPaDW-qVpPKPOBfjbCpzJB9ey) will need to update to use hCaptcha. All form submissions containing a recaptcha-v3-token field will result in a 400 error response.

Again, the vast majority of form submissions already comply with this requirement. If you application or theme invokes the reCAPTCHA api directly, ie via methods on window.grecaptcha then you will need to make changes. More information on wiring forms with hCaptcha using methods supported by Shopify is available in the dev docs

As of the 2025-01 API version, the heldBy string field on the fulfillmentHold GraphQL object will be replaced by the newly introduced heldByApp object field.

This new field provides access to all attributes of the App object, unlike the deprecated heldBy field, which only indicated the app's title.

If you currently query fulfillmentHold.heldBy, you should transition to querying fulfillmentHold.heldByApp.title.

A full-page extension target (customer-account.page.render or customer-account.order.page.render) can no longer coexist with any other targets in the same extension. This change improves performance and provides a better merchant experience in the checkout and accounts editor. If your full-page extension is best used with other extensions in your app, create an editor extension collection to encourage merchants to add all the extensions in the collection.

This change will only impact the deployment of new extensions or new versions of existing extensions. Existing extensions will not be affected until a new version is deployed.

The grace period for the following criteria have been extended to 60 days from the current 30:

• Minimizes impact on store speed
  
• Minimizes impact on checkout speed
  
• Admin performance: meets 75th percentile Web Vitals targets
  
• Minimum number of installs
  
• Minimum number of reviews
• Minimum app rating
  

The grace period for Fulfillment services and Carrier services criteria will also be set to 60 days when enforcement begins.

As of version 2025-01 of the GraphQL Storefront API, Cart now supports removing Gift Cards by Id.

After a cart has been created and a Gift Card applied - perform the cartGiftCardCodesRemove mutation to remove one or more gift cards.

Starting October 15th, 2025, all Shopify App Store apps that appear in the Shopify admin must use the latest Shopify App Bridge by adding the app-bridge.js script tag to the <head> of each document of your app.

As of API version 2025-01, you can access StringConnection.nodes field shorthand to retrieve an array of strings directly instead of via edges. This connection type is now consistent with other connection types in the schema.

Learn more about StringConnection on GraphQL Admin API and Storefront API.

You can now deep link to editor extension collections in the checkout and accounts editor. This is only available on development stores.

When editor extension collections are released to merchants, you can start deep linking to editor extension collections from your app onboarding to streamline the merchant experience.

Learn more on Shopify.dev

As of October 11, 2024, checkout UI extensions targeting the purchase.checkout.reductions.render-before and purchase.checkout.reductions.render-after extension targets will now render in the order summary at the top of the page for one page mobile checkouts. Previously, extensions in these targets would only appear in the order summary at the bottom of the page. This will apply to checkout UI extensions on all API versions.

For more details, please follow up in the github issue in our public repo

As of GraphQL Admin API version 2024-10, ShopifyPaymentsPayoutSummary now surfaces ADVANCE_FEES and ADVANCE_GROSS fields.

Learn more about ShopifyPaymentsPayoutSummary on Shopify.dev.

Certain Shopify Function resource limits now scale proportionally to the number of line items in the cart. Starting at 200 line items, your Shopify Function runs will be able to use more resources than before.

This change applies to all Shopify Function runs that include cart lines in their input query.

Learn more about dynamic resource limits and how they're calculated for Shopify Functions on Shopify.dev.

The merchant export in Partners now provides an "Attribution" column that specifies installs that are attributable to Shopify App Store ad clicks. For more information on the Partners merchant export, see here

As of today, you can use the lineItem on FulfillmentOrderLineItem without planning for deprecation. This applies to all API versions.

Learn more about FulfillmentOrderLineItem.lineItem on Shopify.dev.

As of Admin GraphQL API 2025-01 version, CalculateExchangeLineItemInput.variantId and CalculatedExchangeLineItem.variant fields are nullable at schema level.

This is in preparation of future feature changes. In the current state CalculateExchangeLineItemInput.variantId will still be validated via a returned error if not present.

Learn more about CalculateExchangeLineItemInput and CalculatedExchangeLineItem.

As of GraphQL Admin API version 2025-01, the accountOpenerName field will be added to shopifyPaymentsAccount

As of version 2025-01, the Admin API bulk query operation userErrors GraphQL type will change to BulkOperationUserError. The new type includes the same fields as the old type, with the addition of a code field.

As of GraphQL Admin API version 2024-10, ShopifyPaymentsTransactionType now includes ADVANCE and ADVANCE_FUNDING type.

Learn more about ShopifyPaymentsTransactionType on Shopify.dev.

As of GraphQL Admin API version 2024-10, Business Entity attributes will be available for use as a GraphQL object and across relevant types.

You will now be able to query for properties related to the Business Entities that are enabled on your shop and request for these fields on objects that can be associated to a Business Entity.

Business Entity identifiers will also be available on the Order REST Admin API version 2024-10 as well as on webhook payloads.