9/18/2025, 7:38:39 AM
The updated schema now includes a new menusCount query to return the number of menus, with optional filtering and limit.
The cartTransformCreate and fulfillmentConstraintRuleCreate mutations now use a functionHandle argument instead of functionId; the old argument has been removed, so calls must be updated accordingly.
New enum values – such as MISSING_FUNCTION_IDENTIFIER, MULTIPLE_FUNCTION_IDENTIFIERS, and LOCATION_REQUIRED – have been added to several error enums to better indicate function or location issues.
Several other enums have received new values, including INVENTORY_QUANTITIES_LIMIT_EXCEEDED for bulk variant mutations, ON_FULFILLMENT for selling plan triggers, and ORDERS_LINK_REQUESTED for webhook topics.
The schema also introduces bank account payment instrument types (BankAccount, BankAccountHolderType, BankAccountType) to support detailed banking information.
Additional fields are added: DeliveryProfile.version for version tracking, Order.sharedCheckout to flag orders created via shared checkouts, and the handle field on Channel is no longer deprecated.
All query descriptions have been updated for clarity, but otherwise their behavior remains unchanged.
Count of menus.
Returns a Abandonment resource by ID.
Returns a Article resource by ID.
Returns a Blog resource by ID.
Returns a Comment resource by ID.
Returns a CustomerAccountPage resource by ID.
Returns a DiscountNode resource by ID.
Retrieves comprehensive details about a specific Hydrogen storefront by its unique identifier. This query provides access to the complete storefront configuration, deployment status, environment settings, and associated metadata needed for development and management workflows.
For example, when developers need to inspect a storefront's current deployment state, environment variables, or customer account configuration before making updates, this query returns all relevant information in a single request.
Use the hydrogenStorefront query to:
The query supports comprehensive filtering and returns detailed information about storefront deployments, environment configurations, customer account settings, and any associated background jobs. This makes it essential for storefront management dashboards, CLI tools, and automated deployment systems.
Background job tracking allows monitoring of asynchronous operations like deployments or configuration updates, providing real-time status updates through the job system. The response includes user error handling for cases where the storefront doesn't exist or access is restricted.
Environment variable access enables developers to verify configuration without exposing sensitive values, while deployment information helps track version history and rollback capabilities.
Learn more about managing Hydrogen storefronts.
Retrieves the complete collection of Hydrogen storefronts configured for a merchant's shop, providing comprehensive access to custom storefront implementations and their associated metadata. This query serves as the primary entry point for managing multiple Hydrogen deployments within a single Shopify store.
For example, a merchant running separate storefronts for different markets (US, EU, Canada) or different brands under one Shopify account can query all their Hydrogen implementations to monitor deployment status, manage environment variables, or coordinate updates across multiple storefronts.
Use the HydrogenStorefronts query to:
This query supports comprehensive storefront portfolio management, enabling developers to build CLI tools and dashboards that provide unified visibility into complex multi-storefront architectures. The response includes detailed configuration data, deployment information, and operational status for each storefront instance.
The query is particularly valuable for agencies or enterprise merchants managing sophisticated headless commerce implementations where multiple Hydrogen storefronts serve different customer segments, geographic regions, or brand portfolios within a single Shopify backend.
Learn more about managing Hydrogen storefronts.
Returns a Menu resource by ID.
Returns a Page resource by ID.
Returns a UrlRedirect resource by ID.
Creates a cart transform function that lets merchants customize how products are bundled and presented during checkout. This gives merchants powerful control over their merchandising strategy by allowing apps to modify cart line items programmatically, supporting advanced approaches like dynamic bundles or personalized product recommendations.
For example, a bundle app might create a cart transform that automatically groups related products (like a camera, lens, and case) into a single bundle line item when customers add them to their cart, complete with bundle pricing and unified presentation.
Use CartTransformCreate to:
The mutation processes synchronously and returns the created cart transform along with any validation errors. Once created, the cart transform function becomes active for the shop and will process cart modifications according to your defined logic. Cart transforms integrate with Shopify Functions to provide powerful customization capabilities while maintaining checkout performance.
Cart Transform functions can be configured to block checkout on failure or allow graceful degradation, giving you control over how errors are handled in the customer experience.
Learn more about customized bundles.
Deletes multiple automatic discounts in a single operation, providing efficient bulk management for stores with extensive discount catalogs. This mutation processes deletions asynchronously to handle large volumes without blocking other operations.
For example, when cleaning up expired seasonal promotions or removing outdated automatic discounts across product categories, merchants can delete dozens of discounts simultaneously rather than processing each individually.
Use DiscountAutomaticBulkDelete to:
The operation returns a job object for tracking deletion progress and any validation errors encountered during processing.
Learn more about discount management.
Creates automatic free shipping discounts that apply to qualifying orders without requiring discount codes. These promotions automatically activate when customers meet specified criteria, streamlining the checkout experience.
For example, a store might create an automatic free shipping discount for orders over variable pricing to encourage larger purchases, or offer free shipping to specific customer segments during promotional periods.
Use DiscountAutomaticFreeShippingCreate to:
The mutation validates discount configuration and returns the created automatic discount node along with any configuration errors that need resolution.
Learn more about automatic discounts.
Updates existing automatic free shipping discounts, allowing merchants to modify promotion criteria, shipping destinations, and eligibility requirements without recreating the entire discount structure.
For example, extending a holiday free shipping promotion to include additional countries, adjusting the minimum order value threshold, or expanding customer eligibility to include new segments.
Use DiscountAutomaticFreeShippingUpdate to:
Changes take effect immediately for new orders, while the mutation validates all modifications and reports any configuration conflicts through user errors.
Learn more about managing automatic discounts.
Creates a fulfillment constraint rule and its metafield.
Sets up a new Hydrogen storefront to power your headless commerce experience. This mutation kicks off the provisioning process in the background and gives you a job ID to track progress.
For example, when launching a new headless commerce experience, developers use this mutation to provision the storefront environment.
Use hydrogenStorefrontCreate to:
The mutation returns immediately with a job ID that can be used to monitor the creation progress, as storefront provisioning runs asynchronously. User errors provide feedback if the creation request contains invalid parameters or conflicts with existing resources.
Learn more about creating Hydrogen storefronts.
Updates the customer account application URLs for a Hydrogen storefront, configuring the authentication and redirect endpoints used by Shopify's Customer Account API integration. This mutation validates URL formats and security requirements.
For example, when setting up customer login functionality, developers configure the JavaScript origin for client-side authentication, logout redirect URIs for post-signout navigation, and the primary redirect URI for successful authentication flows.
Use hydrogenStorefrontCustomerApplicationUrlsReplace to:
The mutation replaces all existing URLs with the new configuration, ensuring consistent authentication behavior across the storefront. Detailed error reporting helps developers verify the configuration meets Shopify's security standards.
Learn more about Customer Account API integration.
Replaces all environment variables for a specific Hydrogen storefront environment in a single atomic operation. This mutation provides a complete replacement strategy rather than individual variable updates, ensuring consistent environment configuration.
For example, when deploying a new version of your Hydrogen storefront that requires a different set of API keys, database URLs, and feature flags, you can replace the entire environment configuration at once rather than updating variables individually.
Use HydrogenStorefrontEnvironmentVariableBulkReplace to:
This bulk replacement approach helps prevent configuration drift and ensures all related variables are updated together, reducing the risk of partial updates that could break your storefront functionality.
Learn more about Hydrogen deployment.
Creates multiple product variants
for a single product in one operation.
You can run this mutation directly or as part of a bulk operation
for large-scale catalog updates.
Use the productVariantsBulkCreate mutation to efficiently add new product variants—such as different sizes,
colors, or materials—to an existing product. The mutation is helpful if you need to add product variants in bulk,
such as importing from an external system.
The mutation supports:
Note:
By default, stores have a limit of 100 product variants for each product. You can create a development store and
enable the Extended Variants developer preview
to create a maximum of 2,048 product variants in a single operation.
After creating variants, you can make additional changes using one of the following mutations:
productVariantsBulkUpdate:productSet:You can also specifically manage product options through related mutations:
Learn more about the product model
and adding product data.
Updates multiple product variants
for a single product in one operation.
You can run this mutation directly or as part of a bulk operation
for large-scale catalog updates.
Use the productVariantsBulkUpdate mutation to efficiently modify product variants—such as different sizes,
colors, or materials—associated with an existing product. The mutation is helpful if you need to update a
product's variants in bulk, such as importing from an external system.
The mutation supports:
Note:
By default, stores have a limit of 100 product variants for each product. You can create a development store and
enable the Extended Variants developer preview
to update a maximum of 2,048 product variants in a single operation.
After creating variants, you can make additional changes using theproductSet mutation,
which is used to perform multiple operations on products, such as creating or modifying product options and variants.
You can also specifically manage product options through related mutations:
Learn more about the product model
and adding product data.
Represents a bank account payment instrument.
The type of bank account holder.
The type of bank account.
MULTIPLE_FUNCTION_IDENTIFIERSMISSING_FUNCTION_IDENTIFIERhandleMISSING_FUNCTION_IDENTIFIERMULTIPLE_FUNCTION_IDENTIFIERSversionThe version of the delivery profile.
MISSING_FUNCTION_IDENTIFIERMULTIPLE_FUNCTION_IDENTIFIERSMULTIPLE_FUNCTION_IDENTIFIERSMISSING_FUNCTION_IDENTIFIERLOCATION_REQUIREDLOCATION_REQUIREDWEB_PRESENCE_RETAIL_LOCATIONsharedCheckoutWhether the order was created through a checkout shared between multiple shops.
MISSING_FUNCTION_IDENTIFIERMULTIPLE_FUNCTION_IDENTIFIERSVARIANT_METAFIELDS_LIMIT_EXCEEDEDINVENTORY_QUANTITIES_LIMIT_EXCEEDEDINVENTORY_QUANTITIES_LIMIT_EXCEEDEDON_FULFILLMENTMISSING_FUNCTION_IDENTIFIERMULTIPLE_FUNCTION_IDENTIFIERSORDERS_LINK_REQUESTED