Developer changelog

To help merchants discover the freshest and most well-integrated themes for their store, we've shipped an update to the Theme Store homepage to highlight Top and New themes (published in the last 60 days).

As of GraphQL Storefront API 2024-10, you can now retrieve product taxonomy categories in storefronts. This information is also available through the Liquid API.

This will allow you to customize the buyer experience in storefronts based on product taxonomy. Learn more about product taxonomy in our help docs.

See Shopify.dev for documentation on the new Liquid object and the upcoming GraphQL type.

As of Graphql Admin Api version 2024-10, calls to mutation inventoryActivate can use an optional parameter stockAtLegacyLocation. Setting this parameter to true will allow inventory to be activated if the locationId provided is associated with a fulfillment service that does not permit sku sharing.

If an item is activated at a location that does not permit sku sharing then the item will be deactivated at all other locations.

If an item is currently active at a location that does not permit sku sharing and you want to activate that item at another location the stockAtLegacyLocation parameter also needs to be set to true.

Learn more about inventoryActivate on Shopify.dev

As of 2024-10, ReverseFulfillmentOrderLineItem.fulfillmentLineItem field is nullable. A ReverseFulfillmentOrderLineItem will not always be associated with a FulfillmentLineItem anymore. The non-null fulfillmentLineItem field on the older API versions will return a graphql error when the fulfillment line item does not exisit.

Learn more about ReverseFulfillmentOrderLineItem on Shopify.dev.

As of Admin GraphQL API version 2024-10, use Order.lineItems instead of lineItemsMutable field to get a list of the order's line items.

Learn more about Order on Shopify.dev.

We are retroactively adding Customer, Order, Company, and Model3d graphql types to the MetafieldReference union for Admin API from 2024-01 and onward.

Additionally, TaxonomyValue will be added in 2024-04 to align with the version the type was introduced.

We are requiring apps to meet at least Level 1 Protected Customer Data Requirements in order to access the Customer Account GraphQL API. This change is applicable to all API versions. We recognize that this may be a breaking change for public apps that use the Customer Account API and is necessary to ensure the protection of customer data.

This change will not impact Hydrogen and Headless storefronts or Custom Apps since they already have access to Level 1 and Level 2 Protected Customer data.

Partners that are part of the Customer Account UI Extensibility developer preview and are calling the Customer Account API from their extensions will need to request access to continue to access the API.

Learn more about Protected Customer Data on shopify.dev.

As of 2024-10 version, we are adding productVariantsCount field to the Admin GraphQL API.

Learn more about productVariantsCount on Shopify.dev.

The following changes have been made:

• Technical criteria checklist has been renamed to Technical criteria
• App distribution page layout has been updated, and the content for some standards have been re-worded for clarity.
  • Added: A new section Category-specific criteria to outline criteria for specific app features.
  • Renamed: Build for performance is now Performance.
  • Renamed: Usefulness criteria is now Merchant utility
  • Combined: Protect app safety, security, and reliability and Design for ease of use are now Design and functionality
  • Removed: Share app info and benefits along with the standard Make sure your app listing content is up-to-date. This standard was intended to encourage completion of new app listing form fields introduced in the past, which all partners now have completed.

• Merchants can now filter themes by 3 new features: "Quick Order List", "Sign in with Shop" & "Swatch Filters". And we have removed 3 feature filters: "Product reviews", "Event Calendar" & "Store Locator".
• Each Theme's listing page has been updated to include quality signals and new styling.
• The order of Theme cards on your Partner-specific "All Theme Page" has changed to be "Newest to Oldest".

As of the 2024-10 release of the GraphQL Admin API, we're removing the error codes: HAS_OPEN_TRANSFERS_ERROR and FAILED_TO_RELOCATE_OPEN_TRANSFERS from LocationDeactivateUserErrorCode.

The error codes were not being returned from the LocationDeactivate mutation, as such, they will no longer be listed as possible error codes.

If you are explicitly checking either of these error codes, you should remove references to them.

As of Admin GraphQL API version 2024-10, you can access Order.statusPageUrl field to retrive the URL where the customer can check the order's current status.

Learn more about Order on Shopify.dev.

As of GraphQL Admin API version 2024-10, we're cleaning up the shopifyPaymentsAccount endpoint and removing several unused fields.

As of Shopify CLI 3.66, log streaming and replay for Shopify Functions is generally available.

Log streaming for Shopify Functions enables faster development, testing, and debugging of functions by bringing function execution logs to Shopify CLI. You can also replay function executions locally using input from these logs.

Learn more about Shopify Functions log streaming on Shopify.dev.

As of GraphQL API version 2024-10, we are expanding media capabilities in the productSet mutation:

• We are adding a new field type FileSetInput, which is a derivative of the FileCreateInput, with an added id field, which results in being able to both work with already existing media and create new files while using the same type.

• ProductSet.mediaIds field is being removed and replaced with the new **files** field, which expands the former's functionality by allowing you to also create new files to be associated with the product specified. This field utilizes the new FileSetInput type.

• ProductSetVariantInput.mediaId is being removed and replaced with **file** field, which will associate the file with the variant. This field utilizes the new FileSetInput type.

For more detailed information and examples, visit our productSet documentation on Shopify.dev.

When accessing metafield namespaces or metaobject types, you no longer need to hard code app--{app_id}. The $app reserved prefix is now available to use in your Liquid files.

Learn more about using reserved prefixes in theme app extensions on Shopify.dev developer docs.

With New Customer Accounts, you can create custom pages using full-page extensions for use cases like loyalty, subscriptions, and exchanges. Soon, merchants will be able to add these pages to their customer account navigation menus if the page is declared linkable.

To prepare for this, you can now declare your full-page extension as linkable by using allow_direct_linking = true in your extension configuration.

Please note that not all full-page extensions are suitable for direct linking. For example, if your extension requires the context of a specific order, it’s best to create an order action or extend the Order Status page to link to your full-page extension instead.

Learn more on Shopify.dev and get a sneak peek of the upcoming merchant experience for editing customer account navigation.

We have improved the design and function of Dynamic Checkout and Accelerated Checkout buttons on storefront pages. These updates ensure that the buttons now support features like Shopify Functions and Product Bundles, providing better performance and a smoother user experience. These changes are now live on development stores and will begin rolling out to all merchants September 15.

Please note that the Accelerated Checkout buttons now hide their HTML in a custom element with a closed shadow DOM. This means that any styling or event tracking that targets the existing HTML structure of these buttons will break.

Please review this guide and the Accelerated checkout button reference to ensure your customizations remain compatible with the latest updates.

We are modifying how cart queries and mutations behave when the Storefront API Cart ID is missing the key param. This behavior is applied retroactively to all versions of the Storefront API.

An example cart ID: gid://shopify/Cart/c1-7a2abe82733a34e84aa472d57fb5c3c1?key=824bdj25mhg1242bdb385

• Queries: Querying a cart without including the key param will result in a cart with the buyer's private details removed.

• Mutations Updating a cart without including the key param will result in an error : The specified cart does not exist.

We are deprecating productChangeStatus mutation. Use productUpdate mutation instead.

You will need to migrate to the new endpoint by January 2025 when we will remove access to the productChangeStatus mutation.

Learn more about product mutations at shopify.dev

Theme cards on the Theme Store have been updated. Theme cards are now:

1. Visually simpler (feature tags have been removed)
2. Have a link to the listing for the Theme title
3. Have a badge to identify Themes that are new to the Theme Store
4. Show a Themes percentage positive reviews, and the number of reviews it's received

No action is needed from Theme developers.

We are extending the promotion period for new Themes. Now, new Themes will be highlighted for a longer period than before.

We've added support for the Link metafield type to the metafield_tag filter in Liquid.

Furthermore, you can now consume Link metafields using dynamic sources in inline_richtext and richtext theme settings. Link metafields will be inserted with the metafield_tag filter by default for these setting types.

Learn more about metafield filters in Shopify.dev

We've added error messages to the Shopify Pixel Helper so that you can more easily debug your custom pixels. The Pixel Helper will display uncaught errors that occur at the top level or in the callback function. Top level errors will be viewable when the Pixel Helper loads. Callback error messages will be viewable when an event with a red dot is expanded.

As of the GraphQL Admin API version 2024-10, we're removing a number of MetafieldStorefrontVisibility-related fields, queries, and mutations.

Use the more flexible MetafieldDefinition.access field instead.

• We're removing MetafieldDefinition.visibleToStorefrontApi.
  • Use MetafieldDefinition.access instead.
• We're removing MetafieldDefinitionInput.visibleToStorefrontApi.
  • Use MetafieldDefinitionInput.access instead.
• We're removing MetafieldDefinitionUpdateInput.visibleToStorefrontApi.
  • Use MetafieldDefinitionUpdateInput.access instead.
• We're removing metafieldStorefrontVisibilityCreate
  • Use MetafieldDefinitionUpdate instead.
• We're removing metafieldStorefrontVisibilityDelete
  • Use MetafieldDefinitionUpdate instead.
• We're removing metafieldStorefrontVisibilities
  • Use MetafieldDefinition.access instead.
• We're removing metafieldStorefrontVisibility
  • Use MetafieldDefinition.access instead.

Learn more about MetafieldDefinition.access at https://shopify.dev/docs/api/admin-graphql/2024-07/objects/MetafieldAccess

Address autocomplete apps can now set latitude, longitude and company name when an address suggestion is selected during checkout. If provided, the coordinates of a delivery address are sent to the Carrier Service API when calculating shipping rates. The company name field can be populated in checkout if the field is enabled for the merchant’s store.

• purchase-address-autocomplete-suggest
• purchase-address-autocomplete-format-suggestion

Hydrogen v2024.7.3 is out today. The August 2024 Hydrogen release contains several quality-of-life improvements, optimizations and bug fixes:

• Custom .env file support (#2392)
• Improved performance of currency formatting (#2372)
• Improved handling of remix.config.js / vite.config.js files (#2379)
• Simplified context creation with a new createHydrogenContext function (#2333)
• Script component now takes a waitForHydration prop (#2389)
• Google web cache fix (#2334)
• Custom logger support for vite.config.js. (#2341)
• Subrequest profiler virtual root fix (#2344)
• CLI: Auth flow fix. (#2331) \

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

As of the GraphQL Admin API version 2024-10, an access argument is being added to the standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable GraphQL mutations.

As of the GraphQL Admin API version 2024-10, we're deprecating the visibleToStorefrontApi argument on the standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable GraphQL mutations. Use the new access argument instead.

The new access argument allows developers to specify more granular access controls when enabling a standard metafield definition template.

Learn more about standardMetafieldDefinitionEnable and standardMetafieldDefinitionsEnable at https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/standardMetafieldDefinitionEnable and https://shopify.dev/docs/api/admin-graphql/unstable/mutations/standardMetafieldDefinitionsEnable.

*Updates to our Partner Program Agreement and API License and Terms of Use *

EFFECTIVE AUGUST 9, 2024 ACTION REQUIRED

We've made changes to our Partner Program Agreement and API License and Terms of Use. These updates include terms that are intended to support the growth of Shopify Partners and Merchants, while maintaining the security and integrity of products and services offered on our platform.

These changes come into effect as of today, August 9, 2024.

We encourage all developers on our platform to review and be familiar with the API License and Terms and the Partner Program Agreement, so that you understand how to build, run, and grow your app and development business on our platform.

For more information and frequently asked questions, please visit the Shopify Help Center.

As of the Admin API version 2024-10, apps will not be able to release fulfillment holds unless they have write access to the fulfillment order that the hold belongs to.

See the fulfillment hold release mutation docs for more information on what scopes are required.

See the API access scopes section of the fulfillment order docs for more information about these scopes.

How will this change effect my app?

This change will only effect apps which release fulfillment holds using the Admin API.

If your app already has write access to the fulfillment orders that you are releasing holds from then your app will continue to be able to release holds as you could previously.

If your app does not currently have the required access scopes then you will need to request the correct access scopes before migrating to the 2024-10 API version.

When using the GraphQL API, if you app attempts to release a hold that it does not have access to, a user error with the code FULFILLMENT_ORDER_NOT_FOUND will be returned and the hold will not be released.

You can now specify the category-related features your app offers. These structured app category details will appear on your App Store listing page and in the app comparison feature.

Fill out the app category details fields on your app listing pages so that merchants can more easily find and assess whether your app meets their needs.

For more information, please refer to our dev documentation.

As of 2024-10 version, the product create and update webhook payload contains information about the product category on a product.

The category field exposes a trimmed version of fields that are available on the Product GraphQL response.

To receive category in the webhook payload, specify version 2024-10 or newer as the webhook API version in your App Partner Dashboard.

Effective from July 29, 2024, a 30-day hold will be applied to your first payout. This change will only impact new partners who have not yet received their first payout. Learn more about payout schedules.

You can now specify the category-related features your app offers for 30 additional categories. Fill out the fields on your app listing pages so that merchants can more easily find and assess whether your app meets their needs. These structured app category details will appear on your App Store listing page and in the app comparison feature.

• Countdown timer
• Metafields
• Forms
• Navigation and menus
• Wishlists
• ERP
• Accounting
• Taxes
• Legal
• Wholesale
• Returns and exchanges
• Geolocation
• Stock alerts
• Pre-orders
• Web push
• Gift cards
• Donations
• Gift wrap and messages
• Giveaways and contests
• Surveys
• Image gallery
• Third-party logistics (3PL)
• Fraud
• Helpdesk
• FAQ
• Delivery and pickup
• Video and livestream
• Event booking
• Accounts and login
• Cash on delivery (COD)

For the other categories that already supports app feature details, see here and here. We plan to support all categories by August 2024.

For more information, please refer to our dev documentation.

The shipping and billing address forms in checkout can now have street name, street number, and neighborhood fields, allowing merchants to collect address data in regionally-accepted formats. The fields that are available depend on the country selected at checkout and if a merchant has additional address fields enabled. You can review the supported countries in the help documentation.

The fields are now available for developers to test with as part of the Checkout Extensibility developer preview. The change will be rolling out to merchants in the coming weeks.

Learn how to make use of this data on Shopify.dev.

We are removing the "All count name are in your cart." error response in favour of the exisiting "You can't add more name to the cart." error response in the Cart Ajax API.

Old behaviour: - When all inventory of a variant are already in the cart and the client requests to add more of that variant to the cart, the error response description is "All count name are in your cart.", and the message is "Cart Error". - When some of the inventory of a variant is in the cart and the client requests to add more of that variant to the cart, so that the total amount in the cart is more than the available inventory, the error response description and message is "You can't add more name to the cart."

New behaviour: - When the client requests to add more than available inventory of a variant already in the cart the error response description and message is "You can't add more name to the cart."

This will affect the update.js, change.js, and add.js endpoints.

We are rolling out changes to CAPTCHA on the following forms on Storefronts:

• Customer Login
• Customer Account Creation
• Reset Password
• Contact Form
• Newsletter Signup
• Blog Comments

The changes include:

1. Migration from Google reCAPTCHA to hCaptcha

We are migrating our CAPTCHA solution to hCaptcha as part of an ongoing effort to reduce form spam. This is an ongoing, phased, rollout, and does not affect our published methods for you to work with CAPTCHA.

2. Alternative methods to bind CAPTCHA to forms

You can now force CAPTCHA wireup to Storefront forms using either declarative markup or JavaScript. This is primarily intended for App/Theme developers who wish to take control of Form submission, for example by constructing hidden forms that POST to Shopify. See the documentation for further information and examples.

3. Strict CAPTCHA validation on form submissions

Previously, forms submitted from Storefronts that contained an invalid or missing CAPTCHA token would redirect to /challenge for the user to solve an interactive CAPTCHA. Such form submissions will now cause a 400 error. Theme and App authors who submit forms to Shopify are strongly encouraged to ensure that their forms work with CAPTCHA enabled, by submitting a valid CAPTCHA without relying on the redirect to /challenge

Orders with multiple shipping lines may be refunded. You can refund shipping amounts using the refundCreate GraphQL mutation, the returnRefund GraphQL mutation, or the Refunds REST API.

As of July 18, 2024, all Admin GraphQL API versions return accurate refunds data for orders with multiple shipping lines.

1. Shipping refunds will be included in the refundShippingLines connection, in addition to shipping lines removed via an order edit.
2. For each refunded shipping line, there will be an OrderAdjustment with kind SHIPPING_REFUND. Previously, there would be a single OrderAdjustment with kind SHIPPING_REFUND regardless of how many shipping lines were present on the order.
3. The RefundAgreement has multiple shipping line sales. Each ShippingLineSale corresponds to exactly one shipping line that was refunded. The ShippingLineSale.shippingLine is now populated for all API versions for the RETURN action type.

As of July 18, 2024, all REST API versions return accurate refunds data for orders with multiple shipping lines.

1. For each refunded shipping line, there will be an order adjustment with kind = shipping_refund in the order_adjustments property. Previously, there would be a single order adjustment with kind = shipping_refund, regardless of how many shipping lines were present on the order.

Please note that Refund.refundShippingLines and RefundAgreement.sales are only available in the Admin GraphQL API. They are not present in the Admin REST API.

In the version 2024-10 release of the Admin GraphQL API, we are making the following changes in the product delete APIs

• The productDeleteAsync mutation will be removed.
• A new synchronous boolean parameter will be added to the productDelete mutation, allowing you to choose whether the product deletion should be processed synchronously or asynchronously.

Key Updates:

• Asynchronous Deletion: By setting the synchronous parameter to false in the productDelete mutation, the operation will proceed asynchronously, returning a ProductDeleteOperation object.
• Operation Tracking: You can track the status of the asynchronous deletion by querying the operation ID through the ProductOperation query.

For more detailed information and examples, visit our ProductDelete documentation on Shopify.dev.

In the version 2024-10 release of the Admin GraphQL API, we are making the following changes in the product duplicate APIs:

The productDuplicateAsyncV2 mutation will be removed.

A new synchronous boolean parameter will be added to the productDuplicate mutation, allowing you to choose whether the product duplication should be processed synchronously or asynchronously.

Key Updates:

Asynchronous Duplication: By setting the synchronous parameter to false in the productDuplicate mutation, the operation will be performed asynchronously, returning a ProductDuplicateOperation object.

Operation Tracking: You can track the status of the asynchronous duplication by querying the operation ID through the ProductOperation query.

For more detailed information and examples, visit our productDuplicate documentation on Shopify.dev.

As of GraphQL Admin API version 2024-10 we're deprecating several singular variant mutations in favor of their bulk version, namely: * productVariantCreate. Use the productVariantsBulkCreate instead. * productVariantUpdate. Use the productVariantsBulkUpdate instead. * productVariantDelete. Use the productVariantsBulkDelete instead.

As of Juy 16th, the structured_data filter outputs product information using the ProductGroup schema.org type, according to the latest recommendations from Google.

As of the GraphQL Admin API version 2024-10, we're deprecating the GREATER_THAN_ZERO and INVALID_LINE_ITEM_QUANTITY error codes on the fulfillmentOrderReleaseHold mutation. These error codes are no longer returned by the mutation.

Hydrogen v2024.7.1 is out today. The July 2024 Hydrogen release contains several new features and bug fixes, including:

• A new useOptimisticVariant hook
• sellingPlanId support for <BuyNowButton />
• New customer account session commit pattern (breaking)
• <VariantSelector /> improved handling of options (breaking)
• Update Remix to 2.10.0 which included fixes to infinite loading error
• Type fixes for optimistic cart
• CLI: Vite bundle analyzer
• CLI: Support CSS options in Vite projects

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

We have introduced a new field, Product.restrictedForResource, which allows you to query product restrictions for a given CalculatedOrder resource. This field returns both the restricted status and the reason for the restriction.

Currently, this feature supports checking for Managed Markets product restriction. You can use this field to determine if a product can be added to a CalculatedOrder during the order edit mutation process.

The achievements section of the Distribution page in Partners Dashboard will be removed as of today. You will not lose the ability to see the status of your achievements as they are available in other places on the page.

You can see your Built for Shopify status in the same card above where the Achievement section was located.

You can see your highlight achievement status in the Technical criteria checklist section below.

As of 2024-10, the CartTransform create mutation will support metafields as an argument.

The new metafields argument for cartTransformCreate allows for metafields to be set for the CartTransform at creation without the need to call metafieldsSet in a subsequent call.

Learn more about the CartTransform API.

In the 2024-07 API version of checkout UI extensions, we have introduced a new instructions API. This API will inform checkout UI extensions when a particular extension API is/is not available for the current checkout. For example, if you intend to add a discount code via the applyDiscountCodeChange method, check discounts.canUpdateDiscountCodes to ensure it's supported in this checkout.

All checkout UI extensions updating to 2024-07 will be expected to review the list of APIs that may be restricted, and incorperate fail-safes if a particular API is not available in the current checkout. This will be required for checkout UI extensions to start rendering in draft order invoice checkouts.

For more details, please refer to our 2024-07 update guide for more details and instructions on how to safely update to 2024-07.

As of GraphQL Admin API version 2024-07, you can now set and query a customer's data sale / sharing opt out status. This allows customers to be opted out of data sale / sharing in support of compliance with US state laws like CCPA/CPRA. The Admin API now includes the following updates: * Set dataSaleOptOut: Set the data sale / sharing opt out status of a customer * Query dataSaleOptOut: Query the data sale / sharing opt out status of a customer

To learn more about data sale / sharing opt-outs, refer to the Shopify Help Center and the Customer Privacy API.

As of the 2024-07 release of the GraphQL Admin API, a new error code LEDGER_DOCUMENT_INVALID will be added to the potential errors for the InventorySetScheduledChanges mutation. This error code will be returned when the ledgerDocumentUri provided is not a valid URI.