Starting in API version 2026-04, discounts support tags allowing you to efficiently label, group, and organize your discounts.

What's new:

• The tags field has been added to all discount types
• Tags can be added, updated, and removed via the Admin API

For more information, visit the Admin API documentation

Discount functions now support prerequisites for product discount candidates, allowing you to define the "Buy X" portion of a Buy X, Get Y (BXGY) discount. In a BXGY discount, customers must purchase a specified quantity of one product (Buy X) to receive a discount on another product (Get Y).

What's New:

• A prerequisites field has been added to product discount candidates.
• Each prerequisite is defined as a cartLinePrerequisite, which includes:
  • id: The identifier for the cart line used as the prerequisite.
  • quantity: The number of items from that cart line required to qualify for the discount.

For more detailed information, please visit the Discount Functions documentation.

App-owned metaobjects, identified by types such as $app:example, including those created using declarative metaobject definitions, can now be utilized by their owning app without requiring any access scopes. This change simplifies the process for developers by eliminating the need to request additional access scopes, thereby reducing potential merchant friction.

If you are considering using declarative metaobjects in your app, you can now proceed without worrying about additional access scope requests. Ensure you are using Admin API version 2026-04 or later to read or write app-owned metaobjects without the need for additional access scopes.

Working with merchant-owned metaobject types still requires specific access scopes, such as read_metaobjects or write_metaobject_definitions, to be granted.

Polaris reference docs now follow the same versioning policy as Shopify's GraphQL APIs: Each stable version is supported for a minimum of 12 months. Older versions continue to work, they just won’t have dedicated docs on Shopify.dev. Shopify CLI already prevents deploys targeting API versions older than 12 months, so we recommend keeping your extensions on a supported version.

Starting with the 2026-04 release, we'll only publish docs for the last four stable versions of these reference docs:

• Admin UI extensions
• Checkout UI extensions
• Customer account UI extensions
• POS UI extensions

We are introducing a new access field to the StandardMetaobjectDefinitionTemplate. This field will display the template's access rules, helping you determine if a specific template is configured for access via the Storefront API. By understanding these access rules, developers can plan their API interactions more effectively, ensuring seamless integration with the Storefront.

The StandardMetaobjectDefinitionTemplate is a component that defines the structure and behavior of metaobjects within Shopify. With the new access field, you can proactively verify access configurations, optimizing your development workflow and enhancing the user experience.

We have introduced an expiresIn field to the DelegateAccessToken type, which is returned by the delegateAccessTokenCreate mutation. This addition allows app developers using delegate tokens to know precisely when their tokens will expire. The expiresIn field provides the number of seconds remaining until the token expires, aligning with the data available through the REST Admin API's delegate endpoint.

This feature is particularly beneficial when the expiresIn input is not specified, causing the delegate token to inherit the parent token's Time to Live (TTL). Previously, developers had no means to ascertain the expiration time of such tokens.

This update is available in GraphQL Admin API version 2026-04 and later.

As of Customer Account API version 2026-04, the DraftOrderLineItem object includes a new components field. This field returns the individual component line items associated with a parent line item.

Additionally, a new optional argument, flattenComponents, has been introduced to the DraftOrder.lineItems connection. For API versions 2026-04 and later, flattenComponents defaults to false, meaning only top-level line items are returned as nodes, with their components accessible via the DraftOrderLineItem.components field. If set to true, both parent and component line items are returned as top-level nodes, aligning with the behavior of earlier API versions. For versions prior to 2026-04, flattenComponents defaults to true to ensure backward compatibility.

Example

query {
  draftOrder(id: "gid://shopify/DraftOrder/1") {
    lineItems(first: 10) {
      nodes {
        name
        quantity
        components {
          name
          quantity
        }
      }
    }
  }
}

As of API version 2026-04, you can validate billing addresses and purchase order (PO) numbers in Cart and Checkout Validation Functions. We've added billing address and PO Number to the function input graph and introduced new checkout field targets. This allows you to enforce compliance rules such as blocking prohibited billing countries and requiring PO numbers for B2B orders without relying upon client-side UI extensions.

What's changed

• Input graph fields: billingAddress and poNumber are available on all Shopify Function input graphs. They return null outside of Cart and Checkout Validation.
• Supported checkout field targets for error messages in Cart and Checkout Validation:
  • $.cart.billingAddress.{field} (all standard address subfields)
  • $.cart.poNumber

Impact

• No breaking changes. Your existing functions continue to run. You can optionally add validations for these targets.
• Checkout surfaces field-level errors for billing address and PO number when your function returns validations for these targets.

To learn more, see the developer documentation.

Sales channel apps can now create and manage multiple channel connections from a single app. A single app can now establish more than one channel on a shop, with a separate specification and/or external account for each connection.

Why this matters

If you build a sales channel app that needs separate connections for different accounts or to sell in different markets or have different surfaces, you no longer need to split that model across multiple apps. You can keep those connections inside one app and manage them as distinct channels.

What's new

• A single sales channel app can establish multiple channels on the same shop.
• Sales channels can now uses the Channel Config extension plus one specification file per target channel.
• Each channel can point to a different specification and external account.

What partners should do

For new sales channel apps

• All new sales channels should add a Channel Config extension.
• Define one specification file per target channel.
• Use channelCreate with a specificationHandle, accountId, and accountName to create each channel connection.

For existing sales channel apps

• Migrate legacy sales channel app to use channel connections using this guide
• Review any downstream code that assumes one channel per app. If your app reads or mutates channel-specific state, pass a channel ID instead of relying on app-level defaults.

New APIs in this release

• channel

• channelCreate

• channelByHandle

• channelUpdate

• channelDelete

• channelFullSync

APIs impacted by this release

Deprecated: These single-channel APIs are now deprecated. They still function today but will be removed in a future API version:

| Deprecated API | Use instead | |

As of API version 2026-07, the payment method identifier field is now required when using the customerPaymentMethodRemoteCreate mutation with Stripe, Authorize.net, or Braintree inputs.

The affected fields are:

• paymentMethodId on RemoteStripePaymentMethodInput
• customerPaymentProfileId on RemoteAuthorizeNetCustomerPaymentProfileInput
• paymentMethodToken on RemoteBraintreePaymentMethodInput

These fields were previously optional at the schema level but are required for the payment method to be functional. Without a payment method identifier, remotely created payment methods cannot be used for payment processing. This change aligns the API schema with existing runtime requirements.

If you are already passing a payment method identifier when calling this mutation, no changes are needed. If you are not, update your integration to include the appropriate identifier for your gateway before adopting API version 2026-07.

As of API Version 2026-04 third-party logistics providers (3PLs) and fulfillment apps can now report progress on fulfillment orders with the fulfillmentOrderReportProgress mutation. This feature enables fulfillment services to indicate that work has commenced and, optionally, add brief status notes so merchants see what’s happening in their fulfilment pipeline.

Key Details:

• Reporting progress for 3PL-managed orders works with fulfillment orders in IN_PROGRESS status
• Reporting progress for merchant-managed orders works with fulfillment orders in OPEN or IN_PROGRESS status (requires write_merchant_managed_fulfillment_orders scope)
• Supports optional reasonNotes field (up to 256 characters) for additional context
• New fulfillment_orders/progress_reported webhook available to track when progress has been reported
• fulfillmentOrder.supportedActions field will now return the REPORT_PROGRESS action when a fulfillment order can have progress reported.

New Webhooks

Topic: fulfillment_orders/progress_reported

This webhook is triggered when progress is reported on a fulfillment order. The payload includes the fulfillment order ID and status, the initial_status before the update, and progress_report details including reason_notes and attribution data for the app or user that reported the progress.

Topic: fulfillment_orders/manually_reported_progress_stopped

This webhook fires when a merchant-managed fulfillment order that has had progress manually reported (via fulfillmentOrderReportProgress) is subsequently marked as "ready for fulfillment", transitioning it from IN_PROGRESS back to OPEN status. This webhook allows apps to know when a merchant has "undone" or "cancelled" the in-progress status they previously reported.

In the API 2026-04 release candidate version, the paymentMethodId field is no longer required when creating a subscription contract using the subscriptionContractAtomicCreate and subscriptionContractCreate mutations. This allows you to migrate subscription contracts even if they have missing or expired payment methods.

For implementation instructions, see our docs on how to build a subscription contract.

In the API 2026-04 release candidate version, you can now include a new field called paymentProcessingPolicy when creating a billing attempt using the subscriptionBillingAttemptCreate mutation. A billing attempt is an action to charge a customer based on their subscription.

The paymentProcessingPolicy field determines how the billing attempt is handled depending on the validity of the payment method:

• If you don't provide the paymentProcessingPolicy field, or if you set it to FAIL_UNLESS_VALID_PAYMENT_METHOD, a valid payment method is necessary to create an order successfully.
• Alternatively, if you set the value to SKIP_PAYMENT_AND_CREATE_UNPAID_ORDER, the system will create an unpaid order even if there isn't a valid payment method available on the subscription contract.

For detailed implementation instructions, please refer to our documentation on building a subscription contract.

The Payments Apps API now provides more granular decline reason codes for rejected payment sessions. Multiple new rejection codes have been added to the PaymentSessionStateRejectedReason enum alongside a new source field, giving payments apps more standardized, actionable ways to communicate to merchants why a payment was declined.

New rejection reason codes

The following error codes expand the existing set of rejection reasons with more specific rejection information:

| Error Code | Description | |

We have revamped the way partner organizations manage users and stores.

• Role-based Access Control: Assign roles to users instead of configuring permissions individually. We offer seven system roles that cover organization-wide administration, store access, app development, and merchant-granted collaborator permissions. You can also create custom roles for any needs not covered by the system roles.
• New Organization Structure: Partner organizations now have one Organization Owner and multiple Organization Admins. Previous owners, except the primary owner, have been migrated to Organization Admins, retaining the same access without transferring ownership.
• Unified Store Management in Dev Dashboard: All your dev stores, client transfer stores, and collaborator stores are now consolidated in one place. No more switching between dashboards.
• Seamless Migration: Your organization will be automatically migrated, preserving your team's access and converting it to corresponding roles. No action is required.
• Partner Dashboard: Payouts, app distribution, theme submissions, and referrals remain unchanged in the Partner Dashboard.

Learn more → View help docs →

As of March 23, 2026, customer data erasure requests will no longer be held in a pending state for 180 days from the date of the customer's most recent order.

Erasure requests will now be processed 10 days after the request was submitted, regardless of when the customer's most recent order was placed. For recipients of gift cards that have been scheduled to send, the erasure request will remain in a pending state until the gift card has been delivered.

This update simplifies the overall experience for managing customer data requests.

We are deprecating the --force flag on the shopify app deploy and shopify app release commands. The flag will be removed in a Shopify CLI release in May 2026.

Why we're making this change

The --force flag skips all confirmation prompts, including for extension deletions that can permanently remove data on installed shops. It doesn't distinguish between low-risk operations (adding or updating extensions) and high-risk ones (deleting them). The previously released --allow-updates and --allow-deletes flags give you granular control, so your CI/CD pipelines can run unattended without the risk of accidental, irreversible deletions.

What you should do

If you are automating your app releases in a CI/CD environment, you should adjust your scripts to use the --allow-updates flag instead, which will ensure that extensions can be added and updated, but not deleted.

For example:

shopify app deploy --config production --allow-updates

When extension deletion is needed, you can utilize an interactive deploy or enable the --allow-deletes flag. Use caution and enable --allow-deletes only for manual workflow runs when you are certain that you want to delete an extension and all its configuration on installed shops.

For more information, see documentation on CI/CD deployment for apps.

We're adding barcode support to inventory shipments in version 2026-04, enabling merchants to assign barcodes to shipments for faster receiving workflows.

The following API changes are included:

New field on InventoryShipment

• barcode: String - A nullable field representing the unique barcode assigned to a shipment.

Updated inventoryShipmentCreate mutation

• The InventoryShipmentCreateInput now accepts an optional barcode: String field to assign a barcode when creating a shipment.

New inventoryShipmentSetBarcode mutation

• Sets or clears the barcode on an existing shipment. Pass an empty string to clear the barcode.

Example usage:

mutation {
  inventoryShipmentSetBarcode(
    inventoryShipmentId: "gid://shopify/InventoryShipment/123"
    barcode: "SHIP-2026-0001"
  ) {
    inventoryShipment {
      id
      barcode
    }
    userErrors {
      code
      field
      message
    }
  }
}

What you need to know

• Barcodes must be unique per shop. Two shipments in the same shop cannot share the same barcode.
• Barcodes have a maximum length of 255 characters.
• Leading/trailing whitespace is automatically stripped. Barcodes consisting only of whitespace are treated as empty.

Error codes

• DUPLICATE_BARCODE: Another shipment in the same shop already has this barcode.
• SHIPMENT_NOT_FOUND: The specified shipment does not exist.
• BARCODE_TOO_LONG: The barcode exceeds the maximum length of 255 characters.

Why we made this change Merchants transferring inventory between locations, for example, from a warehouse to a retail store, currently have to scan and receive each item in a shipment one by one. This is slow and error-prone for large shipments. Shipment barcodes let warehouse systems and 3PLs attach a scannable identifier (such as a GS1-128 code) to a shipment so that the entire shipment can be identified and received in a single scan.

The pre_tax_price and pre_tax_price_set fields on order line items in the REST Admin API are being removed. These fields were previously available to stores with the Avalara AvaTax 1.0 integration enabled, which was deprecated in April 2025.

What you should do

Use the GraphQL Admin API to access order line item pricing data.

We are ending the developer preview for checkout and customer account UI extensions. With this update:

• All new development shops on the Shopify Plus plan have access to checkout UI extensions
• All new development shops on all plans have access to customer account UI extensions
• All existing development shops will not be affected by this change

Starting in version 2026-07, the inventoryTransferDelete mutation will return a new error code: INVALID_STATE. This error will be returned when a client attempts to delete an inventory transfer while a product import related to that transfer is in progress.

• New error code added: INVALID_STATE
• API affected: inventoryTransferDelete mutation
• Error enum updated: InventoryTransferDeleteUserErrorCode

For older API versions, the mutation will not include the INVALID_STATE code in the error payload. However, the message field will still provide context about the blocking product import.

For more details, see the updated InventoryTransferDeleteUserErrorCode enum and the inventoryTransferDelete mutation documentation.

We've rebuilt cash management on Shopify POS from the ground up. The new Admin GraphQL APIs and POS UI extension targets open up cash management data and controls to app developers, enabling custom cash management workflows that were previously impossible to build on Shopify POS.

What's new

Cash Drawers

CashDrawer is a new resource that decouples cash management from individual POS devices. A cash drawer represents a physical cash storage unit at a location. Multiple devices can connect to a single drawer, enabling flexible store setups.

| Resource | Description | |

POS UI extensions can now continue running even when a merchant’s device loses network access.

This feature ensures uninterrupted service during connectivity issues. It is especially beneficial for merchants in environments with unreliable internet, such as pop-up shops, outdoor markets, or large retail spaces.

How to Enable

To enable this feature, set runs_offline = true in the [extensions.supported_features] section of your extension configuration:

[extensions.supported_features]
runs_offline = true

Once enabled, your extension will continue to function even if the merchant’s device loses network access. For comprehensive details on configuring offline behavior and best practices, refer to our developer documentation.

Requirements

• POS version 11.0 or later
• Shopify CLI v3.92 or later

As of GraphQL API version 2026-04, all Shopify Functions can access app-owned metaobject entries.

Metaobjects are now available for every function target. This feature enables you to query additional structured data present in metaobjects, such as tiered pricing and bundles. To query a metaobject entry, specify a handle or ID in your input query file. Note that only app-owned metaobject types, identified by the $app reserved prefix, are accessible to functions.

For details look under the Shop field for any of the 2026-04 Functions, like the metaobject input object in Cart Transform. Learn more about metaobject ownership.

Starting in April 2026, the fieldDefinitions input argument for the metaobjectDefinitionCreate mutation will become optional. This change means that developers will no longer be required to specify fieldDefinitions when creating a new metaobject definition. Existing implementations that rely on fieldDefinitions will continue to function as before, but developers can now choose to omit this argument if it is not needed for their specific use case.

We're updating how public apps handle offline access tokens to enhance merchant data protection. Starting April 1, 2026, all new public apps must request and use expiring offline access tokens.

What apps are affected

• Public apps created on or after April 1, 2026 that call the Admin API

What apps are not affected

• Public apps created before April 1, 2026
• Custom apps created at any time
• Apps created by merchants either in the Dev Dashboard or in the admin

Why we’re making this change

Expiring tokens enhance security. If a token is ever leaked, its limited lifespan significantly narrows the risk to both your app and the merchants who trust it. This change aligns with modern OAuth practices, and as a developer it lets you build your app around predictable refresh flows.

Action required

New public apps: Implement expiring offline access tokens. If you use Shopify’s app templates and libraries this is already handled for you.

Need help? Engage with the dev platform community for support and questions.

We're excited to announce that admin intents now support Settings. This new feature allows apps to direct merchants straight to specific Settings pages within the Shopify admin.

What's new?

Previously, directing merchants to a specific Settings page required deep links or manual navigation instructions. Now, with Settings support for admin intents, your app can open a Settings route with a single API call. This keeps merchants focused and eliminates unnecessary navigation steps.

Supported intents

The following Settings intents are now available:

General

• edit:settings/StoreDetails
• edit:settings/StoreDefaults
• edit:settings/OrderIdFormat
• edit:settings/OrderProcessing

Locations

• create:shopify/Location
• edit:shopify/Location
• edit:settings/LocationDefault

How it works

When your app invokes a Settings intent, the Shopify admin opens the relevant Settings page within a page stack, which organizes pages in a layered manner. The Shopify admin automatically scrolls to the targeted card, ensuring merchants land precisely where they need to be.

Sidekick uses Settings intents to streamline configuration tasks, providing merchants with a link that opens the correct Settings page upon clicking.

Learn more

To get started, refer to the admin intents documentation and the Intents API reference.

Holler at us

Leave us feedback, comments, and questions in the Shopify Developer Community. We'd love to hear from you.

The createdAt and updatedAt fields will become available on MetaobjectDefinition objects in API version 2026-04

We've updated requirement 4.4.4 and added a new requirement 4.4.5 for Shopify App Store apps.

Requirement 4.4.4 now provides clearer standards for image quality: images should primarily show your app's actual user interface and features. Screenshots must not include desktop backgrounds or browser windows. Feature images and screenshots that solely contain your app logo are not permitted.

New requirement 4.4.5 introduces a dedicated standard for image uniqueness: each image in your app listing must be unique. Screenshots should showcase different features, views, or states of your app. Don't submit duplicate or near-identical images.

If your app listing already uses distinct screenshots showing different parts of your app, no action is required. These requirements will be enforced starting March 26, 2026.

The productUpdate mutation now accepts an identifier argument, allowing you to look up the product to update by id, handle, or customId instead of passing the product ID inside the input.

The id and handle identifiers let you specify a product's global ID or handle directly. The customId identifier lets you reference a product by a unique metafield value using a namespace, key, and value combination, enabling workflows where external systems identify products by their own IDs.

The inventorySetScheduledChanges mutation will be removed from the GraphQL Admin API in version 2026-07. This mutation has no replacement, so any apps currently using it should stop relying on it to avoid disruptions.

This change is part of our ongoing efforts to streamline and modernize the inventory management APIs, focusing on more robust and consistent methods for handling inventory updates.

What you need to do

Review your app's code for any uses of inventorySetScheduledChanges and remove them. If your app depends on scheduled inventory changes, consider alternative approaches such as using the inventoryAdjustQuantities mutation for immediate adjustments or integrating with other inventory tools. Refer to the API reference for available options.

New Features

The following new features are available for Shopify Minis as of February 2026:

Product Tagging for User-Generated Content

The useCreateImageContent hook now supports tagging products directly to user-generated content. Three new parameters provide partners with enhanced control over content creation:

• productIds: Associate one or more products with a piece of content.
• externalId: Link content to an identifier in your own system.
• description: Add a text description to content.

import {useCreateImageContent} from '@shopify/shop-minis-react';
const {createImageContent} = useCreateImageContent();
await createImageContent({
  imageUri: 'https://example.com/photo.jpg',
  productIds: [
    'gid://shopify/Product/123',
    'gid://shopify/Product/456',
  ],
  externalId: 'my-content-abc',
  description: 'Styled with our summer collection',
});

This feature enables shoppable UGC experiences, allowing users browsing content to discover and purchase tagged products directly.

SafeArea Component and useSafeArea Hook

A new SafeArea (documentation) component and useSafeArea (documentation) hook help minis handle device safe area insets. This is especially important for minis that render full-screen or use custom layouts on notched devices.

import {SafeArea, useSafeArea} from '@shopify/shop-minis-react';

// Option 1: Wrap content in the SafeArea component
function MyMini() {
  return (
    <SafeArea>
      <MyContent />
    </SafeArea>
  );
}

// Option 2: Use the hook for manual control
function MyComponent() {
  const {top, bottom, left, right} = useSafeArea();
  return <View style={{paddingTop: top, paddingBottom: bottom}} />;
}

CLI Enable and Disable Commands

The Shop Minis CLI now includes enable and disable commands for toggling minis directly from the command line. This is useful for testing development minis or managing mini availability during the review process.

npx minis enable
npx minis disable

Additional documentation here

Consent Flow & Scopes

• Terms consent toast: Users see a confirmation toast when accepting terms, improving clarity.
• Development mode consent: The consent dialog now appears in dev mode when a mini requests scopes, facilitating easier testing of the consent flow during development.
• Favorite and unfavorite bypass: Tapping favorite or unfavorite on a mini no longer triggers the consent popup, reducing unnecessary friction.
• Removed Consent Scopes: Unused read scopes have been removed from the platform. Minis that only use ProductCard or ProductLink no longer require the product_list:write scope, reducing the consent burden for simpler minis.
• OpenId scope removed: The openid scope is no longer required for custom backend support. It is only needed if your Mini uses the public user ID (publicId) for personalization or data persistence.

Home Page Quick Link

Minis are now accessible through a quick link on the Shop App home screen, making it easier for users to discover and browse the Explore section. This enhancement gives minis greater visibility across the app.

Documentation Updates

The following documentation updates accompany these changes:

Manifest File

Updated documentation reflects the removal of legacy read scopes from the manifest file. Partners using removed scopes should update their manifest.json accordingly.

Custom Backend

The custom backend guide has been revised with clearer instructions and updated markdown formatting.

Other Changes

• Removed the unused variants field, continuing cleanup from January.
• The CLI template no longer includes unnecessary scopes in the default manifest.json.
• Development minis can now be queried by UUID before they are enabled, supporting consent checks during development.

Summary

February focuses on richer content, better developer experience, and reducing friction:

1. Product tagging for UGC: Tag products directly to user-generated content for shoppable experiences.
2. SafeArea support: New component and hook for handling device safe areas in full-screen minis.
3. CLI enable/disable: Toggle minis directly from the command line.
4. Consent improvements: Smoother consent flow with dev mode support and fewer unnecessary popups.
5. Scope simplification: Removed legacy read scopes and reduced consent requirements for simpler minis.
6. Explore quick link: Greater visibility for minis on the Shop App home screen.

For questions or feedback, reach out to the Shop Minis team or post in the community forums.

In GraphQL Admin API version 2026-04, several Returns fields in analytics, which can be queried through ShopifyQL, have been deprecated and replaced with renamed versions (e.g., sales_reversals, reversed_quantity) to better reflect that they capture all order adjustments, including refunds, returns, order edits, and cancellations. The definitions remain unchanged.

Deprecation timeline

Deprecated fields will be removed in version 2026-07, but will still be accessible via older API versions until 2027-04.

Why we did this

The new field names clarify the difference between broad order adjustments (sales reversals) and physical returns. With the launch of return reason reporting, you can now see physical quantities returned and their reasons at the line item level, separate from overall order adjustments. Access these details in the returns schema using returned_quantity, return_line_item_reason, and is_unverified_return_line_item.

What you need to do

Update your ShopifyQL queries to use the new sales_reversals and reversed_quantity fields (see mapping table below)

| Deprecated field | New replacement field | | :

The analyticsQueryable capability is now available on the MetafieldDefinition type in the GraphQL Admin API, enabling you to specify whether a metafield can be queried in Shopify Analytics. This enhancement allows merchants to leverage custom metafield values for filtering and grouping data, providing deeper insights into their store's performance.

You can access this capability via the MetafieldDefinition.capabilities field. It can be set during the creation or update of a metafield definition using the metafieldDefinitionCreate and metafieldDefinitionUpdate mutations.

Once enabled, the metafield becomes a dimension and filter in ShopifyQL and Shopify's Analytics, empowering merchants to refine their data analysis. Currently, this functionality supports the following MetafieldDefinition.ownerType values:

• PRODUCT
• PRODUCTVARIANT
• ORDER
• CUSTOMER

Example: Enabling Analytics Queryable on a New Metafield Definition

The following GraphQL mutation demonstrates how to enable the analyticsQueryable capability for a new metafield definition. This example sets up a metafield for products, allowing it to be used in analytics queries:

mutation {
  metafieldDefinitionCreate(definition: {
    name: "Fabric"
    namespace: "custom"
    key: "fabric"
    type: "single_line_text_field"
    ownerType: PRODUCT
    capabilities: {
      analyticsQueryable: { enabled: true }
    }
  }) {
    createdDefinition {
      id
      capabilities {
        analyticsQueryable {
          enabled
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

This mutation creates a new metafield definition with the analyticsQueryable capability enabled, making it available for use in Shopify Analytics.

The Metafield type now includes a translations field, enabling you to query localized metafield values directly via the GraphQL Admin API. This enhancement allows you to access translations for metafields associated with any resource, including products, collections, customers, orders, locations, and more.

Querying translations

To query translations for a resource's metafields, including their localized values, see the Get translations for a product metafield example.

Registering a translation

To register a translation, use the translationsRegister mutation with the metafield's resource ID and a content digest. The compareDigest ensures that translations remain synchronized with the original value. You can obtain this digest when creating or querying a metafield.

See the Register a French translation for a metafield value example for the full workflow.

Translation is supported for text-based metafield types, including single_line_text_field, multi_line_text_field, rich_text_field, and html. Ensure that the target locale is enabled and published on your store.

For further information, refer to the Metafield and translationsRegister documentation.

We've updated requirement 1.1.15 for Shopify App Store apps.

Apps must now process refunds only through the original payment processor. Previously, apps were prohibited from offering methods for processing refunds outside of the original payment processor. With this update, if your app issues store credits during a refund, it must use either the 'refundCreate' or 'returnProcess' mutation. This change ensures that refunds and store credits are handled securely and consistently within Shopify’s platform.

For more details on the updated requirement, please refer to the Shopify App Store requirements documentation.

This requirement update will be enforced immediately for new app submissions and will take effect on April 22, 2026, for published apps.

Effective Friday, February 27, 2026, Action Required

We have updated our Partner Program Agreement and API License and Terms of Use. These changes clarify roles, enhance data protection, and support new platform features.

By continuing to use Shopify services on or after February 27, 2026, you confirm that you have read, understood, and accepted these new terms.

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

Action required

We're enhancing Shopify's asset caching to improve load times. As part of this update, we are modifying the URL query parameters recognized for cache busting.

Effective March 24, 2026, bare query strings (a ? followed by a value with no key) will not refresh cached assets. Previously, these strings appeared to refresh assets because altering the URL could bypass the cache; this incidental behavior will be discontinued.

If your asset URLs are generated with Liquid filters (such as asset_url), you’re already compatible—no changes are necessary.

What’s changing

Referencing assets (e.g., images, fonts) with a URL containing a bare query string will no longer refresh the cached asset when the value is updated.

For example:

image.png?123

The same applies within CSS:

background-image: url('image.png?123');

What to do

Use the appropriate Liquid filter to generate URLs (e.g., asset_url, file_url). Shopify handles versioning and updates the URL automatically whenever the asset changes.

In templates:

{{ 'image.png' | asset_url }}

This outputs a URL with a version parameter:

image.png?v=1384022871

In CSS, use a .css.liquid file to incorporate Liquid:

background-image: url('{{ "image.png" | asset_url }}');

Why this matters

Continuing to use bare query strings may result in stale assets being served until the cache expires. Using Liquid filters ensures that the correct, current version of each asset is delivered, enhancing performance by enabling more effective CDN and browser caching.

Learn more

• asset_url filter
• file_url filter
• CSS syntax to ensure automatic updates

As of GraphQL API version 2026-04, Shopify Functions can now access detailed discount information at three levels:

1. Cart-level: All discount applications on the cart.
2. Line item-level: Discounts allocated to specific line items.
3. Delivery-level: Discounts allocated to delivery groups.

Based on the function execution order, only functions that execute after discounts can see complete discount information.

Learn more about function inputs.

You can now pass locale and region_country parameters to the Customer Account API authorization endpoint to build
market-aware login experiences in headless storefronts.

Liquid storefronts handle this automatically with {{ routes.account_login_url }}, but headless storefronts previously had no documented way to construct login URLs that respect market context. We've added documentation and support for two optional
authorization parameters:

• locale: Controls the language of the login screen. Supports regional variants like fr-CA and en-GB, which load market-specific translations set through Translate & Adapt.
• region_country: Controls the market context for policies, branding, and other non-translation content. Uses an ISO 3166-1 Alpha-2 country code.

These parameters can be used independently or together for a fully localized login experience.

Learn more about building market-aware auth URLs for headless stores. For the full list of authorization parameters, refer to the Customer Account API authorization reference.

As of April 2026, you now have access to the SubscriptionBillingAttemptState field in the GraphQL Admin API. This new field replaces several loosely-typed nullable fields with a discriminated union pattern, enhancing the API's ergonomics and self-documentation.

| Deprecated Field | New Equivalent | Notes | |

The verificationSessionReject mutation in the Payments Apps API now supports two new rejection reason codes and an optional merchant-facing message. The new enum values on VerificationSessionStateReason include:

• RESOURCE_NOT_FOUND: The payment method could not be found in the payment provider's system.
• RESOURCE_INVALID: The payment token is not valid for this use case (for example, a mismatch between customer and payment method).

A new input field on VerificationSessionRejectionReasonInput(https://shopify.dev/docs/api/payments-apps/2026-04/input-objects/VerificationSessionRejectionReasonInput) has also been added:

• merchantMessage (string, optional): A custom, localized message to provide to the merchant when a verification is rejected.

These changes give payment apps more granular control over verification rejection reporting.

As part of the enhanced UI for creating shipping options, a shipping option can now include multiple tiered rates grouped together.

If your app integrates with delivery profiles and uses DeliveryMethodDefinition and DeliveryMethodDefinitionInput to manage shipping options, then evaluate if you need to transition to the new APIs in the unstable version:

• If your app reads merchant-managed DeliveryProfile, you might need to migrate to the new read API. Refer to the [Read API](#Read API) and backwards compatibility sections.
• If your app writes merchant-managed DeliveryProfile, then you must migrate to the new write API to avoid unexpected behaviour. Refer to the [Write API](#Write API) section.
• If your app reads and/or writes app-managed DeliveryProfile, then no action is needed.

Glossary:

• Merchant-managed DeliveryProfile: Shipping profiles that merchants create and edit in the Shopify admin.
• App-managed DeliveryProfile: Shipping profiles that the app creates and edits.

This guide outlines the new GraphQL fields and input types for managing shipping options within shipping profiles.

What's changed?

Read API

We're introducing the DeliveryMethodDefinition.rateGroups and DeliveryRateDefinition.conditions fields. These replace the legacy DeliveryMethodDefinition.rateProvider and DeliveryMethodDefinition.methodConditions fields.

To prevent unexpected behavior, migrate to these new fields. Refer to the example query to learn how to use these fields to fetch a DeliveryMethodDefinition.

The legacy fields are scheduled for deprecation. For details on their current behavior, see backward compatibility for queries.

Write API

The following new input fields have been added to DeliveryMethodDefinitionInput: * rateGroupsToCreate

• rateGroupsToUpdate
• freeConditions
• currencyCode

The following legacy fields will become obsolete when merchants start using multiple tiered rates:

• DeliveryMethodDefinitionInput.participant
• DeliveryMethodDefinitionInput.rateDefinition
• DeliveryMethodDefinitionInput.priceConditionsToCreate
• DeliveryMethodDefinitionInput.weightConditionsToCreate .

To learn how to update a DeliveryMethodDefinition using the new fields, see the example mutation

Examples

How to query shipping options

query DeliveryProfile {
  deliveryProfile(id: "gid://shopify/DeliveryProfile/123") {
    profileLocationGroups {
      locationGroup {
        id
      }
      locationGroupZones(first: 10) {
        edges {
          node {
            methodDefinitions(first: 10) {
              edges {
                node {
                  id
                  name
                  description
                  active
                  currencyCode
                  rateGroups(first: 10) {
                    edges {
                      node {
                        id
                        rateProviders(first: 10) {
                          edges {
                            node {
                              ... on DeliveryRateDefinition {
                                id
                                price {
                                  amount
                                  currencyCode
                                }
                                minTransitTime
                                maxTransitTime
                                conditions {
                                  subject
                                  min {
                                    ... on MoneyV2 {
                                      amount
                                      currencyCode
                                    }
                                    ... on Weight {
                                      value
                                      unit
                                    }
                                  }
                                  max {
                                    ... on MoneyV2 {
                                      amount
                                      currencyCode
                                    }
                                    ... on Weight {
                                      value
                                      unit
                                    }
                                  }
                                }
                              }
                              ... on DeliveryParticipant {
                                id
                                carrierService {
                                  id
                                  name
                                }
                                fixedFee {
                                  amount
                                  currencyCode
                                }
                                percentageOfRateFee
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                  freeConditions {
                    subject
                    min {
                      ... on MoneyV2 {
                        amount
                        currencyCode
                      }
                      ... on Weight {
                        value
                        unit
                      }
                    }
                    max {
                      ... on MoneyV2 {
                        amount
                        currencyCode
                      }
                      ... on Weight {
                        value
                        unit
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

How to create and update shipping options

For the deliveryProfileCreate and deliveryProfileUpdate mutations, the following new input fields are added to DeliveryMethodDefinitionInput:

• rateGroupsToCreate
• rateGroupsToUpdate
• freeConditions
• currencyCode

Here's how to update a shipping option using the new input fields:

mutation ProfileUpdate {
  deliveryProfileUpdate(
    id: "gid://shopify/DeliveryProfile/123"
    profile: {
      profileLocationGroups: [
        {
          id: "gid://shopify/DeliveryProfileLocationGroup/456"
          zonesToUpdate: [
            {
              id: "gid://shopify/DeliveryLocationGroupZone/789"
              methodDefinitionsToUpdate: [
                {
                  id: "gid://shopify/DeliveryMethodDefinition/321"
                  rateGroupsToUpdate: [
                    {
                      id: "gid://shopify/DeliveryRateGroup/555"
                      rateDefinitionsToUpdate: [
                        {
                          id: "gid://shopify/DeliveryRateDefinition/666"
                          price: {
                            amount: 7.50
                            currencyCode: USD
                          }
                          minTransitTime: 172800
                        }
                      ]
                      rateDefinitionsToDelete: [
                        "gid://shopify/DeliveryRateDefinition/777"
                      ]
                      rateDefinitionsToCreate: [
                        {
                          price: {
                            amount: 15.00
                            currencyCode: USD
                          }
                          conditions: [
                            {
                              subject: PACKAGE_WEIGHT
                              min: 20.0
                              unit: "kg"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ) {
    profile {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Backwards compatibility for queries

The DeliveryMethodDefinition.rateProvider and DeliveryMethodDefinition.methodConditions fields will continue to be supported temporarily to facilitate a smooth transition.

When using the legacy API:

• If a method definition includes multiple rate definitions, then each additional rate is represented as a separate method definition with its own rateProvider and methodConditions.
• Free conditions are represented as separate method definitions with a zero-price rate definition as the rateProvider.

For example, a method definition with three rate definitions and a free condition will yield different results in the new and legacy APIs. The activeMethodDefinitionsCount and methodDefinitionCounts will reflect these differences.

New API response

{
  "data": {
    "node": {
      "activeMethodDefinitionsCount": 1,
      "profileLocationGroups": [
        {
          "locationGroupZones": {
            "nodes": [
              {
                "methodDefinitionCounts": {
                  "rateDefinitionsCount": 1,
                  "participantDefinitionsCount": 0
                },
                "methodDefinitions": {
                  "nodes": [
                    {
                      "id": "gid://shopify/DeliveryMethodDefinition/825837944888",
                      "name": "Standard",
                      "rateGroups": {
                        "nodes": [
                          {
                            "rateProviders": {
                              "nodes": [
                                {
                                  "id": "gid://shopify/DeliveryRateDefinition/760813584440",
                                  "price": {
                                    "amount": "10.0",
                                    "currencyCode": "CAD"
                                  },
                                  "conditions": [
                                    {
                                      "subject": "PACKAGE_WEIGHT",
                                      "min": {
                                        "value": 0,
                                        "unit": "KILOGRAMS"
                                      },
                                      "max": {
                                        "value": 10,
                                        "unit": "KILOGRAMS"
                                      }
                                    }
                                  ]
                                },
                                {
                                  "id": "gid://shopify/DeliveryRateDefinition/760813617208",
                                  "price": {
                                    "amount": "20.0",
                                    "currencyCode": "CAD"
                                  },
                                  "conditions": [
                                    {
                                      "subject": "PACKAGE_WEIGHT",
                                      "min": {
                                        "value": 10.0001,
                                        "unit": "KILOGRAMS"
                                      },
                                      "max": {
                                        "value": 20,
                                        "unit": "KILOGRAMS"
                                      }
                                    }
                                  ]
                                },
                                {
                                  "id": "gid://shopify/DeliveryRateDefinition/760813649976",
                                  "price": {
                                    "amount": "30.0",
                                    "currencyCode": "CAD"
                                  },
                                  "conditions": [
                                    {
                                      "subject": "PACKAGE_WEIGHT",
                                      "min": {
                                        "value": 20.0001,
                                        "unit": "KILOGRAMS"
                                      },
                                      "max": null
                                    }
                                  ]
                                }
                              ]
                            }
                          }
                        ]
                      },
                      "freeShippingConditions": [
                        {
                          "min": {
                            "amount": "100.0",
                            "currencyCode": "CAD"
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Legacy API response

With the legacy API, you receive multiple method definitions, one for each rate definition and one for the free condition:

{
  "data": {
    "node": {
      "activeMethodDefinitionsCount": 4,
      "profileLocationGroups": [
        {
          "locationGroupZones": {
            "nodes": [
              {
                "methodDefinitionCounts": {
                  "rateDefinitionsCount": 4,
                  "participantDefinitionsCount": 0
                },
                "methodDefinitions": {
                  "nodes": [
                    {
                      "id": "gid://shopify/DeliveryMethodDefinition/825837944888",
                      "name": "Standard",
                      "rateProvider": {
                        "__typename": "DeliveryRateDefinition",
                        "id": "gid://shopify/DeliveryRateDefinition/760813584440",
                        "price": {
                          "amount": "10.0",
                          "currencyCode": "CAD"
                        }
                      },
                      "methodConditions": [
                        {
                          "id": "gid://shopify/DeliveryCondition/21530181688?operator=greater_than_or_equal_to",
                          "field": "TOTAL_WEIGHT",
                          "conditionCriteria": {
                            "value": 0,
                            "unit": "KILOGRAMS"
                          }
                        },
                        {
                          "id": "gid://shopify/DeliveryCondition/21530181688?operator=less_than_or_equal_to",
                          "field": "TOTAL_WEIGHT",
                          "conditionCriteria": {
                            "value": 10,
                            "unit": "KILOGRAMS"
                          }
                        }
                      ]
                    },
                    {
                      "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateDefinition&source_id=760813617208",
                      "name": "Standard",
                      "rateProvider": {
                        "__typename": "DeliveryRateDefinition",
                        "id": "gid://shopify/DeliveryRateDefinition/760813617208",
                        "price": {
                          "amount": "20.0",
                          "currencyCode": "CAD"
                        }
                      },
                      "methodConditions": [
                        {
                          "id": "gid://shopify/DeliveryCondition/21530214456?operator=greater_than_or_equal_to",
                          "field": "TOTAL_WEIGHT",
                          "conditionCriteria": {
                            "value": 10.0001,
                            "unit": "KILOGRAMS"
                          }
                        },
                        {
                          "id": "gid://shopify/DeliveryCondition/21530214456?operator=less_than_or_equal_to",
                          "field": "TOTAL_WEIGHT",
                          "conditionCriteria": {
                            "value": 20,
                            "unit": "KILOGRAMS"
                          }
                        }
                      ]
                    },
                    {
                      "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateDefinition&source_id=760813649976",
                      "name": "Standard",
                      "rateProvider": {
                        "__typename": "DeliveryRateDefinition",
                        "id": "gid://shopify/DeliveryRateDefinition/760813649976",
                        "price": {
                          "amount": "30.0",
                          "currencyCode": "CAD"
                        }
                      },
                      "methodConditions": [
                        {
                          "id": "gid://shopify/DeliveryCondition/21530247224?operator=greater_than_or_equal_to",
                          "field": "TOTAL_WEIGHT",
                          "conditionCriteria": {
                            "value": 20.0001,
                            "unit": "KILOGRAMS"
                          }
                        }
                      ]
                    },
                    {
                      "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateRangeCondition&source_id=21530279992",
                      "name": "Standard",
                      "rateProvider": {
                        "__typename": "DeliveryRateDefinition",
                        "id": "gid://shopify/DeliveryRateDefinition/0?source=RateRangeCondition&source_id=21530279992",
                        "price": {
                          "amount": "0.0",
                          "currencyCode": "CAD"
                        }
                      },
                      "methodConditions": [
                        {
                          "id": "gid://shopify/DeliveryCondition/21530279992?operator=greater_than_or_equal_to",
                          "field": "TOTAL_PRICE",
                          "conditionCriteria": {
                            "amount": "100.0",
                            "currencyCode": "CAD"
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

Legacy customer accounts are no longer available to new stores and existing stores not using it. Shopify will stop providing feature updates and technical support for this older version.

A final sunset date for legacy customer accounts will be announced later in 2026. We strongly recommend that merchants upgrade their customer accounts ahead of the deadline.

If you build themes

Theme developers should no longer include legacy customer account liquid files. Any store that is on legacy customer accounts, that upgrades to a theme without the legacy files, will automatically be upgraded to the latest version of customer accounts.

Simplify customer account implementation across your themes with our new shopify-account web component that automatically redirects to the latest version of customer accounts.

If you build apps

Developers can use Shopify Extensions to develop apps that customize and extend customer accounts in a way that does not require customizing liquid templates. If your app relies on legacy customer account liquid pages, it won’t work for merchants on the latest version of customer accounts.

With customer account UI extensions, you can enhance native pages like order status, order list, profile, and even build unique full-page experiences. 800+ apps have already made the switch. Build your first customer account extension now and put your app in front of over 70% of Shopify merchants (and growing) already using customer accounts.

If you build custom storefronts

Use the Customer Account API as your source for customer-scoped data and authenticated customer actions in order to create the most secure customer experiences.

If you build custom storefronts or apps that currently use Storefront API customer-scoped mutations, we recommend switching to the Customer Account API as soon as possible.

When using API version 2026-04 or later, JSON type metafield writes will be limited to 128KB. Limits for all other metafield types remain unchanged (current limits). All apps that use JSON fields (prior to April 1st, 2026), will be grandfathered at the current 2MB limit. Large metafield values continue to be readable by all API versions, including future versions.

Large JSON metafield negatively impact storefront performance—particularly when multiple large values are loaded together, which can result in tens of megabytes of data being fetched for a single page. Our goal is to accommodate all current use cases while preventing performance issues stemming from extremely large values.

If you are a new app and believe you have a use case that requires >128KB JSON fields, please fill out this form to request access. Additional limits will be granted on a case by case basis.

Note: Initially, this change limited metafields to 16KB. After feedback from our developer community, we've revised those limits to accommodate more use cases and updated this post.

We are enhancing app monitoring and logs to provide better visibility and debugging capabilities, starting with webhooks.

Monitoring Page Improvements

• Expanded History: Access up to 30 days of webhook data, including successful deliveries, error counts, and p90 response times.
• Topic Filtering: List all topics and filter the page to view charts specific to a single topic.

Logs Page Improvements

• Fine-Grained Time Filters: Search logs using customized start and end dates and times for faster troubleshooting.
• Multi-Select Filters: Filter by multiple Shops, Statuses, or Topics simultaneously.
• Filter counts: See the count of events associated with each Shop, Status, and Topic filter option.

These features are now available in the Dev Dashboard.

As of Shopify CLI 3.91, the Dev Console has been updated to show all active dev previews and their extensions, right in the admin. You can now see information on the developer who created the preview, and when it was last updated. Additionally, the Dev Console allows you to:

• Access preview links for your app and extensions
• Open QR codes for mobile testing
• Clean up dev previews that are no longer in use
• Open your app on the Dev Dashboard

The Dev Console is available for your app when running shopify app dev and opening the admin. For more information, see the app testing documentation.

Shopify CLI 3.90.1 now features commands that let you execute queries, mutations, and bulk operations right from your terminal.

• shopify app execute allows you to run standard Admin API queries and mutations.
• shopify app bulk execute allows you to start bulk queries and bulk mutations, and optionally --watch them synchronously.
• shopify app bulk status and shopify app bulk cancel allow you to monitor and manage bulk operations.

These new commands come on the heels of the release of improved performance and expanded mutation support for bulk operations, which make it possible to handle larger data sets for a wider variety of data types. With this Shopify CLI release, it’s now easy for you to script and automate both bulk operations and standard GraphQL operations with the Admin API, or utilize them with coding agents to query and manipulate your dev stores.

For more information, see the documentation and our community announcement.

The Dev Dashboard now renders in your preferred language, and is available in all the languages supported by the Shopify admin.

For more information, see Choosing your account language and region.

As of API version 2026-04, we've removed the permitsSkuSharing field from the FulfillmentService object and from the fulfillmentServiceCreate and fulfillmentServiceUpdate mutations. SKU sharing will be enabled by default for all fulfillment services.

Why we made this change

By enabling permitsSkuSharing for all fulfillment services, we're standardizing inventory behavior across fulfillment services and simplifying the API. Previously, having permitsSkuSharing set to disabled would restrict inventory to a single location. This didn't always represent how the merchant's inventory item was setup in the real world.

Impact on your app

• GraphQL: In the unstable or 2026-04 and later releases, if you are querying for the permitsSkuSharing field or sending it in mutations in API version, you will begin receiving errors.
• REST: In the unstable or 2026-04 and later releases, the permitsSkuSharing field won't be returned in GET requests. In POST and PUT requests, the permitsSkuSharing argument will be ignored.
• permitsSkuSharing will be enabled for all fulfillment services.
• When permitsSkuSharing was disabled, inventory could only be stocked at a single location. With it enabled for all fulfillment services, inventory can be stocked at multiple locations.

What you need to do

• Remove any reads/writes of permitsSkuSharing from your code for the unstable or 2026-04 and later releases.
• Review any business logic that assumed inventory could only be stocked at a single location for a fulfillment service.

In the API 2026-04 release candidate version, a new field, remainingLineItemsWeight, has been added to the FulfillmentOrder GraphQL type. This field returns the total weight of line items that haven’t been fulfilled yet, which enables you to make decisions based on remaining weight in your fulfillment order.

For implementation details and further information, see the fulfillment orders documentation.

We have introduced 3 new enum values to ColumnDataType in ShopifyqlTableDataColumn:

• RATING : Represents a rating value as float.
• STRING IDENTITY: Represents a GID/UUID value.
• COLOR: Represents a color value in HEX format.

You can now assign an optional name to your webhook subscriptions to simplify identification and management. This feature is available for both TOML-based subscriptions and subscriptions created through the Admin API subscriptions created via the GraphQL Admin API.

Naming your webhooks is particularly beneficial when you have multiple subscriptions targeting the same endpoint or listening to the same topic with different filters. When a webhook is delivered, its name is included in the request headers, allowing you to route and process incoming webhooks without needing to parse the payload body.

For admin API subscriptions, the webhook name must be unique per shop. For declarative subscriptions, the name must be unique per app. Names can be up to 50 characters long and may include alphanumeric characters, underscores, and hyphens.

To set a name for TOML-based subscriptions, update the name field in your shopify.app.toml webhook configuration. From 2026-04, you can name admin API subscriptions, the name field can be set using the WebhookSubscription GraphQL object, as well as through the webhookSubscriptionCreate and webhookSubscriptionUpdate mutations.

The shopify.app.extensions() method in App Bridge now supports Point of Sale (POS) UI extensions, in addition to checkout, customer account, Admin, and Theme extensions.

With this update, your embedded app can query the status of POS UI extensions along with other extension surfaces. This enables you to consistently handle and activate your Point of Sale extensions, simplifying the creation of onboarding flows and setup dashboards that encompass your entire app extension ecosystem, including in-store experiences.

For more information, refer to the developer documentation.

Accelerated checkout now supports adding multiple product variants from the product page. Theme devs can include additional items alongside the main product (for example, a TV and its warranty), allowing customers to purchase products and their add-ons using accelerated checkout

Learn more in our dev docs.

You can now query a merchant's default gift card expiration settings using the GraphQL Admin API.

The new expirationConfiguration field on the GiftCardConfiguration object returns the merchant's configured expiration settings, including the duration value and time unit (days, months, or years). When merchants have automatic gift card expiration enabled, you can use these settings to calculate the expiresOn date for new gift cards.

How it works

• The expirationConfiguration field returns either:
  • a GiftCardExpirationConfiguration object when the merchant has configured a default gift card expiration
  • null when the merchant has gift cards set never to expire
• The GiftCardExpirationConfiguration object includes:
  • an expirationValue field (integer)
  • an expirationUnit field (enum: DAYS, MONTHS, YEARS)

Example query

query {
  giftCardConfiguration {
    expirationConfiguration {
      expirationValue
      expirationUnit
    }
  }
}

New Features

Delayed Consent

We've enhanced consent management by introducing a delayed consent popup for all Shop Minis.

What this means for partners:

• Users will see a consent screen before your mini loads if you request scopes.
• The mini's landing (splash) screen is shown while consent is pending.
• Partners should customize their splash screen to provide a great first impression.

We’ve added new payment error codes for subscription billing attempts in the GraphQL Admin API. These new error codes provide more granularity and consistency, making payment errors easier to diagnose. They’re currently available in the unstable API version, will be released in version 2026-04.

We’re also updating our error-code mapping to be more explicit:

• In the unstable version, you’ll start seeing new error codes display, along with fewer AUTHENTICATION_ERROR and PAYMENT_METHOD_DECLINED errors.
• If you’re on version 2026-01 or earlier, you might still notice a shift in error volumes across existing error codes. We improved our mapping so that some errors previously categorized as generic decline errors, such as PAYMENT_METHOD_DECLINED, are now mapped more explicitly to existing error codes. For example, we can map more cases to INSUFFICIENT_FUNDS instead of generic declines.

Known issue resolved

From January 28, 2026, to February 4, 2026, there was a temporary issue with error mapping, which might have caused a surge in TRANSIENT_ERROR. This has been fixed.

Error code mapping

• If you're on version unstable or 2026-04, you'll see the new error code.

• If you're on 2026-01 or earlier versions, you'll see the currently mapped code.

  | New error code | Currently mapped error code | |

As of GraphQL Admin API version 2026-04, you can filter products based on whether their inventory is tracked using the new tracks_inventory Boolean filter.

This is especially useful when working with merchants like dropshippers who might not maintain on-hand inventory.

Example usage

query RetrieveWithInventoryProducts {
  withInventory: products(first: 10, query: "published_status:published AND tracks_inventory:true") {
    edges {
      node {
        id
        title
        status
        totalInventory
        tracksInventory
      }
    }
  }

You can now include up to 30 app blocks in a single theme app extension, an increase from the previous limit of 25. This gives you more flexibility to build comprehensive app experiences that integrate seamlessly with themes.

Learn more about theme app extensions and file and content size limits on Shopify.dev.

You can now add an article_list input setting to your theme sections and blocks. This new setting type outputs an article picker that lets merchants select multiple published articles, which can be used for creating featured article sections, related content areas, or article galleries.

Learn more about the article_list input setting in the theme documentation.

To simplify and standardize our checkout references, Shopify has removed the following fields from checkout and orders webhooks. Merchants and partners should update their webhook handlers to use the token or checkout_token fields going forward.

Checkout webhooks

The id field has been removed from the following webhook topics:

• checkouts/create
• checkouts/update

What you need to do

If you depend on the id field , update your infrastructure to use the token field instead.

Orders webhooks

The checkout_id field has been removed from the following webhook topics:

• orders/cancelled
• orders/create
• orders/fulfilled
• orders/link_requested
• orders/paid
• orders/partially_fulfilled
• orders/updated

What you need to do

If you depend on the checkout_id field, update your infrastructure to use the checkout_token field instead.

Summary

These changes improves consistency across our APIs and ensure that all integrations reference checkouts using the same identifier. Merchants and partners should update their webhook handlers to use the token or checkout_token fields going forward.

For more details, see the public webhook documentation.

As of API version 2026-04, order metafield definitions can copy values from cart metafields to order metafields when an order is created. You can specify which cart metafields should be carried over to orders.

The metafield value is copied if both these conditions are true:

• An order metafield definition exists with the same namespace and key as a cart metafield.
• The cartToOrderCopyable capability is enabled on that order metafield definition.

View developer documentation.

Cart metafields are now accessible in all APIs that interact with the buyer journey, including the Storefront API, Checkout UI extensions, Functions, and the GraphQL Admin API.

We now recommend using cart metafields instead of cart attributes and checkout metafields for custom data storage. Cart metafields offer enhanced security features, such as edit and view permissions, and app-reserved namespaces, which prevent unauthorized access by other apps.

Learn more about metafield capabilities.

Starting with POS 10.19.0, unhandled errors in extension callbacks trigger an error page instead of failing silently. This change ensures a more stable and predictable experience for merchants and helps developers identify issues proactively.

To prevent disruptions for merchants and minimize unexpected failures, developers should thoroughly test callbacks and ensure all exceptions are properly handled.

For example, this code will now trigger an error page:

// Before: Errors occur but do not display an error page.
// POS 10.19.0 onwards: Displays an error page upon encountering an error.
<Screen
  name="example"
  title="Example"
  onReceiveParams={(params) => mayNotExist(params)}
></Screen>

One solution is to wrap the logic in try/catch blocks:

<Screen
  name="example"
  title="Example"
  onReceiveParams={(params) => {
    try {
      mayNotExist(params);
    } catch (error) {
      // Handle errors.
    }
  }}
></Screen>

Access to events data older than one year is no longer available via the Admin GraphQL Event interface or the Admin REST events resource. This update is part of our ongoing efforts to optimize data management and improve system performance.

Please review and update any dependencies on these events. If you have any questions or need further assistance, feel free to reach out on the Shopify Developer Community forums.

As of Shopify CLI 3.89, you now have more control over the types of extension and configuration updates that should be allowed in your automated app releases. This allows developers to be more confident in the safety of CI/CD pipelines and other app deployment automation.

This is possible via new flags on the shopify app deploy and shopify app release commands:

• --allow-updates: Lets you deploy new app configuration and extensions, and update existing ones.
• --allow-deletes: Lets you delete app configuration and extensions.

The existing --force command is equivalent to using these flags together.

Note: Deleting app configuration and extensions also deletes related data on stores that have your app installed. To avoid accidentally deleting store data, Shopify recommends that you only use the --allow-updates flag in your default CI/CD workflow.

For more information, see documentation on Shopify.dev.

As of January 26, 2026, Checkout UI extensions that support blocking now default to non-blocking behavior. To enable blocking, merchants must explicitly activate the Allow app to block checkout setting in the checkout and accounts editor.

If your Checkout UI extension requires blocking, display a warning in the editor using the useExtensionEditor() hook, and include this step in your activation process. Inform merchants that they must enable Allow app to block checkout for the UI extension to function as intended.

We now recommend building custom checkout validation using Cart and Checkout Validation Functions instead of Checkout UI extensions, as they are more secure, performant, and guaranteed to run across supported checkouts. Learn more about Cart and Checkout Validation Functions.

Simplify customer account implementation with our new shopify-account component. This web component allows customers to sign in and access account navigation menu—all without leaving the storefront.

What's included

• Sign-in methods: passwordless sign-in, social sign-in with Facebook and Google, and automatic sign-in with Shop recognition
• Account navigation menu with customizable quick links
• Styling control via CSS variables
• Automatic feature updates from Shopify without requiring you to update your code

This component eliminates the guesswork around customer account implementation. It's fully integrated with the latest version of customer accounts, offers customizable styling to match your brand, and enables seamless sign-in for your customers.

Visit our dev docs to get started now.

The account component is available now in the latest version of the Horizon themes. If stores you manage are using a Horizon theme, update your theme now to get this component live on your storefront.

Coming soon

The shopify-account component will soon be required for all themes submitted to or updated in the Theme Store. If you're a theme partner, we recommend adding it to your themes now.

Starting with POS version 10.19.0, POS UI extensions can now access the device camera through a new Camera API. This enables new use cases like scanning IDs, capturing product photos, and attaching images directly within Shopify POS.

For options, usage examples, and best practices, see Camera API.

Shopify will stop setting the shopify_y and shopify_s cookies in 2026.

If you use these cookies, your storefront will continue to work normally. However, if you don’t upgrade, visitor and session attribution won't be reliable in in Shopify Analytics.

For Hydrogen storefronts, upgrade by April 30, 2026.

What you need to do:

• If you’re using Hydrogen (React Router) deployed to Oxygen: Run the Hydrogen CLI upgrade command. All Hydrogen versions from 2024.7 through 2025.7 include this fix.

• For other setups: See instructions in the dev docs.

The Shop Minis CLI has been updated to ensure only authorized team members can create and manage Shop Minis. This is done by verifying the necessary permissions within your Partner organization.

What's changing

To develop Shop Minis, you must now have the Manage apps permission enabled on your Partner account. Without this permission, CLI commands will result in an error.

This change affects CLI actions such as:

• Setting up a new Mini
• Submitting, canceling, and checking submissions

What you need to do

For organization owners or admins

1. Log in to your Partner Dashboard.
2. Navigate to Settings → Team.
3. Find the developer who needs access.
4. Edit their profile to adjust permissions.
5. Enable Manage apps under Sensitive permissions.
6. Save the changes.

For developers:

Request that your organization owner or admin grants you the Manage apps permission.

After permissions are updated, you can begin developing and submitting Minis within your Partner organization.

Learn more

• Shop Minis permissions docs

The shopify.app.extensions() method in App Bridge now supports Admin and Theme app extensions, in addition to the previously available checkout and customer account extensions.

With this update, your embedded app can query the status of extensions across all major surfaces. This means you can receive consistent handle and activation data for Admin and Theme app extensions. As a result, you can build more comprehensive onboarding experiences and create setup dashboards that encompass your entire app extension ecosystem.

For further details, see the dev docs.

Starting January 13, 2026, Shopify is enforcing stricter Liquid parsing for all themes. This improves code quality, prevents syntax errors, and enables future Liquid enhancements.

If your theme contains Liquid code that doesn't meet the stricter parsing requirements, we'll automatically rewrite those files to be compatible. Updated files will include a comment explaining what changed. The rewrite process preserves your theme's functionality and appearance while fixing syntax issues that could cause problems in the future.

If you're developing new themes or theme app extensions, all new submissions to the Theme Store and App Store already require strict-parsable Liquid code. This ensures new code meets the higher quality standards from the start.

View the migration guide for detailed information on updating your code.

We're updating the format of versioning query parameters appended to store assets such as CSS and JS. Previously, some assets used a bare numeric query parameter, (for example, ?108), while others used a key-value format with the v query parameter. Moving forward, all asset URLs will consistently use the ?v=VERSION_STRING format for versioning. The new format will be returned by liquid tags and will be present in Shopify-rendered storefront HTML.

For example, an asset URL that previously looked like this: https://shop.example.com/cdn/shop/t/7/compiled_assets/styles.css?108

Will now look like this: https://shop.example.com/cdn/shop/t/7/compiled_assets/styles.css?v=108

These changes are being made to support upcoming infrastructure improvements.

Action Required:

Most themes will not require any changes. Themes utilizing standard Liquid asset filters to generate URLs will automatically output the updated format.

However, you should ensure that any app or custom theme code that uses asset URLs doesn’t require them to be expressed in the old bare numeric format. Regular expressions or logic specifically expecting a query string ending in only numbers should be updated to support the ?v= format.

We're adding new error codes to the OrderTransactionErrorCode enum to provide more granular detail about the transaction failure. You can use this more detailed response to improve customer interactions.

What's new

These error codes enable precise identification of transaction issues:

| Error Code | Description | |

shopify app import-custom-data-definitions is now available in Shopify CLI version 3.89.

This command helps you migrate existing metafield and metaobject definitions for your app to declarative TOML management. All app-owned definitions configured on your dev store are automatically converted to their TOML equivalent. These definitions include those with a namespace like $app or metaobjects with a type like $app:example, You can review the TOML definitions and add them to your shopify.app.toml file. You can continue writing metafield and metaobject values without any changes.

You can migrate all your definitions at once, or you can work step by step by running the command multiple times. Run shopify app dev to test your TOML definitions in your dev store, then run shopify app deploy to deploy your new centrally managed Metafield and Metaobject definitions to all shops with your app installed. After you've deployed your changes, you can delete the unnecessary definition management code.

Declarative definitions offer several advantages over API management:

• Shopify updates declared definitions in every shop where your app is installed, ensuring consistency across installations.
• Definitions stay in sync with your app's state, allowing you to roll out new metafields and related features simultaneously.
• Definitions are version controlled as part of your app, making it easy to roll back.

As always, feel free to reach out in the community forum to share your questions and feedback about using declarative metafield and metaobject definitions.

Support for legacy mode profiles in shipping has been discontinued, as this feature has been inactive for some time. Consequently, the GraphQL Admin API is being updated to align with this change.

The following mutation is now marked as deprecated:

• deliveryShippingOriginAssign

Developers are advised to cease using this mutation, as it will be removed in a future API version. To ensure compatibility with upcoming updates, developers should explore alternative methods for assigning shipping origins within the current API framework.

Admin UI extensions for Discount Functions can now interact with the selected discount method and manage discount classes, letting you customize the discount configuration experience directly within the Shopify admin.

This is a non-breaking change that adds new functionality to existing discount UI extensions.

What's new

We've added a new discounts object to the Discount Function Settings API on the 2026-01 API version, providing these features:

• discountClasses: Access enabled discount classes (product, order, shipping).
• updateDiscountClasses: Enable or disable discount classes programmatically.
• discountMethod: Access the selected discount method (code or automatic).

What this solves

Previously, discount UI extensions had three main limitations:

• Inability to manage discount classes: All Discount Functions defaulted to enabling all three discount classes, causing conflicts even when only one was needed.
• No conditional UI based on method: It wasn't possible to render different options for automatic versus code discounts.
• No conditional UI based on classes: There was no way to show/hide settings based on the enabled discount classes.

What you can build

With these enhancements, you can now:

• Create multi-effect discounts: Develop discounts that offer savings on products, order total, and/or shipping, allowing merchants to toggle each option.
• Method-specific configuration: Display different UI for automatic versus code discounts within the same app and discount type.
• Reduce combination conflicts: Enable only the discount classes that your function requires to prevent unnecessary conflicts.

Learn more

• Build a discount UI with UI extensions (updated)
• Admin UI extensions API reference

Buyers can now replace the payment method on their subscription contract without navigating away from your Customer Account UI extension. Simply invoke the intent and the native payment flow handles the rest, no need to store or display cards yourself.

This new capability is the first of its kind powered by a new Intents API that lets your extension invoke native customer account workflows for managing buyer information.

Dive into the documentation on customer account intents to get started.

Starting in POS 10.19, you can now localize your POS UI extensions for international merchants, staff, and customers. You can

• Translate extension text: Define locale files with translation strings that automatically resolve based on customer and shop locales.
• Format currencies and numbers: Use formatCurrency and formatNumber to display values in locale-appropriate formats.
• Handle pluralization: Support complex plural rules across languages using the standard Intl.PluralRules specification.

Learn how to localize a POS UI extension.

You can now use the new ReturnReasonDefinition type to capture more granular, category-specific return reasons when managing returns. This replaces the previous ReturnReason enum with a richer data model that helps provide merchants with better insights in their return analytics, and more tailored return experiences for their buyers.

What's new

• A new ReturnReasonDefinition type with id, handle, and name fields. Use the stable handle for programmatic logic.
• The returnReasonDefinitions query retrieves the full library of available return reasons.
• A new suggestedReturnReasonDefinitions connection on LineItem provides return reasons tailored to each product's category.
• The returnCreate, returnRequest, and orderRequestReturn mutations now accept returnReasonDefinitionId in their line item inputs.
• Access returnReasonDefinition on ReturnLineItem and UnverifiedReturnLineItem types.

Deprecations

The returnReason field on input types and return line item types is deprecated. Use returnReasonDefinitionId for inputs and returnReasonDefinition for reading return data.

Migration

If your app creates returns, update your mutations to use returnReasonDefinitionId instead of returnReason. Query suggestedReturnReasonDefinitions on LineItem to get contextually relevant reasons for each product. For reading returns, update your queries to use returnReasonDefinition instead of returnReason.

These changes are available in API version 2026-01.

Starting with API version 2026-01 of the GraphQL Admin API, your app can subscribe to the orders/link_requested webhook topic. This webhook is triggered when a customer requests a new order link from an expired Order status page, allowing your app to be notified when customers need access to their order details after the original link has expired.

Webhook Trigger: This occurs when a customer visits an expired order status page and requests a new order link.

Payload: The webhook delivers the complete Order object, which includes:

• Order ID and details
• Customer information
• Order status
• Fulfillment information

For more information and to view the full payload, visit the Shopify developer documentation.

You can now access transaction data directly from the Return object in the Admin GraphQL API. This new transactions connection simplifies your ability to associate payments and refunds with specific returns, removing the need to deduce relationships based on amounts and timestamps. This helps ensure accurate financial reporting and reconciliation for integrations.

The transactions connection is populated for the following scenarios:

• POS returns and exchanges: Includes both refunds and captured payments.
• Online returns and exchanges: Includes refunds only.

Here's an example of how to query transactions on a return:

query {
  return(id: "gid://shopify/Return/123") {
    transactions(first: 5) {
      edges {
        node {
          id
          kind
          status
          amountSet {
            shopMoney {
              amount
              currencyCode
            }
          }
        }
      }
    }
  }
}

For more details, refer to the Return object documentation.

Beginning in API version 2026-01, billing attempts will be throttled based on internal trust metrics to prevent abuse. If an attempt is throttled, it will be visible in the new throttled error code on the BillingAttemptUserErrorCode enum.

The fulfillmentOrderMove mutation now returns a specific fulfillmentOrderMoveUserError type instead of the generic userError type.

What's changing:

The user error response now includes a code field for easier programmatic error handling and identification.

Why we made this change:

This enhancement supports the new manual in-progress fulfillment orders feature, which allows merchants to self-report progress on their fulfillment orders. As part of this feature, moving fulfillment orders with reported progress is now restricted, and the enhanced error responses help developers handle these restrictions more effectively.

Learn more

Learn more about the fulfillmentOrderMove mutation.

What's changing?

Starting on September 15th, 2025, Shopify will no longer set the following cookies on merchant storefronts:

• _landing_page
• _orig_referrer
• _tracking_consent

Required updates

While accessing internal cookie values is never recommended as they frequently change, any code that currently accesses the cookie values will need to be adapted to use documented APIs.

_landing_page and _orig_referrer

We recommend keeping track of these values through browser APIs (window.location.href to save the landing page, and document.referrer for the referrer). To keep track of these values through the user’s session, you may use the Web Pixels API. In the GraphQL Admin API, you can access this information by querying an order:

query referrerData {
  order(id: "gid://shopify/Order/14134963208214") {
    customerJourneySummary {
      lastVisit {
        landingPage
        referrerUrl
      }
    }
  }
}

_tracking_consent

Please use the Customer Privacy API.

The Discount Function API now supports discount code rejection, allowing apps to conditionally reject discount codes with a custom message.

With discount rejection for the Discount Function API, merchants can:

• Prevent double discounting on sale prices
• Manage fine-grained combinations of discount codes
• Disqualify certain products from discounts

For more information on discount rejections, visit the tutorial.

Effective immediately: The following customer-related fields now require the write_customers scope and the create_and_edit_customers permission:

• Customer.emailOpenTrackingUrl (deprecated)
• Customer.unsubscribeUrl (deprecated)
• CustomerEmailAddress.openTrackingUrl
• CustomerEmailAddress.marketingUnsubscribeUrl
• CustomerPhoneNumber.marketingUnsubscribeUrl

Reason for change

This update addresses a security vulnerability. These fields return URLs with secret tokens that can modify customer marketing consent, such as unsubscribing a customer. Previously, apps with only the read_customers scope could access these URLs, potentially leading to unauthorized changes to customer preferences. By updating the access requirements, we aim to prevent such security risks.

According to our API breaking change policy, security fixes are implemented immediately across all API versions, bypassing the standard deprecation process.

Action required

If your app queries these fields, you must:

1. Update your app to include the write_customers access scope. Previously, the read_customers scope was sufficient.
2. Ensure the user making the request has the create_and_edit_customers permission.

Apps that only have the read_customers scope will now encounter an access denied error when attempting to query these fields.

As of API version 2026-04, the Storefront API will return a MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR cart error code when a Cart Transform Function encounters a runtime error during cart operations such as cartCreate or cartLinesAdd.

Previously, when a Cart Transform Function failed, the Storefront API returned a generic INVALID error code with the message "An error occurred in your cart." This made it difficult to distinguish between failures in Cart Transform Functions and other validation errors programmatically.

With the introduction of the specific MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR code, you can now:

• Identify and handle Cart Transform Function failures separately from other cart errors.
• Implement more precise error handling and debugging in your storefront.

This change enhances your ability to maintain and troubleshoot your storefront implementation effectively.

Example error response:

{
  "data": {
    "cartCreate": {
      "cart": null,
      "userErrors": [
        {
          "code": "MERCHANDISE_LINE_TRANSFORMERS_RUN_ERROR"
        }
      ]
    }
  }
}

To improve the integration of marketing platforms that track conversions beyond traditional sales metrics, we have added new fields to the MarketingEngagementCreateInput and MarketingEngagement objects on the MarketingEngagementCreate mutation. These enhancements enable more comprehensive data integration into Shopify's marketing reports.

The new fields are:

• primaryConversions: This field tracks the main conversion events, such as purchases or sign-ups, that are most critical to your marketing goals.
• allConversions: This field captures all types of conversion events, providing a complete view of customer interactions.

For more information on sharing marketing data, please visit our help page.

We have introduced a new processedAt input field to the refundCreate mutation. With this field, you can manage refund timestamps in your records more effectively.

If you don't provide a processedAt value, then the current timestamp is used by default. This ensures that existing integrations continue to function without modification.

What's new

The refundCreate mutation now includes an optional processedAt field, enabling you to specify the exact time a refund was processed. This feature is particularly useful for:

• Processing backdated refunds: Manage refunds initiated offline or those that need to reflect a specific processing date for accounting purposes.
• Maintaining accurate financial records: Ensure your refund timestamps align with your actual business operations and reporting periods.

How it works

To use this feature, include the processedAt field when creating a refund:

mutation refundCreate($input: RefundInput!) {
  refundCreate(input: $input) {
    refund {
      id
      processedAt
      createdAt
    }
    userErrors {
      field
      message
    }
  }
}

With input:

{
  "input": {
    "orderId": "gid://shopify/Order/123",
    "processedAt": "2024-12-01T10:30:00Z",
    "refundLineItems": [...]
  }
}

If you don't provide a processedAt value, the current timestamp is used by default. This ensures that existing integrations continue to function without modification.

This changelog relates to concurrency protection features.

We're making the idempotent directive introduced here mandatory for the following mutations in version 2026-04:

• refundCreate
• inventoryShipmentReceive
• inventoryAdjustQuantities
• inventoryMoveQuantities
• inventorySetQuantities
• inventorySetOnHandQuantities
• inventoryShipmentCreateInTransit
• inventoryShipmentCreate
• inventoryTransferCreate
• inventoryTransferCreateAsReadyToShip
• inventoryTransferDuplicate
• inventoryTransferSetItems
• inventorySetScheduledChanges
• inventoryActivate
• inventoryShipmentAddItems
• locationActivate
• locationDeactivate

Note: Even though the idempotency directive doesn't show up as mandatory at the schema level, calling these mutations without an idempotency directive will result in an error at runtime.

What you need to do

Developers using these mutations must update their application logic to include the @idempotent directive before migrating to version 2026-04

How to use the directive

An idempotency key is a unique identifier (we recommend using a UUID) that you provide when making a mutation request (generally, you would regenerate this key on page load and after successful operations). If you retry the same request with the same idempotency key due to network issues or timeouts, Shopify will recognize it as a duplicate and ensure the inventory is only adjusted once (or that the refund is only created once), protecting against double-counting. It will return the result of the original operation instead of creating a new one.

Example usage:

  mutation {
    inventoryAdjustQuantities(
      input: {
        reason: "restock"
        name: "available"
        changes: [{
          delta: 5
          inventoryItemId: "gid://shopify/InventoryItem/123"
          locationId: "gid://shopify/Location/456"
        }]
      }
    ) @idempotent(key: "4f5b6ebf-143c-4da5-8d0f-fb8553bfd85d") {
      inventoryAdjustmentGroup {
        id
      }
      userErrors {
        code
        message
      }
    }
  }

Why we made this change

Idempotency keys are essential for building robust, production-ready integrations. Duplicate inventory adjustments and duplicate refunds have long been a pain-point for merchants and for Shopify, resulting in inventory inconsistencies and financial losses. Making idempotency mandatory for our refund and inventory mutations will mitigate these problems.

For more information on how to implement idempotency, refer to our docs.

Error codes

If there's an issue with your idempotency key usage, you'll receive one of these error codes:

• IDEMPOTENCY_CONCURRENT_REQUEST: Another request with the same idempotency key is currently being processed
• IDEMPOTENCY_KEY_PARAMETER_MISMATCH: The same idempotency key was used with different parameters

This changelog relates to concurrency protection features.

Starting in 2026-04, the changeFromQuantity field will be required for the following mutations:

• inventoryAdjustQuantities: Available on the InventoryChangeInput input type
• inventoryMoveQuantities: Available on the InventoryMoveQuantityTerminalInput input type
• inventorySetOnHandQuantities: Available on the InventorySetQuantityInput input type
• productVariantsBulkUpdate: Available on the InventoryAdjustmentInput type, which is available on the quantityAdjustments field of the ProductVariantsBulkInput type

This is a breaking change. Note that even though the changeFromQuantity field doesn't show up as mandatory at the schema level, calling these mutations without passing in null or passing in the current actual quantity will result in an error at runtime.

What you need to do

Before migrating to version 2026-04, update your application logic to include the changeFromQuantity argument:

• To enable concurrency checks (Recommended): Pass the expected current quantity.
• To opt-out (skip checks): Explicitly pass changeFromQuantity: null

How to use the field

The changeFromQuantity field is useful to keep inventory data accurate, even if multiple updates are happening at the same time. If the actual quantity doesn't match the value you provide, the mutation will fail with a CHANGE_FROM_QUANTITY_STALE error, preventing unintended overwrites.

In the following example, the adjustment will only succeed if the current available quantity is 50. If another process has modified the quantity in the meantime, you'll receive an error and can retry with the updated value.

For more information on compare and swap, and when you should opt out of comparison checks, refer to our docs. We encourage users to avoid opting-out unless it's justified by their use-case.

  mutation {
    inventoryAdjustQuantities(
      input: {
        reason: "correction"
        name: "available"
        changes: [{
          delta: 10
          changeFromQuantity: 50
          inventoryItemId: "gid://shopify/InventoryItem/123"
          locationId: "gid://shopify/Location/456"
        }]
      }
    ) {
      inventoryAdjustmentGroup {
        id
      }
      userErrors {
        code
        message
      }
    }
  }

This changelog consolidates all updates related to concurrency protection features for inventory and refund mutations.

Compare and swap changes

To prevent race conditions in inventory updates, we're introducing compare and swap protection through the changeFromQuantity field across multiple API versions:

• 2026-01 : Introducing a changeFromQuantity field for various inventory mutations
• 2026-01: Introducing a changeFromQuantity field for the inventorySetQuantities mutation and deprecating the old compare And swap fields
• 2026-04: Making the changeFromQuantity field required (with explict opt-out) for various inventory mutations (BREAKING)
• 2026-04: Making the changeFromQuantity field required (with explict opt-out) for the inventorySetQuantities mutation and removing the old compare And swap fields (BREAKING)

Idempotency changes

To prevent duplicate operations when requests are retried, we're introducing idempotency protection through the idempotent directive:

• 2026-01: Introducing an optional idempotent directive for various inventory and refund mutations
• 2026-04 Making the idempotent directive required for various inventory and refund mutations (BREAKING)

Why we made these changes

Most inventory adjustments lack concurrency and idempotency protection, leaving systems vulnerable to race conditions, duplicate updates, and integrity issues—especially when commands are retried due to network disruptions. To solve this we will standardize concurrency and idempotency checks across Inventory APIs.

For more information, refer to our idempotency and compare and swap docs.

This changelog is relates to concurrency protection features.

We're making the changeFromQuantity field introduced in 2026-01 mandatory and removing the compareQuantity and ignoreCompareQuantity fields for the inventorySetQuantities mutation.

This is a breaking change. Note that even though the changeFromQuantity field doesn't show up as mandatory at the schema level, calling these mutations without passing in null or passing in the current actual quantity will result in an error at runtime.

What you need to do

Before migrating to version 2026-04, update your application logic to include the changeFromQuantity argument:

• To enable concurrency checks (Recommended): Pass the expected current quantity.
• To opt-out (skip checks): Explicitly pass changeFromQuantity: null

Additionally, before migrating, you must remove the ignoreCompareQuantity argument and the compareQuantity argument from your mutation calls.

How to use the field

Previously, to bypass comparison checks, you set ignoreCompareQuantity to true.

Now, to bypass comparison checks, you explicitly pass null to the changeFromQuantity field. To enable checks, pass an integer that represents the initial quantity before it is updated to the desired value.

In the following example, the operation will only successfully set the new available quantity to 12 if the current available quantity is 5. If another process has modified the quantity in the meantime, you'll receive an error and can retry with the updated value.

  mutation {
    inventorySetQuantities(
      input: {
      quantities: [
        {
          quantity: 12,
          inventoryItemId: "gid://shopify/InventoryItem/2",
          locationId: "gid://shopify/Location/1",
          changeFromQuantity: 5
        }
      ],
      reason: "correction",
      name: "available"
    }
    ) {
      inventoryAdjustmentGroup {
        id
      }
      userErrors {
        code
        message
      }
    }
  }

Removing legacy fields

The compareQuantity and ignoreCompareQuantity fields will be removed in version 2026-04.

For more information on compare and swap, and when you should opt out of comparison checks, refer to our docs. We encourage users to avoid opting-out unless it's justified by their use-case.

We've made it possible create subscription contracts without an attached payment method using the GraphQL Admin API. Contracts created through checkout will continue to require a payment method.

With this update, if you’re importing existing contracts with missing or expired payment methods, you can still migrate them to Shopify first and collect or update payment details later—removing a common onboarding blocker while keeping the buyer experience unchanged.

Note: Charges can’t be processed until a valid payment method is added.

Learn more in the dev docs.

We’re discouraging use of OrderTransaction.receiptJson. You should stop relying on receiptJson in production apps.

receiptJson is gateway-defined, inconsistently shaped, and may change without notice. Because its structure isn’t stable or typed, changes can lead to unexpected app failures.

We've updated bulk operations in the GraphQL Admin API to process large datasets faster.

What's new: Here's what we've done:

• Support for all mutations: Previously bulk mutations only supported a limited set of actions. Now, you can execute any mutation using bulk operations across all API versions.
• Larger file uploads : Upload files up to 100MB (up from 20MB), reducing the number of operations needed for large datasets.
• Five concurrent operations: Each app can run up to five bulk operations per shop simultaneously. Split large imports and exports into parallel jobs and complete them faster without managing throttling or concurrency yourself.

For setup guidance and examples, visit the developer documentation.

Starting with the 2026-01 API version, the authorizationCode field on the OrderTransaction object is deprecated. We recommend using the paymentId field instead.

The paymentId field provides a consistent, standardized identifier for payment reconciliation across all payment providers on Shopify. Adopting paymentId ensures your integration relies on the most stable and supported field for tracking and reconciling transactions, regardless of the underlying payment gateway.

Warning: paymentId returns a Shopify-specific identifier, which differs from the provider-specific value in authorizationCode. Ensure your systems are updated to store and reconcile using this new ID format.

Recommended migration

Developers should update their queries to use the paymentId field when accessing OrderTransaction objects in the Admin GraphQL API. Replace instances of authorizationCode with paymentId. By making these changes, you ensure your app relies on the standard identifier for payment transactions.

For example, update your query from:

query TransactionDetails {
  order(id: "gid://shopify/Order/12345") {
    transactions {
      id
      authorizationCode
    }
  }
}

to:

query TransactionDetails {
  order(id: "gid://shopify/Order/12345") {
    transactions {
      id
      paymentId
    }
  }
}

We've expanded the resources that you can query by metafield value to include Companies and Company Locations. We've also expanded how you can query metafield values on Products, Orders, and Metaobject entries to include:

• Greater than and less than comparisons
• Prefix matching
• Boolean operators (AND, OR, NOT)

These work across more metafield types than before. No more fetching all resources and iterating through metafield values client-side. You can filter directly in your queries, and the query options now match how other properties are searchable on resources.

Today, we're introducing Sidekick app extensions to give your app new ways to integrate your app with Sidekick, Shopify's AI-enabled commerce assistant.

What are Sidekick app extensions?

Your app can connect its data and workflows using app extensions. Sidekick can search your app’s data, answer questions with your app’s context, and take merchants straight to the right page in your app.

You can also let Sidekick assist directly inside your app. Define safe, scoped actions—like editing an email template, creating a product review, or updating a support issue—and Sidekick will suggest changes and bring up the right UI, but merchants stay in control of what gets updated.

Learn more

Jump in and take a tour through our documentation on Sidekick app extensions to learn how you can integrate these new super-powers into your app!

Holler at us

Leave us feedback, comments, and questions in the Shopify Developer Community. We'd love to hear from you.

Announcing 150+ updates to Shopify.

See the updates

Offline access tokens now can optionally expire after 60 minutes and come with a refresh token. You can use the refresh token to obtain a new offline access token without requiring merchant interaction. This update aligns our process with the OAuth 2.0 specification and enhances security.

How expiry works

OAuth authorizes your app to act on behalf of a store. Once the merchant approves your requested scopes, you receive tokens.

1. Direct the merchant through OAuth and request offline access.
2. We provide:
   • access_token access token to be used to make API requests
   • expires_in time to live (TTL) of the access token in seconds (3600 seconds)
   • refresh_token used to request a new access token with an updated TTL
3. Before or after the access token expires, exchange the refresh_token at the token endpoint to receive a new offline access token.
4. Update stored tokens with the latest values returned by the refresh response.

Refer to the OAuth documentation for specific parameters, error codes, and retry guidance.

How to implement expiry

• Securely store refresh tokens, as they are sensitive credentials that can generate new access tokens. Use a secrets manager, encrypt at rest, and restrict access.
• To implement expiring tokens, you'll need to:
  • Track the access token’s 60-minute expiry.
  • Proactively refresh tokens a few minutes before they expire, and when you recieve a 401 response.
  • Update stored tokens with the latest values from the refresh response.
  • Remove any assumptions in your code that offline tokens never expire.
• Monitor logs and alerts for token refresh failures, and revert to a new OAuth authorization if necessary.

Migration and compatibility

• This change is additive: existing perpetual offline tokens will continue to function for now.
• Available with both token exchange and authorization code grant types. The client credentials grant already supports expiry and refresh using a slightly different OAuth 2 spec process.

We've overhauled the Point of Sale (POS) UI extensions reference, making it easier for you to build extensions that integrate into Shopify's Point of Sale interface.

Updates include:

• Expanded guidance: Detailed explanations and real-world use cases help you implement features.
• More examples: New code snippets and an example switcher help you find what you need faster.
• Clearer relationships: Support matrices show at a glance how targets, APIs, and components work together.
• Developer feedback addressed: We reviewed and resolved 100% of feedback submitted through our Was this doc helpful? form.

Check out the new POS UI extensions reference.

We've overhauled the Dev Assistant to make it a more reliable and comprehensive companion for your development workflow. While the Assistant is already a familiar tool, this update introduces a new engine designed to deliver higher accuracy and broader knowledge across the entire ecosystem.

Key improvements include:

• Comprehensive platform knowledge: The Assistant now supports the full breadth of the Shopify development platform. Whether you're working with the GraphQL Admin API, building UI extensions, or configuring Hydrogen, you can ask about any aspect of the platform and get a relevant answer.
• Verified code examples: We've improved the accuracy of generated solutions. The Assistant now validates code blocks against our schemas before rendering the response, ensuring the snippets you receive are syntactically correct and ready to use.
• Direct documentation access: It's now easier to verify answers and dive deeper into specific topics. The Assistant provides transparent resource links alongside every response, enabling you to navigate quickly to the exact pages on shopify.dev that were used to generate the answer.

Enhance your app's global admin performance with regional data from the Web Vitals API. Each Web Vitals event now includes a country field with a two-letter ISO country code, allowing you to pinpoint where users encounter performance issues with your app.

This update enables you to understand regional performance patterns and optimize your app for users worldwide. You can segment admin performance data by geography to identify slow-loading regions, troubleshoot location-specific issues, and ensure consistent user experiences across various markets.

No additional setup is required; existing onReport callbacks automatically receive the new country field. Use this data to create more targeted performance optimizations and deliver faster admin experiences for merchants globally.

For more information about the Web Vitals API, visit the developer documentation.

Preparing your app for review just became more straightforward. We've simplified and updated App Store requirements to be clearer, better organized, and easier to work with throughout the development process.

What's improved:

• Streamlined structure: Requirements are organized for better structure and readability, so you can understand exactly what’s needed.
• Numbered for easy reference: Each requirement has a clear number and hyperlink associated with it, making it simple to reference specific items as you work through them.

What this means for you: These improvements remove friction from understanding and following requirements, so you can focus on building features that merchants love.

All updated requirements are now live in the developer documentation.

In the API 2026-01 release candidate version, we've introduced consolidated options in the GraphQL Admin API. This feature allows you to support merchants by combining options, such as size and length, to streamline the checkout process for customers.

The new consolidatedOptions field has been added to the ProductBundleCreateInput and ProductBundleUpdateInput input objects in the GraphQL Admin API. Use this field to define which buyer-facing options to combine across components, ensuring a single selector for customers purchasing fixed bundles.

Learn more about combining bundle options by following this tutorial.

Developers and merchants can now access ShopifyQL data through a dedicated Python SDK and CLI tool designed for analytics workflows.

The ShopifyQL Python package provides a clean, Pythonic interface for ShopifyQL queries while handling GraphQL API complexity behind the scenes. It eliminates manual OAuth implementation and HTTP request handling, returning data directly as either pandas DataFrames or polars DataFrames.This enables you to create reporting apps and export data to data warehouses without managing GraphQL interactions directly.

Learn more.

As of API version 2026-04, tax calculation requests for tax partner apps now include buyer metafields. These fields provide custom data associated with customers (for D2C orders) and companies (for B2B orders) that may affect tax calculations. This enhancement allows tax partners to access merchant-defined buyer attributes for more accurate tax determination and compliance reporting.

What's new

The tax calculation request payload now includes new metafields arrays in the buyer identity section:

1. Customer metafields (cart.buyer_identity.customer.metafields[]):

   • Available for D2C orders
   • Contains custom attributes defined by the merchant for individual customers
   • Examples include prescription status, tax exemption certificates, and customer classifications

2. Company metafields (cart.buyer_identity.purchasing_company.company.metafields[]):

   • Available for B2B orders
   • Contains custom attributes defined by the merchant for business customers
   • Examples include wholesale status, resale certificates, and business classifications

Metafield structure

Each metafield contains information on namespace, key, type, and value. The following example shows the structure before and after the update:

Customer metafields

Before (2026-01 and earlier):

{
  "customer": {
    "id": "123",
    "exemptions": []
  }
}

After (2026-01):

{
  "customer": {
    "id": "123",
    "exemptions": [],
    "metafields": [
      {
        "namespace": "custom",
        "key": "has_prescription",
        "type": "boolean",
        "value": "true"
      }
    ]
  }
}

Company metafields

Before (2026-01 and earlier):

{
  "purchasing_company": {
    "company": {
      "id": "456",
      "external_id": "ACME-001"
    },
    "company_location": {
      "id": "789",
      "external_id": "ACME-LOCATION-001"
    }
  }
}

After (2026-04):

{
  "purchasing_company": {
    "company": {
      "id": "456",
      "external_id": "ACME-001",
      "metafields": [
        {
          "namespace": "custom",
          "key": "customer_class",
          "type": "single_line_text_field",
          "value": "wholesale"
        }
      ]
    },
    "company_location": {
      "id": "789",
      "external_id": "ACME-LOCATION-001"
    }
  }
}

You can now run theme commands across multiple environments simultaneously, making it easier to manage themes across development, staging, and production stores in a single operation.

Starting in API version 2026-01, Venmo and PayPal are treated as separate payment methods when using payment customization functions. Previously, hiding PayPal's express checkout placement would automatically hide Venmo as well. With this change, you can now hide or show Venmo independently from PayPal in your payment customization logic.

Action required

If you were previously hiding PayPal's accelerated checkout placement to also hide Venmo, you must now explicitly hide Venmo separately in your payment customization function.

Previous behavior (automatic):

• Hiding PayPal's ACCELERATED_CHECKOUT placement would automatically hide Venmo.

export function run(input) {
  const operations = [];

  const paypal = input.paymentMethods.find(method =>
    method.name.includes("PayPal")
  );

  if (paypal && shouldHidePayPal(input)) {
    operations.push({
      paymentMethodHide: { paymentMethodId: paypal.id }
    });
    // Venmo was implicitly hidden
  }

  return { operations };
  
}

New behavior (explicit control required):

• Hiding PayPal's ACCELERATED_CHECKOUT placement only hides PayPal.
• To hide Venmo, you must now explicitly hide Venmo's placement separately. Venmo is only available in the ACCELERATED_CHECKOUT placement.

To maintain the previous behavior of hiding both PayPal and Venmo together, update your payment customization function logic to explicitly target the Venmo payment method. Venmo can be targeted by checking for the exact string "Venmo" in the payment method's name field.

export function run(input) {
  const operations = [];

  const paypal = input.paymentMethods.find(method =>
    method.name.includes("PayPal")
  );

  const venmo = input.paymentMethods.find(method =>
    method.name === "Venmo"
  );

  if (shouldHidePayPal(input)) {
    if (paypal) {
      operations.push({
        paymentMethodHide: { paymentMethodId: paypal.id }
      });
    }

    // NEW: Must explicitly hide Venmo if you want both hidden
    if (venmo) {
      operations.push({
        paymentMethodHide: { paymentMethodId: venmo.id }
      });
    }
  }

  return { operations };
}

Tangle is a platform-agnostic, open source experimentation platform with a visual editor and content-based caching.

With Tangle, you can build ML and data pipelines collaboratively, choosing from reusable modules in the component library or adding your own.

Learn more about Tangle.

We've released the @shopify/shopify-function-test-helpers package to simplify writing comprehensive integration tests for Shopify Functions using real production data. All function extension templates now include integration tests powered by this package.

Why this matters

1. Test the actual WASM binary: Integration tests validate the compiled code uploaded to Shopify's infrastructure, helping to catch breaking changes before they hit production; including compilation errors, runtime crashes, or serialization issues that unit tests might miss.
2. Easily add new scenarios: Create new fixtures in the tests/fixtures/ directory, and the test suite will automatically include them. There's no need to write additional test code for each new scenario.
3. Build from real production data: Create your fixture library by copying function run logs directly from production. This enables you to test against the actual inputs your function encounters, ensuring your tests reflect real-world scenarios.

Learn more

For more details, visit the package page or explore the Shopify developer documentation.

Order editing mutations now include additional validations. When these validations fail, the API returns relevant userErrors in the response. These changes apply to all supported API versions.

Gift card amount limit

Gift cards added with the orderEditAddVariant mutation are now subject to a maximum value limit. Limits vary by currency but are set high enough to accommodate typical merchant use cases.

Error message

Gift card amount exceeds the limit of {limit}

Line item count limit

Orders are limited to a maximum number of active line items when using the orderEditAddVariant and orderEditAddCustomItem mutations.

Error message

The number of line items exceeds the limit of {limit}

Line item subtotal limit

Orders now validate that the combined value of all active line items stays within the subtotal limit.

This validation already exists at checkout and now applies to order editing as well. The current limit is set high enough to avoid blocking legitimate orders in normal use.

Error message

Line item subtotal exceeds the limit of {limit}

The InventoryItem.variant field has been deprecated and will be removed in a future API version. Use the new InventoryItem.variants connection instead.

To learn more, see InventoryItem object or inventoryItem query in the GraphQL Admin API reference.

Why we're making this change

The new variants connection allows for retrieving ProductVariants through a paginated connection, rather than a single variant object. This update prepares the API to support multiple variants sharing a single inventory item in the future.

Initially the variants connection will return a single node. However, we recommend updating your integrations to handle variants as a connection to accommodate future changes.

What you need to do

Modify your GraphQL queries by replacing variant with variants. Since variants is a connection, ensure you request edges and nodes. Although the deprecated variant field remains functional in all supported API versions, including 2026-01 , it will eventually be removed. Updating your queries now will ensure they remain compatible with future API versions.

Before (deprecated):

{
  inventoryItem(id: "gid://shopify/InventoryItem/123") {
    variant {
      id
      sku
    }
  }
}

After (recommended):

{
  inventoryItem(id: "gid://shopify/InventoryItem/123") {
    variants(first: 10) {
      edges {
        node {
          id
          sku
        }
      }
    }
  }
}

As of API version 2026-01, the shopAddress field will be introduced to the Shop object in the GraphQL Admin API. This new field replaces the now-deprecated billingAddress field, which will be removed in a future version. shopAddress will have identical structure and values as billingAddress.

Billing account address currently corresponds to the shop address. This change makes that relationship clearer, and supports potential future separation of billing and shop addresses.

Action required

You should update your queries to use the new shopAddress field when accessing the Shop object in the GraphQL Admin API. Replace instances of shop { billingAddress { ... } } with shop { shopAddress { ... } }.

For example, update your query from:

query ShopAddress {
  shop {
    billingAddress {
      address1
      address2
      city
      province
      zip
      country
    }
  }
}

to:

query ShopAddress {
  shop {
    shopAddress {
      address1
      address2
      city
      province
      zip
      country
    }
  }
}

By making these changes, you ensure compatibility with future API versions.

As of API version 2026-01, the tax_summaries/create webhook and tax calculation requests for Tax Partner Apps include additional fields for currency. These fields provide amounts in both shop currency and presentment currency. This enhancement allows tax Partners to perform calculations and reporting in the merchant's accounting currency while maintaining the customer-facing currency for display.

What's New

The webhook and tax calculation request payloads now include new MoneyBag fields in both shop currency and presentment currency in the following locations:

1. Sale Records (agreements[].sales[]):

   • discount_amount_set
   • tax_amount_set
   • amount_before_taxes_after_discounts_set
   • amount_after_taxes_after_discounts_set

2. Cart Line Costs (delivery_groups[].cart_lines[].cost):

   • amount_per_quantity_set
   • subtotal_amount_set
   • total_amount_set

These fields complement the existing single-currency amount fields and are available when shops have multi-currency enabled.

MoneyBag Structure

The new MoneyBag fields contain two MoneyV2. Below is an example of the structure:

Before (2025-10 and earlier):

{
    "amount_before_taxes_after_discounts": {
        "currency_code": "CAD",
        "amount": "135.00"
    }
}

After (2026-01):

{
    "amount_before_taxes_after_discounts": {
        "currency_code": "CAD",
        "amount": "135.00"
    },
    "amount_before_taxes_after_discounts_set": {
        "shop_money": {
            "currency_code": "USD",
            "amount": "100.00"
        },
        "presentment_money": {
            "currency_code": "CAD",
            "amount": "135.00"
        }
    }
}

This changelog relates to concurrency protection features.

The following mutations now support the optional changeFromQuantity field:

• inventoryAdjustQuantities: Available on the InventoryChangeInput input type
• inventoryMoveQuantities: Available on the InventoryMoveQuantityTerminalInput input type
• inventorySetOnHandQuantities: Available on the InventorySetQuantityInput input type
• productVariantsBulkUpdate: Available on the InventoryAdjustmentInput type, which is available on the quantityAdjustments field of the ProductVariantsBulkInput type

Note: The quantityAdjustments field of the productVariantsBulkUpdate mutation will only be public in version 2026-01.

How to use the field

The changeFromQuantity field is useful to keep inventory data accurate, even if multiple updates are happening at the same time. If the actual quantity doesn't match the value you provide, the mutation will fail with a CHANGE_FROM_QUANTITY_STALE error, preventing unintended overwrites.

In the following example, the adjustment only succeeds if the current available quantity is 50. If another process has modified the quantity in the meantime, you'll receive an error and can retry with the updated value. To opt-out of comparison checks you can explicitly pass in null to the changeFromQuantity field.

  mutation {
    inventoryAdjustQuantities(
      input: {
        reason: "correction"
        name: "available"
        changes: [{
          delta: 10
          changeFromQuantity: 50
          inventoryItemId: "gid://shopify/InventoryItem/123"
          locationId: "gid://shopify/Location/456"
        }]
      }
    ) {
      inventoryAdjustmentGroup {
        id
      }
      userErrors {
        code
        message
      }
    }
  }

For more information on compare and swap, and when you should opt out of comparison checks, refer to our docs. We encourage users to avoid opting-out unless it's justified by their use case.

This changelog relates to concurrency protection features.

We're introducing idempotency keys for several inventory and refund mutations. This enhancement helps you build more reliable integrations by preventing duplicate operations when retrying failed requests. You pass idempotency keys in using an idempotent directive. Refer to the idempotent requests docs for more details.

The following mutations now support the optional idempotent directive:

• refundCreate
• inventoryShipmentReceive
• inventoryAdjustQuantities
• inventoryMoveQuantities
• inventorySetQuantities
• inventorySetOnHandQuantities
• inventoryShipmentCreateInTransit
• inventoryShipmentCreate
• inventoryTransferCreate
• inventoryTransferCreateAsReadyToShip
• inventoryTransferDuplicate
• inventoryTransferSetItems
• inventorySetScheduledChanges
• inventoryActivate
• inventoryShipmentAddItems
• locationActivate
• locationDeactivate

Note: While the idempotent directive is optional for now, we plan to make it mandatory for these mutations in version 2026-04.

How to use the directive

An idempotency key is a unique identifier (we recommend using a UUID) that you provide when making a mutation request (generally, you would regenerate this key on page load and after successful operations). If you retry the same request with the same idempotency key due to network issues or timeouts, Shopify will recognize it as a duplicate and ensure the inventory is only adjusted once (or that the refund is only created once), protecting against double-counting. It will return the result of the original operation instead of creating a new one.

Example usage:

  mutation {
    inventoryAdjustQuantities(
      input: {
        reason: "restock"
        name: "available"
        changes: [{
          delta: 5
          inventoryItemId: "gid://shopify/InventoryItem/123"
          locationId: "gid://shopify/Location/456"
        }]
      }
    ) @idempotent(key: "4f5b6ebf-143c-4da5-8d0f-fb8553bfd85d") {
      inventoryAdjustmentGroup {
        id
      }
      userErrors {
        code
        message
      }
    }
  }

Why we made this change

Idempotency keys are essential for building robust, production-ready integrations. Network failures and timeouts are inevitable, and without idempotency protection, retrying requests could lead to duplicate refunds, incorrect inventory counts, or other data inconsistencies. Making this feature publicly available gives you the tools to handle these scenarios safely.

Error codes

If there's an issue with your idempotency key usage, you'll receive one of these error codes:

• IDEMPOTENCY_CONCURRENT_REQUEST: Another request with the same idempotency key is currently being processed.
• IDEMPOTENCY_KEY_PARAMETER_MISMATCH: The same idempotency key was used with different parameters.

What's new

The created_at field from tax_summaries/create webhook for tax partners will now return timestamps in UTC format with the Z suffix, including millisecond precision.

Action required

Update your parsing logic to handle the new format. The following are examples of the format prior to and after the change:

Versions prior to 2026-01:

{
  "id": 14,
  "shop_id": 1,
  "order_id": 7,
  "created_at": "2025-11-19T08:16:53-05:00",
  "summary": {
    ...
  }
}

Versions 2026-01 and higher.

{
  "id": 14,
  "shop_id": 1,
  "order_id": 7,
  "created_at": "2025-11-19T13:16:53.784Z",
  "summary": {
    ...
  }
}

We've added a new processing error for subscription billing attempts: INVALID_BILLING_ADDRESS.

This error is returned when one or more fields in the billing address contain invalid data. Validated fields include:

• firstName or lastName
• address1 or address2
• city
• province or provinceCode
• country or countryCode
• zip (postal code)
• phone
• company

This changelog relates to concurrency protection features.

We've enhanced the compare-and-swap functionality in the inventorySetQuantities mutation to make concurrent inventory updates more intuitive. You can now use the new changeFromQuantity field in InventoryQuantityInput to explicitly choose whether to perform quantity comparison checks.

The use of compareQuantity and ignoreCompareQuantity will be deprecated .

This 2026-01 change isn't considered breaking because if users don't pass in a value for changeFromQuantity, the mutation will fallback to using the values for compareQuantity and ignoreCompareQuantity.

How to use the field

Previously, to bypass comparison checks, you set ignoreCompareQuantity to true.

Now, to bypass comparison checks, you explicitly pass null to the changeFromQuantity field. To enable checks, pass an integer that represents the initial quantity before it is updated to the desired value.

Passing any value (including null) to changeFromQuantity will override any values passed to the compareQuantity and ignoreCompareQuantity fields. In the following example, the operation will only successfully set the new available quantity to 12 if the current available quantity is 5. If another process has modified the quantity in the meantime, you'll receive an error and can retry with the updated value.

  mutation {
    inventorySetQuantities(
      input: {
      quantities: [
        {
          quantity: 12,
          inventoryItemId: "gid://shopify/InventoryItem/2",
          locationId: "gid://shopify/Location/1",
          changeFromQuantity: 5
        }
      ],
      reason: "correction",
      name: "available"
    }
    ) {
      inventoryAdjustmentGroup {
        id
      }
      userErrors {
        code
        message
      }
    }
  }

Deprecating legacy fields

The compareQuantity and ignoreCompareQuantity fields will be deprecated in version 2026-01. We plan to remove them entirely starting from version 2026-04.

For more information on compare and swap, and when you should opt out of comparison checks, refer to our docs. We encourage users to avoid opting-out unless it's justified by their use-case.

We're excited to introduce a new deployment tutorial for Google Cloud Run.

After scaffolding a Shopify app through the CLI and building out functionality in a local development store, what's next?

Deployment!

This tutorial guides you through the complete process of deploying your production Shopify apps, using Google Cloud Run as the target. You'll configure a project with the necessary permissions for continuous deployment, you'll set up a production database for persistent storage, and configure load balancing for multiple instances of your app across multiple regions.

Take a look and share your thoughts (including how you deploy your apps differently) on the Shopify community forum!

The Shopify Dev MCP server now includes support for code generation for POS (Point of Sale) UI extensions.

With this update, you can use the Shopify Dev MCP as a virtual pair programmer within your preferred IDE. This enhancement allows you to:

• Generate code snippets efficiently
• Explore API capabilities seamlessly
• Accelerate your development process across the Shopify platform

Get Started

If you're already using the Shopify Dev MCP server, support for POS UI extensions is automatically included in the latest version. If not, follow these steps to get started:

1. Configure the Shopify Dev MCP server to integrate it with your development environment.
2. Unlock the new capabilities by ensuring your setup is up-to-date.

By following these steps, you can take full advantage of the new features and enhance your development workflow.

We will be enforcing Shopify's protected customer data policy for all web pixel extensions starting on December 10th, 2025. Customer personally identifiable information (PII)—including name, email, phone, and address fields—will only be present in web pixel payloads when the app has been approved for the corresponding protected scopes.

What’s changing

• Web pixel payloads will be filtered at runtime based on the app’s approved access scopes.
• If your app is not approved for a given scope, the corresponding fields in the pixel event will be set to null. Event data structure remains stable.
• Enforcement applies on all web pixel surfaces: storefront, checkout, and customer accounts.
• Custom pixels are out of scope for this change.

Protected scopes enforced

• read_customer_name
• read_customer_email
• read_customer_phone
• read_customer_address
• read_customer_personal_data

Example

{
  "event": "checkout_completed",
  "customer": {
    "email": null,           // null if not approved for read_customer_email
    "first_name": null,      // null if not approved for read_customer_name
    "phone": null            // null if not approved for read_customer_phone
  },
  "shipping_address": {
     "first_name": null,	// null if not approved for read_customer_name
     "address_1": null, 	// null if not approved for read_customer_address
     "address_2": null, 	// null if not approved for read_customer_address
     "zip": null,      	// null if not approved for read_customer_address
     "phone": null            // null if not approved for read_customer_phone
     [other address fields exempt]
  }
}

Non-PII data events will continue to fire normally. Your analytics, conversion tracking, and non-PII use cases will not be affected.

What you need to do

• Review and request access. Ensure you have approval for the protected scopes you require. See Protected Customer Data Policy. You should only request the scopes your app uses.
• Update your code paths. Handle null for gated fields without breaking event handling or analytics pipelines.
• Test across surfaces. Verify behavior on storefront, checkout, and customer accounts. No downtime is expected.

This change will take effect starting on December 10th, 2025. We recommend submitting your request for protected customer data review as soon as possible if you need to maintain access to these values.

No action is needed if your app is already approved for protected customer data, or is resilient to null values. If you have questions about this change, please comment on this post in the Developer Community forums.

Starting with API version 2026-01, third-party tax apps will receive Global IDs (GIDs) in tax calculation requests and tax summary webhook payloads for all entity references of the summary section. This aligns with how Partners interact with other Shopify APIs.

These apps can now use the same identifiers across all Shopify endpoints without managing different ID formats for tax-specific integrations.

What's changed

This change affects two key integration points:

Tax calculation requests:

• Customer, Company, CompanyLocation, Product, and ProductVariant IDs now use the GID format.

Tax summary webhooks:

• All entity IDs within the summary section (Order, Customer, Product, ProductVariant, SalesAgreement, Sale, LineItem, Company, CompanyLocation ShippingLine, and TaxLine) now use the GID format.
• The webhook payload also includes new admin_graphql_api_id fields at the top level for TaxSummary, Shop, and Order entities.

Changes include:

• Top Level: Adds shop_admin_graphql_api_id and order_admin_graphql_api_id fields (existing shop_id and order_id remain as integers).
• Customer IDs: Changes from "id": "5" to "id": "gid://shopify/Customer/5".
• Product IDs: Changes from "id": "1" to "id": "gid://shopify/Product/1".
• Product Variant IDs: Changes from "id": "1" to "id": "gid://shopify/ProductVariant/1".
• Line Item IDs: Changes from "line_item_id": "5" to "line_item_id": "gid://shopify/LineItem/5".
• Sale IDs: Changes from "id": "9" to "id": "gid://shopify/Sale/9".
• Agreement IDs: Changes from "id": "6" to "id": "gid://shopify/Agreement/6".
• Company IDs: Changes from "id": "3" to "id": "gid://shopify/Company/3".
• Company Location IDs: Changes from "id": "4" to "id": "gid://shopify/CompanyLocation/4".
• Shipping Line IDs: Changes from "id": "4" to "id": "gid://shopify/ShippingLine/4".
• Tax Line IDs: Changes from "id": 6 to "id": "gid://shopify/TaxLine/6".

What you need to do

Update your integrations to handle the GID format when processing tax calculations and webhook payloads in API version 2026-01 and later. The following are some examples:

Tax calculation request

Before (2025-10 and earlier):

{
  "cart": {
    "buyer_identity": {
      "customer": {
        "id": "593934299"
      }
    }
  }
}

After (2026-01):

{
  "cart": {
    "buyer_identity": {
      "customer": {
        "id": "gid://shopify/Customer/593934299"
      }
    }
  }
}

Tax summary webhook

Before (2025-10 and earlier):

{
  "id": 80,
  "shop_id": 1,
  "order_id": 64,
  "summary": {
    "agreements": [{
      "id": "82",
      "sales": [{
        "id": "106",
        "line_item_id": "76"
      }]
    }]
  }
}

After (2026-01):

{
  "id": 80,
  "admin_graphql_api_id": "gid://shopify/TaxSummary/80",
  "shop_id": 1,
  "shop_admin_graphql_api_id": "gid://shopify/Shop/1",
  "order_id": 64,
  "order_admin_graphql_api_id": "gid://shopify/Order/64",
  "summary": {
    "agreements": [{
      "id": "gid://shopify/SalesAgreement/82",
      "sales": [{
        "id": "gid://shopify/Sale/106",
        "line_item_id": "gid://shopify/LineItem/76"
      }]
    }]
  }
}

The Carrier Service API callback payload now includes order totals and customer tags. This enhancement enables more effective shipping rate calculations by taking into account the order value and customer segments.

New Payload Fields:

• order_totals
  • subtotal_price: The total price of all items in the cart before discounts.
  • total_price: The final price after discounts and taxes.
  • discount_amount: The total discounts applied to the order.
• customer
  • id: The unique identifier for the customer.
  • tags: Labels associated with the customer, useful for segmentation.

Important: The subtotal_price might be higher than the sum of the items in the items array, as this array only includes physical items that require shipping.

These new fields are automatically included in all callback requests, allowing you to customize shipping rates using detailed order and customer information. For implementation details, refer to the Carrier Service API documentation.

Update your shipping rate calculations to leverage these new fields for a more personalized shipping experience.

As of the 2026-01 API version, the tax_summaries/create webhook and taxSummaryCreate mutation are available for Tax Partner Apps.

What's New

The taxSummaryCreate mutation enables apps to request the generation of tax summaries for orders. The tax_summaries/create webhook is triggered by events that may affect tax liability, such as fulfillments and refunds.

Using the Mutation

The mutation accepts either a specific order ID or a time range for bulk processing:

mutation {
  taxSummaryCreate(orderId: "gid://shopify/Order/123456789") {
    enqueuedOrders {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Webhook Payload

The tax_summaries/create webhook provides comprehensive tax data, including:

• Sales agreements and associated sales details
• Delivery groups with fulfillment information
• Tax exemption details
• Return sales types for refund workflows
• Order context and financial status

Requirements

• Access Scope: write_taxes
• Tax Platform Access: Tax Platform features

Learn More

For information about the Tax Platform and partnership opportunities, see Building tax apps.

As of Admin API 2026-01, the phone field is now publicly available in the orderUpdate mutation's OrderInput. This field allows developers to update the customer phone number for an order, overwriting the existing phone number.

This change brings parity with the REST API, which already supports updating the phone field through the Order resource. The phone field is particularly useful for maintaining accurate customer contact information, especially for SMS notifications and order-related communications.

For implementation details, refer to the orderUpdate mutation documentation.

As of API version 2026-01, the Storefront API returns a GIFT_CARD_RECIPIENT_INVALID error when adding a gift card to a cart with missing or invalid recipient details, such as in this example.

Previously, when adding a gift card to a cart using either the cartCreate or cartLinesAdd mutations, an empty cart and empty userErrors would be returned if any of the recipient details were invalid, such as a missing email address. With this change a GIFT_CARD_RECIPIENT_INVALID error is returned for both cartCreate or cartLinesAdd mutations, so that you can use the information to surface gift card recipient errors back to the client.

We've introduced new GraphQL queries to help you retrieve and manage bulk operations in the Admin API.

What's Changed

Here's an overview of the updates:

New Bulk Operations Retrieval Queries

We have added two new queries for accessing your bulk operations:

• bulkOperations: A connection-based query that returns a paginated list of all your bulk operations, complete with filtering and sorting options.
• bulkOperation: A single-object query that retrieves a specific bulk operation by its ID.

Enhanced Filtering and Search Capabilities

The bulkOperations connection now supports flexible querying with the following features:

• Status Filtering: Locate operations by status (e.g., canceled, completed, running).
• Type Filtering: Filter operations by type (query or mutation).
• Date Filtering: Search for operations created before or after a specific date.
• Sorting Options: Sort operations by created_at, completed_at, or status in ascending or descending order.
• Search Syntax: Use field:value patterns for precise filtering.

What You Need to Do

Depending on your requirements, follow these steps:

To List and Filter Bulk Operations

Utilize the bulkOperations connection query with search syntax:

query {
  bulkOperations(
    first: 10
    query: "status:completed operation_type:query created_at:>2025-10-10"
    sortKey: CREATED_AT
    reverse: true
  ) {
    edges {
      node {
        id
        status
        query
        createdAt
        completedAt
        url
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
  }
}

To Retrieve a Specific Bulk Operation

Use the bulkOperation query:

query {
  bulkOperation(id: "gid://shopify/BulkOperation/123456789") {
    id
    status
    query
    createdAt
    completedAt
    url
    errorCode
  }
}

If You're Using Existing Bulk Operation Workflows

No changes are necessary. The currentBulkOperation can still be used but is being deprecated.

Why We Made This Change

Previously, you could only access the most recent bulk operation through currentBulkOperation. These new queries offer:

• Complete visibility into all your bulk operations, not just the current one.
• Enhanced debugging capabilities by filtering operations by status or date.
• Efficient pagination for managing large numbers of operations.
• Simplified monitoring, debugging, and management of bulk operations at scale.

Learn More

• Bulk Operations Queries Guide

You can now create inventory transfers without specifying an origin or destination location.

Previously, the InventoryTransferCreateAsReadyToShip mutation required both origin and destination location IDs.

Now, these inputs are optional. This change supports workflows where the transfer's origin or destination is unknown at creation time.

Note: You must provide at least one of origin or location as input to validate the mutation.

Example:

mutation OmitOriginExample {
  inventoryTransferCreateAsReadyToShip(
    input: {
      lineItems: [
        { inventoryItemId: "gid://shopify/InventoryItem/...", quantity: 5 }
      ]
      originLocationId: null,
      destinationLocationId: "gid://shopify/Location/...",
    }
  ) {
    inventoryTransfer {
      id
      status
      origin { name }
      destination { name }
    }
  }
}

What you need to do

Nothing.

This isn't a breaking change. No action is required. Existing apps that provide IDs for inventory transfer origins or destinations will continue to function correctly. If your app previously required these fields, then you can update your validation logic to treat them as optional.

Built for Shopify (BFS) apps are now featured more prominently across key App Store surfaces, helping merchants discover them faster.

What's new:

• Homepage spotlight: BFS now appears in the featured header section of the App Store homepage, giving certified apps maximum exposure to browsing merchants.
• Priority recommendations: BFS apps receive preferential positioning on some category pages.
• Interactive BFS badge: All BFS badges across the App Store are now clickable to provide merchant education on BFS standards.

These enhancements work alongside existing Built for Shopify benefits including ranking boosts and the BFS search filter, making Built for Shopify the most effective way to maximize your app’s visibility and discovery potential in the App Store.

As part of the GraphQL Storefront API 2026-01 release, the cartDiscountCodesUpdate mutation now requires the discountCodes agrument to be included. Previously, the cartDiscountCodesUpdate mutation would accept a mutation with no discountCodes argument, which would not actually modify the cart in any way.

For more information about the Cart object and its related mutations, visit Shopify.dev.

The 2026-01 Admin GraphQL API introduces support for ACH payment methods, enabling merchants to accept and manage bank account-based payments through Shopify Payments. This means new types of PaymentInstrument and CustomerPaymentInstrument are now available for B2B company locations, supporting payment terms and draft orders. If your integration manages the payment lifecycle of those ways to sell, consider upgrading. If you are not on the latest version of the API, you will not find these available payment methods.

New Objects:

• BankAccount - Represents a bank account payment instrument

Updated Types:

• PaymentInstrument union - Now includes BankAccount
• CustomerPaymentInstrument union - Now includes BankAccount

The storeCreditAccountCredit mutation now includes an optional notify parameter.

• When this parameter is set to true, the account owner will receive a "store credit issued" email notification. If the parameter is not provided, no email will be sent. To enable email notifications, you must explicitly set this flag to true.

• For store credit accounts owned by a Customer, the email will be sent to the customer's default email address.

• For store credit accounts owned by a CompanyLocation, each customer associated as a CompanyContact for that company location will receive an email at their respective default email address.

For more details refer to the storeCreditAccountCredit mutation in the developer documentation.

Effective Wednesday, November 5th, 2025, the following requirement for the online store has been revised:

• Your app must not use theme app extensions or blocks to promote your app, promote related apps, or request reviews.

• App Name Branding in theme extensions is now permitted only under specific conditions: when customers directly interact with branded elements as a key aspect of their buying experience, or when removing these elements would cause confusion or harm to customers. In all other cases, the standard attribution pattern must be used.

• Your app may use App Name Branding in theme extensions only if one or both of the following criteria are met:

  • Customers directly interact with the custom branding elements as a key aspect of their buying experience, such as part of a payment method or loyalty program.
  • Removing the custom branding elements would cause confusion or harm to customers.

App Name Branding includes:

• Company or app logos, icons, branded watermarks, visual identifiers, or other branded imagery.
• Company or app name displayed as text in any form, including plain text, branded fonts, or stylized lettering.
• Custom design elements containing the name or logo of the company or app.

Standard app attribution: If your app does not meet the criteria above for App Name Branding, you must use the standard app attribution pattern. This pattern is limited to a 24x24 pixel width and height for any image or text.

Regardless of branding, all apps must not:

• Request app reviews or ratings
• Promote other apps or services

You can find this revised requirement in the online store section of the checklist of requirements page.

We’ve released a major update to POS UI extensions, aimed at reducing friction and speeding up your workflow.

Key improvements include:

• Hot reloading improvements: We've made hot reloading faster and smoother. Code changes appear on your POS test device instantly without flickering. This update also supports reloading entire navigation screens, so you no longer need to exit and re-enter a screen to see your changes.
• POS dev console: When you scan your deeplink, you are immediately directed to the POS dev console where you view your app and extension information. The console offers easy access to targets and configurations, centralizing everything you need to efficiently build your extension.
• Quick target previews: With the new "Preview" feature in the dev console, you can instantly jump to the correct screen in the POS app where your extension is rendered.
• Build error reporting: If your extension code triggers an error, you’ll now see an error UI directly on the POS device. Tapping the broken component opens the dev console with information about the extension and the error.
• App persistence: You can configure your extension to automatically reconnect after a POS restart, removing the need to deep link repeatedly.
• In-app reset: You can remove your extension without restarting the POS or your dev server, making it easy to test new deep links quickly.

Ready to get started? All you need is POS v10.13+ and Shopify CLI v3.85+. Find everything you need in our documentation.

We're excited to hear how this improves your workflow! Let us know what you think in our developer community.

We've increased the limits for metafield and metaobject definitions, providing you with more flexibility when building custom data structures for your apps and stores.

• For app developers: Each app has its own allocation, so apps aren't competing with each other for definition space.
• For merchants: Higher limits support complex workflows across multiple apps and meet custom data needs.
• For metaobject entries: The 1,000,000 entry limit per definition removes previous plan-based restrictions of 64,000 (non-Plus) and 128,000 (Plus).

With these new limits, you can:

• Create more granular data structures in your apps.
• Support larger catalogs and content libraries.
• Build apps with richer metadata without worrying about hitting limits.

Changes to metaobject definitions

App definitions

• Each app installed on a shop can create up to 256 metaobject definitions

Merchant definitions

• 128 definitions for Basic, Shopify, and Advanced plans
• 256 definitions for Plus and Enterprise plans

Metaobject entries

• Up to 1,000,000 entries per definition

Changes to metafield definitions

App definitions

• Each app can create up to 256 definitions per resource type

Merchant definitions

• 256 definitions per resource type

Note: Standard metaobject and metafield definitions do not count towards these limits.

Learn more

• Metaobject limits
• Metafield limits
• Metaobjects overview
• Metafields overview

As of October 10, 2025, the Cart AJAX API and Storefront Cart GQL API now processes simultaneous requests. For example, when sending two cart add requests at the same time, the Cart AJAX API executes both requests.

Previously, the Cart AJAX and GraphQL APIs were inconsistent in handling concurrent requests. This sometimes resulted in requests being dropped.

This is considered a bug fix for both APIs, but may require updates if the theme or storefront is unintentionally sending duplicate requests.

Note: If too many simultaneous requests are receieved, the Cart AJAX API will instead return an HTTP 409 response, while the Storefront Cart GraphQL API will return an error with code "CONFLICT" and message "Could not complete cart operation. The cart conflicted with another request".

We now support enabling and referencing standard metafield and metaobject definitions through an app’s TOML file. Key benefits include:

• Standard metafield and metaobject definitions can be enabled through TOML, and managed through the app dev or app deploy command.
• Shopify automatically distributes these definitions to multiple shops simultaneously, significantly speeding up migration processes.
• Updates are atomic, ensuring that all stores consistently maintain the same version of your definitions.

For more information, see the custom data documentation on shopify.dev.

It is now possible for all Shopify merchants to create products with up to 2,048 variants in Shopify, exceeding our historical variant limit of 100.

Please note that merchants using apps that are not using the in-support GraphQL product APIs may have a downgraded or broken experience when creating or viewing products with more than 100 variants.

Learn more about 2048 variants, including information on migrating from REST product APIs to the in-support GraphQL product APIs, in our developer docs.

Shop Minis offer immersive, full-screen buyer experiences within the Shop app. These experiences are built using familiar web technologies, leveraging our React SDK to streamline development. The Shop Minis SDK is now available for early access, enabling you to build and launch your Minis quickly and efficiently.

To create a new Mini, run the following command in your terminal. This will set up a new project with the latest version of the Shop Minis SDK:

npm init @shopify/shop-mini@latest

For more information on the SDK and available development commands, visit our documentation: Shop Minis API Documentation

POS UI Extensions 2025-10 introduces API updates for subscription selling plans support within Shopify POS.

New Cart API Methods

Adding Selling Plans

To add a selling plan to a line item in the cart, use the following method:

shopify.cart.addLineItemSellingPlan({
  lineItemUuid: 'line-item-uuid',
  sellingPlanId: 123456,
  sellingPlanName: 'Monthly Subscription - 10% off'
});

Removing Selling Plans

To remove a selling plan from a line item, use this method:

shopify.cart.removeLineItemSellingPlan('line-item-uuid');

API References

For detailed information on these methods, refer to the following documentation:

• addLineItemSellingPlan
• removeLineItemSellingPlan

Enhanced Line Item Interface

The LineItem interface has been enhanced to support selling plans:

interface LineItem {
  uuid: string;
  productId: number;
  requiresSellingPlan?: boolean;  // Indicates if a product must have a selling plan
  hasSellingPlanGroups?: boolean; // Indicates if a product has available selling plans
  sellingPlan?: SellingPlan;      // The currently applied selling plan
}

Version Requirements

⚠️ Critical Compatibility Note

To utilize these features, ensure you are using:

• POS UI Extension 2025-10 or later
• Shopify POS 10.13+

Attempting to use selling plan APIs or fields in older versions will result in blocked checkouts. Ensure your system is updated to avoid disruptions.

As of the Admin API version 2026-01, the callbackUrl argument in the fulfillmentServiceCreate and fulfillmentServiceUpdate mutations is now optional.

If your app's fulfillment services do not have a callback URL but have either inventoryManagement or trackingSupport enabled, they will need to submit the information required by these features via the API.

• For submitting tracking information and handling fulfillment requests, refer to our documentation on building for Fulfillment Services.
• For managing inventory quantities, see our documentation on managing Inventory Quantities and States.

How will this change affect my app?

This is a non-breaking change. If your app currently provides a callbackUrl, it will continue to function as before. You now have the option to create or update services without a callbackUrl.

What do I need to do?

No action is required for existing apps.

For new apps, you can omit the callbackUrl argument when creating or updating fulfillment services if your operations do not depend on these callbacks.

We have optimized the output of bulk operations in the GraphQL Admin API to enhance speed and reliability.

What's Changed

Bulk Queries (bulkOperationRunQuery)

The groupObjects argument now defaults to false. Grouping objects can slow down operations and increase failure rates, especially with large datasets.

Bulk Mutations (bulkOperationRunMutation)

The groupObjects argument is now deprecated. It does not affect the order of output files because mutation outputs do not have parent objects.

What You Need to Do

If You're Running Bulk Queries

• To maintain grouped output: Set groupObjects: true.

  mutation {
    bulkOperationRunQuery(
      query: """
      {
        products {
          edges {
            node {
              id
              title
            }
          }
        }
      }
      """
      groupObjects: true  // Add this to maintain grouped output
    ) {
      bulkOperation {
        id
        status
      }
      userErrors {
        field
        message
      }
    }
  }
  

If You're Running Bulk Mutations

Remove the groupObjects argument from your queries. This will not impact the output files.

Why We Made This Change

Most applications do not require grouped output and the associated overhead negatively impacts performance. These changes deliver faster, more predictable results that are easier to process at scale. Enable groupObjects only if your application specifically depends on the grouped output format. As this was the default behavior previously, you can verify on any version after 2025-07 by setting groupObjects to false and testing your application.

For optimal performance, omit groupObjects on or after 2026-01, and disable this option if you are on 2025-07 or 2025-10.

Learn More

• Bulk Operations Queries Guide
• Bulk Operations Imports Guide
• Working with JSONL Output

Add Shop Pay and Apple Pay checkout buttons to product and cart pages using Checkout Kit for Swift or React Native. Give customers the quick payment options they expect, with just a few lines of code.

Support for legacy mode profiles in shipping has been discontinued. This feature has been disabled for a while, and the the GraphQL Admin API is being updated to reflect this.

The following fields are being marked as deprecated:

• DeliveryProfile.legacyMode

The following fields are effectively deprecated, as they are no longer functional:

• DeliverySetting.legacyModeBlocked
• DeliverySetting.legacyModeProfiles
• DeliverySettingInput.legacyModeProfiles

Note: These three fields can't be marked as deprecated because that would leave their objects with zero public fields, which is known to cause problems for schema generation.

The corresponding queries that use these fields now return static data that users should ignore. Any mutations that pass these fields are now be no-ops.

In the API 2026-01 release candidate version, a new value, ON_FULFILLMENT, has been added to the SellingPlanRemainingBalanceChargeTrigger enum. This value allows you to set payments for pre-orders to be processed upon order fulfillment, providing flexibility in managing deferred payments.

For implementation details and further information, see the pre-orders documentation.

The Theme Store has simplified its categorization process by assigning only one industry tag per theme, effective immediately. As a result, all secondary industry tags have been automatically removed.

Your theme's primary industry tag now serves as its sole industry classification. Choose the industry that best matches:

• The main product types showcased in your demo store
• Your intended target merchant audience

This will make it easier for merchants to browse and find themes tailored to their specific industry needs.

You can review your current primary industry tag in the Partner Dashboard.

We've improved how subscription contracts handle shipping requirements to ensure accurate tax calculations, delivery details, and order totals. These changes apply when using the subscriptionBillingAttemptCreate mutation.

What's Changed

Shipping requirements use latest product information
Subscription contracts now dynamically retrieve the "requires shipping" value from the product variant for each contract line. Previously, a static value was stored when the subscription line was added to the contract. This update ensures that shipping requirements are always current when you update your product variants. This change also applies to SubscriptionDraft.fields.deliveryOptions.

Delivery lines added only when necessary
If no lines in a subscription contract require shipping, then we no longer add a delivery line to the order. This prevents unnecessary shipping charges and ensures correct tax calculations.

Impact

These changes ensure that:

• Taxes are calculated correctly based on current shipping requirements.
• Order totals reflect accurate delivery costs.
• Shipping configuration issues are caught before orders are processed.
• Subscription contracts stay in sync with your product catalog changes.

The Shopify.dev MCP server now supports code generation for a range of powerful APIs, enhancing your development experience:

• Storefront API
• Partner API
• Customer Account API
• Payment Apps API
• Polaris Web Components
• Liquid

This update allows you to leverage the Shopify.dev MCP as a virtual pair programmer within your preferred IDE. Generate code snippets, explore API capabilities, and accelerate your development process across the Shopify platform.

Get started:
To begin, configure the Shopify.dev MCP server to integrate it with your development environment and unlock these new capabilities.

We have introduced the fulfillmentOrdersReroute mutation to the Admin GraphQL API. This mutation allows you to move fulfillment orders to the next best location based on the shop’s delivery strategies. This update ensures that both the API and Admin offer the same capabilities, enhancing consistency and flexibility for developers.

With this mutation, you can optionally specify locations to exclude from the reroute. Alternatively, you can define a set of locations to consider for changing the fulfillment orders’ location.

mutation {
  fulfillmentOrdersReroute(
    fulfillmentOrderIds: ["gid://shopify/FulfillmentOrder/12345678"],
    excludedLocationIds: ["gid://shopify/Location/456789"]
  ) {
    movedFulfillmentOrders {
      # FulfillmentOrder fields
    }
    userErrors {
      field
      message
    }
  }
}

For further details on working with the new mutation, please refer to our documentation.

We're introducing important changes to simplify and enhance return management in the Shopify Admin API.

What's changing?

• The returnRefund mutation is deprecated and replaced by the new returnProcess mutation. The returnProcess mutation streamlines return lifecycle management by combining disposition decisions and financial processing into a single call.
• The field Return.suggestedReturnRefund is deprecated in favor of the new Return.suggestedFinancialOutcome field.
• Exchange fulfillment orders are now created only when exchange line items are processed, ensuring accuracy.
• Refunds and return processing now offer enhanced precision for managing returned line items.

Action required:
If your app currently creates returns using returnCreate or approves return requests using returnApproveRequest, migrate to the new returnProcess mutation to handle refunds and exchanges. The older mutations (refundCreate, returnRefund) and the query field (Return.suggestedRefund) are deprecated. Instead, you should now use returnProcess and Return.suggestedFinancialOutcome.

Availability:
These new APIs are available now in the unstable API version and officially launch in API version 2025-07.

For more details, see our updated migration guide.

Polaris web components are now generally available for extensions with version 2025-10. This unified toolkit now includes support for POS, Admin, Checkout, and Customer Accounts, and is always up-to-date through Shopify's CDN.

Since early access, we've added 14 new components for App Home, including a new modal experience. Additionally, there are 36 new components for Checkout and Customer Accounts, and a new Point of Sale surface with 31 components.

To get started, check out the developer documentation, or learn more about the library by reading our blog post.

We're adding a productNetwork Boolean field on the GraphQL Admin API's Order object in version 2025-10. This field indicates whether a customer also purchased items from other stores.

We have added metafield.reference and metafield.references to the Customer Account API. This means that reference Media types, including MediaImage, GenericFile, Model3d, and Video, now exist on the common query objects that currently support metafields on the Customer Account API.

Metaobjects can now also be queried through metafield.reference on the Customer Account API. To enable access to metaobjects, toggle the Customer Account API access toggle when editing a metaobject definition in Admin. After toggling this value on, metaobjects are exposed and accessible to apps with the customer_read_metaobjects scope.

This functionality can also be achieved with new changes to the GraphQL Admin API. We have exposed the ability to create, update, and query CustomerAccess, which can be set to either READ or NONE. You can specify the access on the MetaobjectAccess object when running the metaobjectDefinitionCreate or metaobjectDefinitionUpdate mutation.

Below are some example queries of Media types and metaobjects.

1. Querying a Media object metafield.reference (MediaImage) through customer:

	query {
		customer {
			metafield(namespace: "custom", key: "example") {
				namespace
				key
				jsonValue
				reference {
					__typename
					... on MediaImage {
						image {
							url
						}
					}
				}
			}
		}
	}

2. Querying a metaobject metafield.reference through an order (note, the metaobject contains a MediaImage reference):

	order(id: "gid://shopify/Order/1") {
		metafield(namespace: "custom", key: "example") {
			__typename
			namespace
			key
			reference {
				__typename
				... on Metaobject {
					id
					fields {
						type
						value
						key
						value
						reference {
							__typename
							... on MediaImage {
								id
								image {
									altText
									url
								}
							}
						}
					}
				}
			}
		}
	}

The productSet mutation mutation now uses dynamic complexity costing that more accurately reflects the actual computational cost of operations.

What's changing

Instead of a fixed cost of 50 points for all productSet operations, the mutation now calculates complexity based on the actual work being performed:

• Base cost: 10 points
• Per variant: 0.2 points
• Per variant file: 0.6 points
• Per variant metafield: 0.4 points
• Per product metafield: 0.4 points
• Per product file: 1.9 points

The total complexity is calculated as:

10 +
  (variants × 0.2) +
	(variant_files × 0.6) +
	(variant_metafields × 0.4) 
	(product_metafields × 0.4) 
	(product_files × 1.9)

Benefits for your apps

Lower costs for most operations: More than 99.5% of existing productSet operations will cost less than the previous fixed cost of 50 points. Simple product updates that previously cost 50 points now cost as little as 10-20 points.

Support for larger products: The mutation now supports products with up to 2,048 variants for merchants on all plans, a significant increase from the previous limit of 100 variants. This enables apps to manage more complex products and support merchants with diverse business needs.

Examples

Simple product update (1 variant, no files or metafields):

• Previous cost: 50 points
• New cost: 10 points (80% reduction)

Medium complexity (20 variants, 5 product metafields):

• Previous cost: 50 points
• New cost: 16 points (68% reduction)

Complex product (200 variants, 10 files, 20 metafields):

• Previous cost: 50 points
• New cost: 77 points (reflects actual resource usage)

Migration guidance

For most apps, no changes are required. Your existing productSet operations will automatically benefit from lower complexity costs.

For apps working with high-complexity products exceeding the 1000-point single query limit:

• Consider using bulk mutations for very large operations
• Split complex operations into separate calls: use productSet for core product data, then use metafieldsSet and fileCreate for additional data

Developers can now leverage ShopifyQL to extract valuable insights from all merchant analytics including sales, customer, and product data via the GraphQL Admin API. This enhancement allows for more sophisticated data analysis and reporting.

For a comprehensive guide on the ShopifyQL language, please visit the ShopifyQL syntax documentation.

The shopifyqlQuery field is now accessible on the QueryRoot of the GraphQL Admin API. To learn more about using this new query field, refer to our detailed documentation.

For example, here is a query that demonstrates how to retrieve total sales data, grouped by month, starting from the beginning of the current year:

{
   shopifyqlQuery(query: "FROM sales SHOW total_sales GROUP BY month SINCE startOfYear(0y) ORDER BY month") {
    tableData {
      columns {
        name
        dataType
        displayName
      }
      rows
    }
    parseErrors
  }
}

The response contains table data with column and row values, detailing the total sales per month.

{
  "data": {
    "shopifyqlQuery": {
      "tableData": {
        "columns": [
          {
            "name": "month",
            "dataType": "MONTH_TIMESTAMP",
            "displayName": "Month"
          },
          {
            "name": "total_sales",
            "dataType": "MONEY",
            "displayName": "Total sales"
          }
        ],
        "rows": [
          {
            "month": "2025-01-01",
            "total_sales": "5542.954"
          },
          {
            "month": "2025-02-01",
            "total_sales": "1610.094"
          }
        ]
      },
      "parseErrors": []
    }
  }
}

Any parsing errors encountered during execution will be listed under parseErrors.

Starting in version 2025-10, the GraphQL Admin API includes a themeDuplicate mutation to duplicate store themes. The mutation accepts a theme ID and an optional name parameter to rename the duplicated theme.

For further details, refer to the themeDuplicate reference documentation.

What's changing

The visibleToStorefrontApi field/input field is deprecated and removed from the unstable version of the GraphQL Admin API for the following types:

• MetaobjectFieldDefinition
• MetaobjectFieldDefinitionCreateInput
• MetaobjectFieldDefinitionUpdateInput
• StandardMetaobjectDefinitionFieldTemplate

Who's affected

• Anyone using visibleToStorefrontApi field or input field on a Metaobject field definition

NOTE: With the exception of StandardMetaobjectDefinitionFieldTemplate, this field was only ever exposed in unstable.

Why we're making this change

This field implies a system behaviour that doesn't exist. It isn't possible to toggle the storefront visibility of individual fields. The only storefront visibility controls are on the access fields of the metaobject definition itself.

Action required

If your app has a query or mutation that's referencing the visibleToStorefrontApi field on a Metaobject field definition, you need to remove that field.

Key dates

April 2, 2026: visibleToStorefrontApi field on metaobject field definitions will be removed from unstable and 2026-07

UNLISTED is available as a new product status value in the 2025-10 GraphQL Admin API and REST Admin APIs, as well as in the Webhooks API.

The Unlisted status hides products from store search and recommendations (including collections), all sales channels, internet searches and Shopify Catalog, while still allowing access via a direct URL. It will be returned in Storefront API and Liquid only when referenced individually by handle, id, or metafield reference.

Note: Previous versions of the Admin APIs will return product status for unlisted products as ACTIVE.

Learn more about this update in our developer documentation.

Starting from October 31 2025, when a customer updates their shipping address during a Draft Order checkout, product prices may change based on the shop's Markets configuration.

To prevent product pricing from changing in Draft Order checkouts, use the priceOverride or generatePriceOverride input field on the Draft Order line item input when creating or updating a Draft Order.

We're excited to introduce admin intents — a transformative API that enhances app interactions with Shopify's admin interface.

What are admin intents?

Admin intents offer a streamlined API designed to integrate effortlessly with:

• Embedded apps (App Home)
• Admin UI extensions

With just one API call, your app can now efficiently create or modify a wide range of Shopify core resources, including:

• Products
• Catalogs
• Collections
• Customers
• Markets
• Discounts
• And more!

Dive into the comprehensive documentation on admin intents to discover how to seamlessly incorporate this powerful API into your app development process.

As of October 2025, Shopify will introduce two new metafield definition types in the Admin GraphQL API, Storefront API, and Liquid. Metafields allow you to customize and store additional information about your Shopify resources, enhancing the flexibility of your online store.

The new metafield definition types are:

• article_reference: This type allows you to reference a specific article on your online store, making it easier to link content dynamically.
• list.article_reference: This type enables you to create a list of article references, providing a streamlined way to manage multiple content links.

To explore these new reference types further, visit the Shopify.dev documentation. For practical implementation, check out the examples provided.

These updates offer enhanced capabilities for managing content on your Shopify store, allowing for more dynamic and customized user experiences.

We have extended the grace period for Built for Shopify (BFS) apps that no longer meet specific automated criteria from immediate to 60 days. This extension applies to the following criteria:

• Uninstall cleanly using theme app extensions.
• Are embedded within the Shopify admin.

This change provides you with additional time to resolve any issues without immediately losing your BFS badge. During the 60-day grace period, your app will retain its BFS badge and remain visible to merchants. If the issues are not resolved within this timeframe, the BFS badge will be removed until the problems are addressed.

Starting October 9, 2025, products displayed on storefronts can originate from a "remote" source, such as another store. This is an opt-in feature available to a select group of eligible US-based merchants.

• There is no required action from theme developers to support this change, however some app integrations might be affected and therefore we have highlighted some recommendations below.
• In collections and search results, remote products will display small badges on their images to indicate their remote origin.
• In the cart, remote product titles will include a reference to the seller.
• Products with a remote_details.type of seller will automatically use the Seller product template.

Recommended updates

The following updates are recommended.

Seller products

You can include a Seller product template in your theme using the naming convention product.remote.seller.json. Refer to the related documentation for best practices when designing this template. If a Seller product template is not available, merchants will be prompted to create one; otherwise, the default template will be used as a fallback.

Cart

To enhance your theme's compatibility with apps that utilize Shopify Function inputs for cart-related functionality, we recommend visually distinguishing remote products from regular products in the cart. Remote products are not included in Shopify Function inputs, and Shopify Function operations cannot target them. Consequently, apps using Shopify Functions for features like cart validation and discounts will not consider remote products in their calculations. This may lead to discrepancies between the cart totals and the calculations returned by these apps.

For example, if an app calculates free shipping for totals above $50, and a customer has $55 worth of merchandise in their cart, with $20 from a remote product, the Functions will only recognize $35 worth of merchandise. As a result, the customer will see that the free shipping threshold has not been met.

To identify and visually group remote products in the cart, use the remote_details on the product:

<h2>Sold by {{ shop.name }}</h2>
{% for item in cart.items %}
  {% unless item.product.remote_details %}
    <!-- Items without remote details -->
  {% endunless %}
{% endfor %}

<h2>Sold by other stores</h2>
{% for item in cart.items %}
  {% if item.product.remote_details %}
    <!-- Items with remote details -->
  {% endif %}
{% endfor %}

Related Documentation

Refer to the following documentation for additional information.

• Liquid remote_product object
• Seller product template
• Remote products in cart
• Remote products in collections
• Remote products in search
• Cart AJAX API - example of a cart with remote products

Starting October 9, 2025, products displayed on storefronts may originate from a "remote" source, such as another store. This feature is optional and available to a select group of eligible US-based stores.

Recommended Updates

• If your app uses the Cart Ajax API to determine free shipping qualifications or apply cart discounts, ensure that remote products are excluded from these calculations. Remote products have separate shipping arrangements from their origin stores, and discounts should apply only to products owned by the store.

• For apps utilizing the Cart Ajax API for features like abandoned cart recovery, exclude remote products. The URLs for remote products will expire after a certain period, making recovery attempts unreliable.

• For other use cases involving the Cart Ajax API, evaluate whether your logic should exclude remote products.

• Note that remote products are not included in Shopify Function inputs, and Shopify Function operations cannot target remote products.

• For apps that calculate free shipping thresholds or loyalty points, exclude remote products from your calculations.

• For apps that display product page widgets like wishlists, coupon prompts, or store points earning, check if a product is remote and hide these UI elements.

Identifying Remote Products

In the Cart Ajax API response, remote products can be identified by the presence of the attribute remote: true on cart line items.

Remote products can be distinguished from native products in Liquid by checking if product.remote_details is present.

Remote products do not yet appear in Storefront API responses. Support for identifying these products is coming soon.

The productVariantsBulkCreate and productVariantsBulkUpdate mutations now use dynamic complexity costing to more accurately reflect the actual computational cost of operations.

Support for more complex products

The mutations now support products with up to 2,048 variants for merchants on all plans, a significant increase from the previous limit of 100 variants. This enables apps to manage more complex products, and support merchants with diverse business needs.

What's changing

With the release of Dynamic Complexity, the productVariantsBulkCreate and productVariantsBulkUpdate mutations will now have a base cost of 10-points, and additional points will be calcuated based on the complexity of the input.

• Base cost: 10 points
• Per variant: 0.2 points
• Per variant media: 0.6 points
• Per variant metafield: 0.4 points
• Per product media: 1.9 points

The total complexity is calculated as:

10 +
  (variants × 0.2) +
  (variant_media × 0.6) +
  (variant_metafields × 0.4) +
  (product_media × 1.9)

Migration guidance

For most apps, no changes are required.

For apps working with high-complexity products exceeding the 1000-point single query limit:

• Consider using bulk mutations for very large operations.
• Split complex operations into separate calls: use the productVariantsBulkCreate and productVariantsBulkUpdate mutations for core variant data, then use metafieldsSet and fileCreate for additional data.

What's changing?

The productVariantsBulkCreate and productVariantsBulkUpdate mutations now enforce validation limits on inventory quantities as part of supporting the increased variant limit from 100 to 2048 variants per product.

Input Validation Limits

With the increase in maximum variants per product from 100 to 2048, the mutation now enforces a maximum limit of 50,000 inventory quantities across all variants in a single mutation. This ensures reliable performance when managing products with many variants across multiple locations.

Error response example

{
  "data": {
    "productVariantsBulkCreate": {
      "userErrors": [{
        "code": "INVENTORY_QUANTITIES_LIMIT_EXCEEDED",
        "field": ["variants"],
        "message": "Input contains 51200 inventory quantities, which exceeds the limit of 50000"
      }],
      "product": null
    }
  }
}

Why are we making this change?

Support for 2048 Variants

• Increased variant limit: Products can now have up to 2048 variants (previously 100)
• Reliable execution: Ensures consistent performance when managing complex products

Handling Large Inventory Updates

If you hit the 50,000 inventory quantity limit, you have several options:

1. Batch your operations: Split large operations into multiple smaller mutations
2. Use inventorySetQuantities: For updating inventory across many locations, use the inventorySetQuantities
3. Use bulk mutations: For very large datasets, consider using bulk mutation operations

Related Changes

• These changes are part of supporting the increased limit of 2048 variants per product. This validation complements the dynamic complexity calculation, providing both cost optimization and input validation for the productSet mutation to handle complex products efficiently.

• The productSet mutation now enforces inventoryQuantities limits as well.

We've introduced a new DisputeStatus value, prevented, and updated the descriptions of all dispute statuses for clarity and consistency.

What Changed

You can now receive a prevented status on disputes in the Admin API (both GraphQL and REST) and in any webhooks or payloads that include dispute status. We have refreshed the descriptions of all dispute statuses to better reflect real-world outcomes and processor terminology.

Who This Is For

• App developers and partners who read, store, or display dispute statuses.
• Payment and operations tools that report on dispute outcomes.
• Agencies building custom workflows around dispute lifecycle events.

Why It Matters

• Distinguish cases where a chargeback was stopped upstream (e.g., via Visa Rapid Dispute Resolution) from other outcomes.
• Update your UI and reporting to reflect that merchants won’t incur a chargeback fee for prevented disputes.
• Gain clearer, more actionable status definitions across the dispute lifecycle.

How It Works

Processors may send a prevented status when a chargeback is stopped before it’s filed. Currently, Stripe may send prevented for Visa transactions covered by RDR when the merchant is enrolled through a third party.

Shopify doesn’t enroll merchants into dispute prevention services. However, if a merchant is enrolled via a third party and the processor sends prevented, you’ll see it in the Shopify admin.

Availability

• Available now in the Admin API (GraphQL and REST) and in payloads that include dispute status.
• This is a non-breaking change; no version pinning is required.

What You Should Do

• Review any strict enum handling (switches, validations, database constraints) to ensure prevented is accepted.
• Update UI copy, translations, and filters to surface prevented distinctly from open, won, or lost states.
• Check analytics and reporting pipelines that group outcomes or calculate fees to ensure prevented is categorized correctly.
• Verify that any webhook or event processing that reacts to dispute status changes handles prevented gracefully.

Limitations and Notes

• You’ll only see prevented when your payment processor supplies it; availability varies by processor and merchant enrollment.
• Prevented indicates the dispute didn’t proceed to a chargeback, and merchants won’t be charged a chargeback fee.

Documentation

For more information, please see the following resources:

• Admin GraphQL DisputeStatus enum
• Admin GraphQL Dispute object
• Admin REST disputes

Breaking Changes

None

The productCreate and productUpdate mutations now use dynamic complexity costing to more accurately reflect the actual computational cost of operations.

What's changing

With the release of Dynamic Complexity, the productCreate and productUpdate mutations will now have a base cost of 10-points, and additional points will be calcuated based on the complexity of the input.

• Base cost: 10 points
• Per product metafield: 0.4 points
• Per product media: 1.9 points

The total complexity is calculated as:

10 +
  (product_metafields × 0.4) +
  (product_media × 1.9)

Migration guidance

For most apps, no changes are required.

For apps working with high-complexity products exceeding the 1000-point single query limit:

• Consider using bulk mutations for very large operations.
• Split complex operations into separate calls: use the productCreate and productUpdate mutations for core product data, then use metafieldsSet and fileCreate for additional data.

You can now access more detailed balance information and payment status updates for payment schedules using deferred payments.

We've introduced three new fields to the PaymentSchedule object:

• balanceDue: The remaining balance that needs to be captured for this payment schedule.
• totalBalance: The total balance that the customer needs to pay or authorize for this payment schedule.
• due: Indicates whether the payment schedule is currently due (boolean).

These fields enhance your ability to monitor payment statuses when developing apps for merchants utilizing payment terms and deferred payment options. With these updates, you can easily differentiate between captured and uncaptured balances and quickly identify which payment schedules require immediate action.

Please note that the existing amount field is now deprecated. We recommend using these new fields for more specific information, or you can refer to Order.totalOutstandingSet for order-level balance details.

App discovery and recommendations are now part of Sidekick, allowing merchants to find, compare, and install apps in chat. Sidekick uses App Store listing content to render standardized app cards, reducing steps to install.

Key features:

• Up to three relevant app cards for broad queries
• A single highlighted app card for strongly-matched apps
• App‑to‑app comparisons highlight key differences and Built for Shopify status
• Install directly from Sidekick

Guided search and comparisons in the App Store will soon retire.

To optimize your app's visibility in Sidekick, enable Shopify-managed installation to streamline your install experience. Also, check your App Store listing for accuracy, clarity, and structure. Achieving the Built for Shopify badge improves search ranking in both the App Store and Sidekick.

What's changing?

The productSet mutations now enforces validation limits on inventory quantities as part of supporting the increased variant limit from 100 to 2048 variants per product.

Input Validation Limits

With the increase in maximum variants per product from 100 to 2048, the mutation now enforces a maximum limit of 50,000 inventory quantities across all variants in a single mutation. This ensures reliable performance when managing products with many variants across multiple locations.

Error response example

{
  "data": {
    "productSet": {
      "userErrors": [{
        "code": "INVENTORY_QUANTITIES_LIMIT_EXCEEDED",
        "field": ["input", "variants"],
        "message": "Input contains 51200 inventory quantities, which exceeds the limit of 50000"
      }],
      "product": null
    }
  }
}

Why are we making this change?

Support for 2048 Variants

• Increased variant limit: Products can now have up to 2048 variants (previously 100)
• Reliable execution: Ensures consistent performance when managing complex products

Handling Large Inventory Updates

If you hit the 50,000 inventory quantity limit, you have several options:

1. Batch your operations: Split large operations into multiple smaller mutations
2. Use inventorySetQuantities: For updating inventory across many locations, use the inventorySetQuantities
3. Use bulk mutations: For very large datasets, consider using bulk mutation operations

Related Changes

• These changes are part of supporting the increased limit of 2048 variants per product. This validation complements the dynamic complexity calculation, providing both cost optimization and input validation for the productSet mutation to handle complex products efficiently.

• The productVariantsBulkCreate and productVariantsBulkUpdate mutations now enforce inventoryQuantities limits as well.

The customerPaymentMethodRemoteCreate mutation in the Admin API now includes rate limiting to manage excessive API requests and maintain consistent performance for all merchants. This change helps ensure that no single user can overwhelm the system, thereby providing a more reliable experience for everyone.

For Facebook orders created as of August 26, 2025, you can now add exchangeLineItems as an input in the returnCreate mutation as you do for other orders, eliminating the need for workarounds when handling exchanges for Facebook orders.

Additionally, Facebook orders also support return fees as of the same date. This change applies to all supported GraphQL API versions.

Exchanges and return fees remain unavailable for Facebook orders placed before this date.

What's new

As of 2025-10, metaobject fields can now be made searchable and filterable in the Shopify admin through the new admin_filterable capability, bringing metaobject fields in line with the existing capability framework used by metafield definitions and enabling merchants to filter metaobject lists by field values and create saved views based on field criteria.

Implementation

1. Creating or updating field definitions: When creating or updating metaobject field definitions through the Admin GraphQL API, you can now specify capabilities:

mutation {
  metaobjectDefinitionCreate(definition: {
    name: "Product Metadata"
    type: "product_metadata"
    fieldDefinitions: [
      {
        key: "brand"
        name: "Brand"
        type: "single_line_text_field"
        capabilities: {
          adminFilterable: {
            enabled: true
          }
        }
      }
    ]
  }) {
    metaobjectDefinition {
      id
      fieldDefinitions {
        key
        capabilities {
          adminFilterable {
            enabled
          }
        }
      }
    }
  }
}

2. Querying capability status: When querying metaobject fields, check the status of the admin_filterable capability:

query {
  metaobjectDefinition(id: "gid://shopify/MetaobjectDefinition/123") {
    fieldDefinitions {
      key
      name
      capabilities {
        adminFilterable {
          enabled
        }
      }
    }
  }
}

We are removing the Shop.draftOrders connection, which has already been deprecated for some time. This change is part of our ongoing efforts to streamline and improve the API's efficiency and functionality.

What You Need to Do

To ensure your integrations continue to function smoothly, please update your applications to use the QueryRoot.draftOrders object for retrieving multiple draft orders. If you have any questions or need assistance, please refer to our developer documentation or reach out to our support team.

Checkout Kit’s preloading feature is not compatible with the upcoming release of iOS 26. This incompatibility will prevent buyers from completing their checkout process within the app. If no action is taken, customers using devices with iOS 26 will encounter blank checkout pages and will be unable to finalize their purchases.

To prevent this issue, promptly update your apps to the latest versions of Checkout Kit. Use the following versions: Swift 3.3.1, Kotlin 3.5.1, and React Native 3.3.1.

For more information, learn more about Shopify's Checkout Kit.

As of the 2025-10 API version, we’re introducing support for user-defined handles as the identifier for Shopify Functions in GraphQL mutations. Instead of passing a globally unique functionId in mutations that create or manage function owners, you can pass a stable, app-scoped handle that you define in your shopify.extension.toml. All GraphQL mutations that currently accept functionId will accept functionHandle.

Note: You must provide either 'functionId' or 'functionHandle' for each call, not both. Providing both will result in a user error.

What this does for you

Function IDs change with each deployment to a different environment. This forces developers to query for the latest ID before they can create or update a function owner. Handles are stable across environments and scoped to your app, removing the need to query shopifyFunction before creating the function owner.

No developer action required

These changes will not break your existing integrations. functionId will continue to work. However, we recommend you update your code to use functionHandle instead:

• Remove code that queries for functionId at runtime.
• Use the functionHandle you define in shopify.extension.toml directly in GraphQL mutations.

Formal deprecation and removal timelines for functionId will be announced separately.

Example Usage

1. Obtain functionHandle from the function's shopify.extension.toml:

   [[extensions]]
   name = "Payment Customization Function"
   handle = "YOUR_FUNCTION_HANDLE" 
     type = "function"
   

2. Create the payment customization using functionHandle

   mutation {
     paymentCustomizationCreate(paymentCustomization: {
       title: "Payment Customization Title",
       enabled: true,
       functionHandle: "YOUR_FUNCTION_HANDLE",
     }) {
       paymentCustomization {
         id
       }
       userErrors {
         message
       }
     }
   }
   

As of version 2025-10, you can use the GraphQL Storefront API to add gift cards to a cart without replacing gift cards that have already been applied.

After a cart has been created, perform the cartGiftCardCodesAdd mutation to add one or more gift cards to the cart.

As of GraphQL Admin API version 2025-10, ShopifyPaymentsPayoutSummary now includes a usdcRebateCreditAmount field, which provides a total of all USDC rebate credits issued as part of the payout.

For more information about ShopifyPaymentsPayoutSummary, visit the Shopify.dev documentation.

As of 2025-10, The countryCode field in CountryHarmonizedSystemCodeInput is now nullable. When set to null, the HS code (harmonized system code) entry represents a global HS code rather than a country-specific one.

Why this matters Many merchants work with global HS codes (typically 6-digit codes) that apply universally across countries before being extended with country-specific digits. This enhancement allows you to:

• Store global HS codes without requiring a specific country context
• Reduce redundancy when the same base HS code applies across multiple countries
• Better align with international trade practices where global codes serve as the foundation

Migration No action required. This is a non-breaking change:

• Existing implementations that provide countryCode will continue to work unchanged
• You can now optionally pass null for countryCode to create global HS code entries

Related resources

• [Add HS codes and the country or region of origin to your products]https://help.shopify.com/en/manual/international/duties-and-import-taxes/charging-duties#add-hs-codes)
• International Trade Documentation

As of version 2025-10, we are introducing a new value to the FulfillmentEventStatus enum, to enhance your fulfillment tracking capabilities:

• CARRIER_PICKED_UP: This status indicates that the carrier has successfully collected the fulfillment.

With this update, you can now track when a shipment has been picked up by the carrier. For more details, please refer to the updated Shopify API documentation.

Order metafield definitions and values can now be used as filters in the Shopify Admin UI, enhancing the functionality of the order index. This update enables merchants and developers to efficiently manage and organize orders based on specific metafield criteria, streamlining order processing and improving operational efficiency.

Additionally, you can now query order metafield definitions through the Admin GraphQL API using the metafieldDefinitions query. This feature allows for more precise data retrieval and manipulation, giving developers greater control over order data.

Since orders are already a supported metafield owner type, this change empowers apps and merchants to manage order-level metafield definitions more efficiently. By leveraging these enhancements, users can optimize their workflows and improve the overall management of order-related data.

As of 2025-10, StoreCreditAccount also support CompanyLocation as owners, enabling location-specific credit management for B2B merchants on the Admin API.

B2B customers authenticated with new customer accounts can view and spend store credit at checkout for company locations they have permission to place orders for.

The Customer Account API now returns the company location's StoreCreditAccount for authenticated B2B customers.

We've updated Polaris with eight new unified components now available for Shopify Admin:

• ColorField
• ColorPicker
• Popover
• Tooltip
• Menu
• Chip
• ClickableChip
• DropZone

They are already available to you via Shopify's CDN. To get started with these new components, check out the developer documentation.

We are excited to announce the release of support for building announcement bar extensions on the Thank You page and Customer Account pages, including the Order Status page, Order Index page, and Profile page. The announcement bar is a new UI-extension form factor that uses prominent placement, animation, and colors to capture buyers' attention. With this feature, you can create extensions that highlight a merchant's most important tasks on the page, such as surveys, reviews, and upsells.

You can start building an announcement bar extension now using the 2025-07 version of the Checkout and Customer Accounts UI extension APIs.

For more information on building an announcement bar extension, visit the Shopify developer documentation.

What’s new for you:

• Create developer stores with any plan: Easily create dev stores on any Shopify plan, including Plus, to align with your target environments.
• Build and test without deploying: Instantly iterate on your app using the new app dev preview. Deploy only when you're ready.
• Manage metaobject definitions in code: Directly define and update your app’s custom data in your TOML files, eliminating the need to manage state via APIs.
• Streamline your workflow: Organize, monitor, and manage your apps in one centralized Dev Dashboard.

What’s changing:

We're transitioning all apps and dev stores from the Partner Dashboard to the new Dev Dashboard. Your current installations will continue to function, but management will now occur on the new platform.

Shopify will migrate your partner org's apps over the next week. If the migrated apps have extensions, you'll need to run shopify app deploy in order for their extensions to be updated.

If you use dashboard-managed extensions, migrate them to the CLI or remove them, as they won't function on the new platform. Post-migration, you can deploy and manage app versions via the CLI or Dev Dashboard.

Why this matters:

This update provides a faster feedback loop, greater control over your data models, and a unified platform for app management. The new platform is designed to support modern app development at scale, allowing you to focus on creating exceptional merchant experiences.

Next steps:

• Explore the documentation for detailed information on the new workflow.
• Review and update your extensions as necessary.
• Make sure you're on the latest version of Shopify CLI (3.84.1 or newer)

If you have questions or need assistance with migration, refer to the documentation or engage with the developer forums.

The @inContext directive now includes a visitorConsent parameter, allowing developers to pass buyer consent preferences—such as analytics, preferences, marketing, and sale of data—to cart operations. This consent information is automatically encoded into the resulting checkoutUrl, ensuring privacy compliance throughout the checkout process.

This enhancement allows developers using Checkout Kit and other integrations to seamlessly collect and transmit buyer consent, thereby supporting privacy regulations and maintaining a smooth checkout experience.

Key features:

• Optional consent fields for analytics, preferences, marketing, and sale of data
• Automatic encoding of consent into checkout URL via the _cs parameter
• Compatibility with existing cart mutations and queries

Learn more about the @inContext directive and visitor consent →

As of GraphQL API version 2025-10, we have introduced a new value, PRESERVE_STANDALONE_VARIANT, to the ProductVariantsBulkCreateStrategy. This value can be used as an optional argument in the productVariantsBulkCreate mutation.

The PRESERVE_STANDALONE_VARIANT strategy ensures that any existing standalone variant, whether default or custom, is retained when executing the productVariantsBulkCreate mutation.

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

The Shopify Dev MCP server can now search for Liquid docs, and validate Liquid to catch common errors before deployment:

• Liquid Documentation: Your AI assistant can now search the complete Liquid API reference, which includes all objects, filters, and tags.
• Code Validation: The built-in theme-check integration identifies syntax errors and best practice violations in your generated code, helping you maintain high-quality standards.

If you're already using the Shopify Dev MCP server, Liquid support is automatically included in the latest version.

View the Shopify Dev MCP server documentation or explore the source code on GitHub for more details.

Enhanced Delivery Profile Webhooks Now Include Additional Payload Fields

We've improved the profiles/update webhook by adding more comprehensive payload information. This enhancement significantly increases webhook reliability and reduces unnecessary debouncing.

What's New

Previously, profiles/update webhooks only included the profile ID in their payload. This minimal payload led to an issue where multiple rapid updates to the same delivery profile were debounced by our webhook delivery system, meaning only the first update within a 15-minute window would reach your app.

Now, when you subscribe to profiles/update webhooks, you'll receive these additional fields:

• name: The profile's display name
• default: Indicates if this is the default delivery profile
• profile_type: The type of delivery profile
• version: An integer that gets incrementned whenever the profile or its shipping rates are modified

Why This Matters

If your app responds to delivery profile changes—such as for shipping rate synchronization, fulfillment optimization, or carrier integrations—you can now reliably receive every update. This is especially useful when merchants make quick successive changes to their shipping configurations, such as:

• Adjusting weight-based rate conditions
• Modifying zone configurations
• Updating multiple shipping rates in sequence

The new version field acts as a fingerprint of the profile's current state. It increments whenever the profile or its associated shipping rates are modified, ensuring each webhook has a unique payload that won't be debounced.

Using the Enhanced Payload

The enhanced payload structure is as follows:

{
  "id": 123456789,
  "name": "Standard Shipping",
  "default": false,
  "profile_type": "shipping",
  "version": "1"
}

This enhancement is available now in API version unstable and will be included in the next stable API release.

The checkout_and_accounts_configurations/update webhook, originally introduced in API version 2025-04 to help track updates to checkout and accounts configurations, will be removed on January 1, 2026.

Action required:

Apps still subscribed to the checkout_and_accounts_configurations/update webhook should unsubscribe before the removal date.

For tracking Thank You and Order status page upgrades, we recommend using the Admin API checkoutProfiles query, which includes the typOspPagesActive boolean field to access the same information. This change simplifies the developer experience based on community feedback.

Learn more about working with checkout profiles in the Shopify developer documentation.

New fields have been introduced to enable parent-child (nested) relationships between cart lines, supporting use cases such as warranties, engravings, and gift-wrapping.

• Nested cart lines are now supported in the Cart AJAX API, and as of version 2025-10, in Storefront API and Checkout UI Extensions.

• Nested (child) lines reference their parent using a dedicated parent field: Use parentId or parent_line_key (Cart AJAX API), parentID (Checkout UI Extensions), parent.lineId or parent.merchandiseId (Storefront API).

To learn more about the impacted APIs and fields, click here.

As of GraphQL Admin API version 2025-10, ShopifyPaymentsPayout now includes externalTraceId field

The externalTraceId field provides a unique reference identifier for tracking payouts across external payment systems and financial institutions.

For more information about ShopifyPaymentsPayout, visit the Shopify.dev documentation.

As part of our ongoing move towards open source fonts, we're implementing a gradual automatic font replacement. All deprecated fonts used in online store themes, checkout, and the Shopify Forms app will be automatically replaced with fonts of a similar style.

This automatic replacement will happen gradually throughout August 2025. Merchants using deprecated fonts will see their stores updated with replacement fonts that maintain similar visual characteristics to their original selections.

If you're building themes for the Theme Store, you should have already updated your theme presets by the January 3, 2025 deadline. If you haven't yet, review our deprecated fonts list and update any affected presets with our recommended replacements or any other available font of your choice.

Shopify partners can now export search term performance data with detailed targeting breakdowns for multiple ad campaigns simultaneously. Previously, this granular data was only available for one campaign at a time.

With the new export option, you can view search term performance across multiple ad campaigns, categorized by:

• Country/region
• Device type
• Shop plan

To use this feature, go to the ad campaigns overview page. Select the ad campaigns you want to analyze, then click Actions and choose Export. Select the new option labeled "Performance by search terms, categorized by country/region, shop plan, and device type." This will download comprehensive data for your selected ad campaigns.

For more information, visit the Shopify Developer Documentation.

The orders query argument now supports the current_total_price (documentation) and total_weight (documentation) filters. Additionally, we've introduced the ability to use sortKey with CURRENT_TOTAL_PRICE (documentation).

As of July 28, 2025, "Sell only within configured shipping zones" has been enabled on nearly all shops at checkout. This change ensures that customers can only purchase products that are available at fulfillment locations configured to deliver to their shipping zone. This setting will continue to be removed up until September 30, 2025.

"Sell from all locations to all shipping zones" remains an option to control storefront behaviour for merchants who have not previously enabled the "Sell only within configured shipping zones" option.

This update helps prevent overselling and reduces issues such as canceled orders due to regional stock unavailability or the need for manual order corrections.

Developers should note that apps using Shopify APIs to manage recurring subscription orders might encounter an increase in errors that occur when products are unavailable at fulfillment locations that ship to the customer. Additionally, apps managing shipping settings or inventory should ensure that inventory is in stock at locations with valid delivery methods in order to be available for purchase.

See the help documentation to learn more about fulfillable inventory.

As of Admin GraphQL API version 2025-10, we are deprecating the taxCode field from the ProductVariant object. This change is part of the Avalara AvaTax app deprecation and will affect how you handle tax classification for product variants.

The taxCode field on ProductVariant objects will not be available in future API versions. If your app currently relies on this field for tax calculations or reporting, you must update your implementation before the field is fully removed.

Why We're Making This Change

We are deprecating the taxCode field because the Avalara AvaTax app, which powered this functionality, is being discontinued. This field applies only to the stores that have the Avalara AvaTax app installed.

What You Need to Do

If your app uses the taxCode field, you should:

1. Audit Your Current Implementation: Identify where your app reads or writes the taxCode field.
2. Update Your GraphQL Queries: Remove references to the taxCode field from your queries and mutations.
3. Test Thoroughly: Ensure your app continues to function correctly without the deprecated field.

Timeline

The taxCode field will continue to return data through API version 2025-10. However, you should migrate away from it as soon as possible, as future API versions will not include this field.

Learn More

For more information on the deprecation of the Avalara AvaTax app, refer to the documentation on migrating from AvaTax.

For guidance on using the new Avalara Tax Compliance app, refer to the documentation on mapping Avalara tax codes in Shopify.

We've released new guidelines and updated documentation for the referenceDocumentUri field in inventory adjustment mutations. By following these guidelines, your apps can maintain inventory traceability, which helps merchants troubleshoot issues and conduct audits more easily. Access the field in admin via the "Inventory adjustment changes" report in Analytics or on the Adjustment History Page.

What’s new:

• Detailed guidelines for using the referenceDocumentUri field to link each inventory adjustment to its source system and document.
• Recommendations for adopting the Global ID (GID) format (gid://namespace/entity/id) to maintain consistency across integrations.
• Support for various URI formats, including URLs and custom schemes, ensuring backward compatibility.
• Best practices for defining namespaces and entity types.
• Code examples for Warehouse Management Systems (WMS), Third-Party Logistics (3PL), Point of Sale (POS), and Enterprise Resource Planning (ERP) integrations.
• Migration guides for updating existing implementations.
• Validation rules and format specifications.

These updates enable you to:

• Provide merchants with comprehensive audit trails for compliance.
• Display your app’s name in Shopify admin inventory history.
• Trace inventory changes back to their origin, simplifying troubleshooting.

To implement, you'll incorporate the referenceDocumentUri field into the inventoryAdjustQuantities mutation.

Explore the updated guidelines and documentation

As of version 2025-10 of the GraphQL Storefront API, you can replace all delivery addresses that are present on a cart in a single operation.

The new cartDeliveryAddressesReplace mutation accepts an addresses field for specifying the list of delivery addresses to replace.

You can now apply discounts to line items that have already been fulfilled using the order editing API, resulting in more flexible order adjustments. The orderEditAddLineItemDiscount mutation now supports discount application to both fulfilled and unfulfilled line items.

What this means for you:

• Clearer transaction history: Discounts on fulfilled items improve post-purchase financial attribution and reporting.
• Simplified order management:Orders automatically unarchive when you begin editing and re-archive after issuing refunds, eliminating the need for manual archive management.

What's changing?

Starting on January 1st, 2026 Shopify will no longer set the following cookies on merchant storefronts:

• _shopify_s
• _shopify_y

Required updates

While accessing internal cookie values is never recommended as they frequently change, any code that currently accesses the cookie values will need to be adapted to use documented APIs.

_shopify_y

If you're accessing this value via document.cookie you'll have to use Web Pixels and particularly the clientID property of any Standard or DOM event (See API reference).

This example shows a Custom Pixel, but this would work with a Web Pixel App Extension as well.

• Go to Admin > Settings > Customer Events > Custom Pixels
• The following JavaScript within a web pixel would log the ID formerly known as _shopify_y on every page view, assuming proper user consent is given:

analytics.subscribe('page_viewed', (event) => {
  console.log("The client's ID is ", event.clientId);
});

_shopify_s

Shopify will not offer a replacement value. However, as part of the browser APIs (or Web Pixels API’s browser interface) it is possible to create a session-length cookie, which is equivalent functionality.

When a Hydrogen branch is deployed, its new preview URL is automatically added to the application setup for the Customer Account API. This ensures that OAuth redirects, logouts, and JavaScript-origin checks continue to function seamlessly across deployments without requiring manual updates to settings. While these auto-added URLs are hidden from the settings page, any URIs added directly in the Admin remain visible and editable.

Starting with API version 2025-10 of the GraphQL Storefront API, we have introduced the SELLING_PLAN_NOT_APPLICABLE_ON_COMPANY_LOCATION warning code to the CartWarningCode enum. This warning code is triggered when a logged in B2B customer creates a cart with a selling plan or adds a merchandise item with a selling plan to their cart.

We have added support for the Meta Pixel Conversions API, enabling server-side tracking of app installations. This API allows developers to track Purchase events when merchants install their apps, enhancing attribution accuracy for Facebook advertising campaigns.

To take advantage of this feature, Partners can now add their Facebook Pixel tracking ID to their app's Distribution settings.

Starting from version 2025-07, Customer Account UI extensions will have the capability to access the analytics object from the Standard API. This enhancement allows you to publish custom events to Shopify Web Pixels directly from your extensions, enabling percise tracking of customer interactions with your extension.

Note: To ensure your extension is up to date, please consider updating @shopify/ui-extensions and @shopify/ui-extensions-react to the most recent stable version, 2025.7.1 or later

Read more about how to implement the analytics API in customer accounts.

You can now deploy payments app extensions instantly without waiting for manual review from Shopify. We've replaced our manual configuration review process with automated validation that gives you immediate feedback directly in your CLI.

What this means for you:

• Deploy immediately: No more waiting for approval—push your payments app extension updates to merchants as soon as they're ready
• Catch issues faster: Get instant feedback on configuration problems during submission, so you can fix them before deployment
• Stay compliant automatically: We'll validate that your extension supports test mode, uses stable API versions, and includes payments methods that match your extension type

How it works: When you submit through Shopify CLI, your TOML configuration is automatically evaluated and you'll get immediate feedback on any issues. The deployment process remains the same—just without the manual review step.

We've closed the Flex sections developer preview as of July 14th. This preview included theme blocks and style settings.

Theme blocks are now available to all theme developers. You can start using theme blocks immediately to create reusable modules for structuring content within sections. Learn more about theme blocks in our documentation.

Style settings are no longer supported as we plan to explore different approaches in the future. You can remove any references to style settings from your development stores.

Our review system continues to evolve to prioritize relevant and trusted reviews.

• Reviews are archived if they’re left by stores that are on a trial or discounted plan, or that are no longer active.
• Archived reviews are automatically re-published once the store has paid for a full priced plan or reactivates.
• Developers will receive an email notification for each new review, indicating if it is published or archived.

Learn more about archiving and unpublishing criteria in our help docs.

As of API version 2025-10, apps with read_customer_payment_methods scope can query the new mandate connection on the CustomerPaymentMethod object.

This connection returns what each payment method is authorized for (orders, subscriptions, checkout, etc.) via the resourceType field and the resourceId when applicable.

EFFECTIVE Wednesday, July 16, 2025 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 ensuring the continued reliability and performance of our platform and its offerings.

These changes come into effect as of today, July 16 2025. Updates to Revenue Share are effective January 1, 2025.

Continued use of Shopify services on or after Wednesday, July 16, 2025 confirms that you’ve read, understood, and accepted these new terms.

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

Web pixels now automatically load on Customer Account and Order Status pages, enabling you to track the entire customer journey from discovery to order management.

• Shops must use a custom domain (e.g., accounts.your-store.com) for customer accounts.
• The page_viewed events and the Advanced DOM API are supported.
• You can publish custom events through a UI extension.

You can now access inventory shipment timestamps through the Admin GraphQL API. You can now use the dateCreated, dateReceived, and dateShipped fields within the InventoryShipment type. Additionally, you can set timestamp values using the following mutations:

• inventoryShipmentCreate: Includes dateCreated in the input to specify the creation date of the shipment.
• inventoryShipmentMarkInTransit: Accepts dateShipped as an argument to indicate when the shipment was dispatched.
• inventoryShipmentReceive: Uses dateReceived as an argument to denote when the shipment was initially received.

All the above timestamp fields return dates in UTC format. They are currently accessible via the unstable version of the API and will be available in the stable admin GraphQL API version 2025-10.

We’ve rolled out several updates to the Shopify Theme Store that help merchants find the right theme faster—while giving your themes more visibility:

Dedicated theme cards and listing pages for theme presets Each preset now has its own theme card and listing page, providing greater opportunity to merchandise themes to specific industries and catalog sizes.

Embedded demo store experience on the theme listing page The demo store now loads directly on the theme listing page, so merchants can explore without navigating away.

Updated industry and catalog size filters Theme Store filters have been updated to make it easier for merchants to get more granular in their search.

These changes aim to improve theme discoverability and help connect merchants with the themes that best fit their needs.

Explore these changes on the Shopify Theme Store

What's changing?

Starting on August 18th, 2025, Shopify will no longer set the _ab cookie on merchant storefronts or checkout. This cookie was used to enable/disable the preview bar.

You can hide the preview bar while previewing a theme by adding the pb=0 parameter to the URL.

A new filter called dispute_type has been added to the available filters in the Order list (GraphQL query OrderListData). It is a multiple choice filter that allows to show only orders that have a chargeback and/or an inquiry associated with it.

You can now use the shopify.app.extensions() method in App Bridge to identify which of your checkout and customer account extensions are active on a merchant’s store. This feature simplifies tracking setup progress and assists in guiding merchants through onboarding.

With the shopify.app.extensions() method, your embedded app can query its checkout and customer account extensions. For each extension, you’ll receive:

• handle: The extension handle from your TOML file
• activations: Lists the targets where each extension is live (e.g., purchase.thank-you.block.render)

This data helps you show merchants what’s configured and what requires attention, particularly useful when migrating to the Thank You and Order Status pages.

This initial release supports only checkout and customer account extensions.

For more information, refer to the developer documentation.

The subtotal_price field has been added to Server Pixel events to enhance transaction data tracking. This field is now available in the following events:

• checkout_started
• payment_info_submitted
• checkout_completed

The subtotal_price represents the sum of all line item prices, after applying product and order level discounts.

Cart tokens will now be returned with a new format for both the AJAX and Storefront GraphQL Cart APIs. API features and functionality remain unchanged. Apps and themes should be designed to handle cart tokens in any format and of any length. Treat the cart token as a random identifier that will change in the future.

Action Required: Ensure that any app and theme code is free from hard-coded assumptions (ex. Using regex to identify a cart token) on the format and structure of the cart token.

The new App Bridge Reviews API allows Shopify apps to request reviews directly within the Shopify admin interface.

• Better merchant experience: Leave reviews directly in the Shopify admin with in-context prompts vs. multi-step App Store redirects.
• No customization required: The component has already been designed—you control when the review modal is shown to merchants (following our guidelines).
• Support callouts: The “Get Support” button will also be surfaced in the review modal, giving merchants with issues a direct path to resolution as an alternative to leaving a review.

Use development stores to test the Reviews API, which bypasses the rate limits and restrictions. Read more about testing and implementing the Reviews API.

We have introduced the multipassIdentifier field to the Admin GraphQL API, achieving feature parity with the REST Admin API. This update ensures that both APIs offer the same capabilities, enhancing consistency and flexibility for developers.

The multipassIdentifier field allows you to assign unique identifiers to customers, facilitating seamless authentication between your external website and Shopify store through the Multipass feature.

You can now utilize this field in both the customerCreate and customerUpdate mutations:

mutation {
  customerUpdate(input: {
    id: "gid://shopify/Customer/12345678",
    multipass_identifier: "your-multipass-identifier-value"
  }) {
    customer {
      id
      multipassIdentifier
    }
    userErrors {
      field
      message
    }
  }
}

For further details on working with customers in the Admin GraphQL API, please refer to our Customer documentation

As of July 3, 2025, we've made the following updates to POS UI Extensions:

Breaking Changes

We've removed the deprecated FormattedTextField component. Update your code to use TextField instead.

FormattedTextField still works in POS 10.6.0, but will no longer function in POS 10.7.0.

Deprecations

We've deprecated the following property values on the Icon component:

• For the size property, we've deprecated: 'minor', 'major', 'spot', 'caption', 'badge'. Use 's', 'm', 'l', 'xl' instead.
• For the name property, we've deprecated 'arrow', 'available-at-other-locations', 'collections', 'connectivity-warning', 'delivery', 'home', 'image-placeholder', 'internet', 'menu', 'orders', 'products', 'shipment'. See valid values for IconName.

Important Fixes

We've updated the pos.draft-order-details.block.render target to allow block components (BlockComponents). Previously, this target erroneously accepted action components (ActionComponents), which are intended targets like pos.draft-order-details.action.render.

Additions

Along with the above deprecations and fixes, we've added the following:

• Added a required posVersion property to the Session interface.
• Added an optional currency property to the Discount interface.
• Added an executedAt property to the BaseTransactionComplete interface.
• Added optional exchangeId and returnId properties to the ReturnTransactionData interface.
• Added a required variantId property to the ProductApi interface.
• Added an optional taxLines property to the ShippingLine interface.
• Added an optional onBlur handler to the SearchBar component.
• Added an optional tone property to the Icon component, and added new name and size options.

Additionally, in developer preview, we've introduced a Storage API. This API gives UI extensions access to store data on the POS device where the extension is running.

Versions

All changes are available for POS UI Extensions version 2025-07 and POS app version 10.6.0. For complete version details, refer to the version log.

As of API version 2025-07 you can now narrow the list of fulfillments returned by Order.fulfillments with an optional query argument that targets created_at and/or updated_at fields. The argument uses the same search syntax already familiar from other Admin API endpoints, for example:

fulfillments(query: "created_at:'2025-05-07T08:37:00Z'")
fulfillments(query: "created_at:>='2025-05-07T00:00:00Z' updated_at:<'2025-05-09T00:00:00Z'")

The field still returns a simple array—no pagination cursor needed—and behaves exactly as before if you omit query.

The discountClass field in the DraftOrderPlatformDiscount object has been deprecated. Please use the discountClasses field instead, which allows for the representation of multiple discount classes associated with the backing price rule of the DraftOrderPlatformDiscount.

To determine the specific impact of a DraftOrderPlatformDiscount on a draft order, continue using the presentationLevel field.

The Customer Account API now includes a discounts connection on customer subscription contracts, mirroring functionality that already exists in the Admin API.

What's new:

• Query subscription discount details directly from the Customer Account API.
• Access discount types, values, and line-item allocations through the discounts field returned by the SubscriptionContract query.
• No changes to existing Admin API functionality.

How to use it: You can now examine subscription discounts in customer storefronts using the discounts field on subscription contracts. This returns the same discount information available through the Admin API, including:

• Discount amounts and percentages
• Which subscription lines the discounts apply to
• Discount allocation details

This enhancement enables the creation of more comprehensive subscription management experiences, allowing customers to see precisely how discounts affect their subscription pricing.

Learn more

• SubscriptionDiscountConnection documentation
• GraphQL Customer Account API overview

Starting July 1, 2025, new category-specific requirements apply to marketing apps in the Built for Shopify (BFS) program. These requirements apply to the following categories:

• Ads apps – all criteria required
• Affiliate program apps – all criteria required
• Analytics apps – all criteria required
• Email marketing apps – select criteria based on your app's functionality
• Forms apps – all criteria required
• SMS marketing apps – select criteria based on your app's functionality
• Subscription apps - Customer Account UI extensions are now required

These requirements will be enforced during manual reviews of your app, which occur when you submit your app and at annual review.

For a full breakdown of these requirements, visit our developer documentation.

We're introducing new fields to help you better manage and track returns:

Quantity tracking fields

The following fields are now available on both ExchangeLineItem and ReturnLineItem objects:

• processedQuantity - Tracks the quantity of a return that has been processed.
• processableQuantity - Indicates the quantity ready for processing.
• unprocessedQuantity - Shows the remaining unprocessed quantity.

Return timestamps

You can now retrieve important timestamps for returns:

• Return.closedAt - The timestamp when the return was closed.
• Return.createdAt - The timestamp when the return was created.
• Return.requestApprovedAt - The timestamp when the return request was approved.
• ReverseFulfillmentOrderDisposition.createdAt - The timestamp when the disposition was created.

Breaking change

ExchangeLineItem.lineItem is now deprecated. Please use ExchangeLineItem.lineItems instead. If an exchange line item has been processed multiple times, it will have multiple associated line items. The lineItem field will only return the first associated line item.

Availability

These fields officially launched in API version 2025-07.

We're introducing the removeFromReturn mutation, which allows you to remove unprocessed items from returns efficiently.

What's new

This mutation enables the removal of:

• Return line items
• Exchange line items

Replaces previous mutation

The removeFromReturn mutation supersedes the returnLineItemRemoveFromReturn mutation, which was limited to removing only return line items.

Availability

Currently available in the unstable GraphQL API version, this mutation will be officially released in version 2025-07.

With the 2025-10 API version, the permitsSkuSharing argument has been updated for both the fulfillmentServiceCreate mutation and the FulfillmentService#create REST endpoint to return an error if a false value is passed in. Non-SKU sharing fulfillment services have been deprecated, and this pushes us in the direction of making all Fulfillment Services Sku sharing enabled.

If your app or service is currently passing in a false value, please update it to send in true instead, or omit this parameter entirely. This change means that any new fulfillment services that are created can share SKUs with other locations and ensures future compatibilty with our systems.

GraphQL mutation documentation REST endpoint documentation

In API version 2025-07, the maximum number of line items accepted by the draft order create and update mutations have been increased from 250 to 499. This change ensures that the GraphQL API now matches the REST API's limit.

As of API version 2025-07, fulfillment service apps can use the new estimatedShippedAt argument to specify when they estimate the fulfillment order to become fulfilled. Shopify Fulfillment Network partners will be expected to provide this value when accepting Fulfillment Requests.

estimatedShippedAt

We're making changes to our HTTP/1.0 and HTTP/1.1 request handling to improve security and compliance with web standards. Starting August 1, 2025, all POST requests to Shopify APIs must include either a Content-Length header or Transfer-Encoding: chunked header, or they'll return an HTTP 411 error.

What you need to do

Update your client libraries and API integrations to ensure all POST requests include one of these headers:

• Content-Length: Specifies the exact size of the request body in bytes
• Transfer-Encoding: chunked: Indicates the request body is sent in chunks

Most modern HTTP client libraries automatically include these headers, but some custom implementations or older libraries might not.

Why we're making this change

This change aligns with HTTP/1.1 standards (RFC 7230) and helps prevent potential security vulnerabilities related to request smuggling attacks. It ensures consistent request handling across our infrastructure.

We've introduced a new groupObjects argument to bulkOperationRunQuery and bulkOperationRunMutation mutations in the GraphQL Admin API that allow clients optionally to disable grouping and benefit from faster and more reliable bulk operation job runs.

The JSONL output file that GraphQL Admin API bulk operations jobs generate by default places child objects directly below their corresponding parent objects. Ensuring such grouping is costly and results in slower job run and increases chances of job timeout.

If you do not need grouping in the JSONL output, set groupObjects to false to benfit from faster and more reliable bulk operation jobs.

When you update your app's scopes, the app/scopes_updates webhook payload now includes the shop ID (shop_id).

You can now use the new unit_price_with_measurement filter to display unit prices in the customer's language, enhancing user experience and simplifying theme code.

Note: Unit prices are available only for stores located in the European Union (EU) or Switzerland. To add unit prices to products, you can do so through Shopify admin.

For detailed instructions on how to display unit prices in your theme, please refer to the unit pricing documentation.

The EligibleForShopifyTaxReporting and ShopifyTaxReportingLegacyAutoTaxMigrated fields have been removed from the ShopFeatures object as it is no longer utilized in Shopify tax reporting. There are no replacements for these fields for external-facing apps. If you rely on these fields, you should update your integration accordingly.

You can now read cart metafields in the GraphQL input query for Shopify Functions. Checkout UI extensions can also read and write cart metafields for abandoned carts, order edits, and draft orders, in addition to previously supported resources. Notably, cart metafields are carried over to abandoned carts for later use.

For security, use a reserved namespace to ensure only your app can access specific cart metafields.

Note: If you modify cart metafields using the cartMetafieldsSet or cartMetafieldDelete mutations, then the changes won't be available to Shopify Functions until the buyer goes to checkout or performs another cart action that triggers the function.

Example: Read a cart metafield in a function input query

query RunInput {
  cart {
    myCartMetafield: metafield(namespace: "myNamespace", key: "myCartMetafield") {
      value
    }
  }
}

We’ve standardized target and operation names in the Cart Transform, Delivery Customization, Fulfillment Constraints, Order Routing, Payment Customization, Cart and Checkout Validation APIs for better consistency and extensibility. The Cart and Checkout Validation API now returns operations like other Function APIs. Please note that these changes will only affect functions using version 2025-07 and later.

Unchanged APIs:

• Discount, Order Discount, Product Discount, Shipping Discount and Discounts Allocator
• Local Pickup and Pickup Point Generator

New target names

| Function API | Previous target name | New target name | |

Starting with API version 2025-10, image alt text will be exposed as a TranslatableResourceType. This means that image alt text surfaced to the buyer will be eligible for translation through the Translations API.

You can now set custom payment terms at checkout using the Payment Customization Function. In addition to renaming, reordering, or hiding payment methods, the new PaymentTermsSetOperation lets you define fixed, net, or event-based payment terms for each order, with optional deposits. Use the Payment Customization Function API to tailor both payment methods and payment terms to fit your business needs.

Last year, we announced the deprecation of the Checkout APIs, which Buy Button JS is dependent on. As part of this deprecation, checkout functionality will stop working on older versions of Buy Button JS on August 1, 2025 11:00 AM ET. To maintain functionality for customers to complete purchases, ensure that your app or storefront is on the latest major version of Buy Button JS (v3.0).

For documentation on how to update your Buy Button JS code, refer to the developer docs.

**Critical Deadline: August 1, 2025 11:00 AM ET. **You must update by this date or customers will not be able to complete purchases.

As of GraphQL Admin API version 2025-07, the orderCancel mutation allows you to issue refunds as store credit, in addition to the original payment methods, when orders are cancelled.

This update introduces a new refundMethod input, which offers greater flexibility in handling customer refunds during order cancellations, and deprecates the existing refund input.

Action required:

If you want to continue to issue refunds to the original payments methods on order cancellation, replace your usages of the refund input with the new refundMethod.originalPaymentMethodsRefund input going forward.

For detailed information and examples on how to implement the new input, visit our orderCancel documentation on Shopify.dev.

In API version 2025-10, we've enhanced order editing workflows, making them more flexible and improving traceability features. These updates expand mutation ID compatibility and add session details to return fields, making it easier to track and manage order editing sessions.

What's New

Direct order edit session access

Now, you can directly access order edit sessions through the id field on the OrderEditSession object, enhancing the tracking of changes throughout your order editing workflow.

Enhanced mutation ID flexibility

Order editing mutations now accept IDs from both CalculatedOrder and OrderEditSession objects. This enhancement provides greater flexibility in your application architecture by supporting different workflows based on session context.

Affected mutations:

• OrderEditAddCustomItem
• OrderEditAddLineItemDiscount
• OrderEditAddShippingLine
• OrderEditAddVariant
• OrderEditCommit
• OrderEditRemoveDiscount
• OrderEditRemoveShippingLine
• OrderEditRemoveLineItemDiscount
• OrderEditSetQuantity
• OrderEditUpdateDiscount
• OrderEditUpdateShippingLine

Expanded return fields

Order editing mutations now return an orderEditSession field, enabling you to use the session id in subsequent mutation calls for improved workflow continuity. This enhancement applies to all mutations listed above, plus:

• OrderEditBegin

These improvements provide a more flexible approach to managing order editing workflows while maintaining full traceability of session changes.

What's changing

The Liquid and Storefront GraphQL API now limits pagination of arrays of objects to 25,000 items. This affects:

• For paginated GraphQL queries (using first, last, before, after parameters), queries will now return an error when paginating past the 25,000th item in the array.
• For uses of the paginate tag in Liquid, the last allowed page will be returned when paginating past the 25,000th item in the array.
• Any query originating from Liquid or GraphQL for a count will now return a maximum of 25,001 (indicating "more than 25,000") for arrays with more items.

In addition to that:

• The maximum Liquid page size has been increased from 50 to 250 to match the Storefront GraphQL API limit.

The documentation for Liquid and API usage have been updated to reflect these limits.

Important: This change only affects the Liquid and Storefront GraphQL API. The Admin GraphQL API continues to support higher limits for merchant facing workflows. See recent changelogs to that effect here and here.

What you need to do

If your application, storefront, or Liquid theme paginates through more than 25,000 items:

• Add filters to views to help narrow down results before pagination. For example, filter by product type, price range, or availability.
• Update count handling to account for the 25,001 maximum return value and replace it with a human readable value like "More than 25,000 products available."

What's changing?

Starting on August 15th, 2025, Shopify will no longer set the _shopify_country cookie on merchant storefronts or checkout.

Required updates

Developers looking to establish the customer's location can use the Customer Privacy API's getRegion method, which will be more reliable than the cookie now being removed.

Example JavaScript code:

window.Shopify.loadFeatures([
  {
    name: 'consent-tracking-api',
    version: '0.1',
  },
], function (error) {
  if (error) {
    throw error;
  }
  
  // "CAON"
  let region = window.Shopify.customerPrivacy.getRegion(); 
  // "CA"
  let country = region.slice(0,2); 
});

Starting from 2025-07, the following productCreate input issues will be surfaced as userErrors:

• Linking multiple options to the same metafield
• Linking an option to an already-linked metafield
• Attempting to specify linkedMetafieldValue for an option that is not linked to a metafield
• Specifying both options and optionValues

We've added three new fields to the OrderTransaction object to give you better insights into order processing: device, location, and currency_exchange_adjustment. These fields offer additional context about the point of sale device used, the physical location of the transaction, and any currency exchange adjustments applied.

Additionally, the processed_at field is now available when using the OrderCreateManualPayment mutation. This allows you to specify the exact date and time a manual payment was processed, which is particularly useful for importing transactions from external platforms or applications.

For further details, see OrderTransaction and OrderCreateManualPayment.

The standard product review syndication program is now available to all partners, officially entering general availability.

Any partner can now build a reviews app that syndicates to the standard product review metaobject, as long as their app meets the program requirements. This enables reviews to be displayed in the Shop app and other surfaces across Shopify.

For documentation and implementation guidelines, refer to the developer docs.

With the 2025-07 version release of the Function APIs, you can now use the cart.deliveryGroups.groupType to determine the type of delivery group. The groupType field indicates whether the delivery is a one-time purchase (ONE_TIME_PURCHASE) or part of a recurring subscription (SUBSCRIPTION).

Delivery groups streamline fulfillment by organizing items that can be shipped together, based on the customer's shipping address. For example, if a customer orders a t-shirt and a pair of shoes that can be shipped together, then the items are included in the same delivery group.

We're changing the fallback behavior when determining the pricing and publishing that applies to a customer in a specific context. Currently, if a country that doesn't belong to a market is passed as a buyer signal, we use the store defaults. For example, the currency used for pricing will be the store's default currency. With this change, the market for the backupRegion will now be used so currency, catalogs, and other settings from that market will be used when determining pricing and publishing. This fallback matches the behavior on the storefont and allows for consistency in pricing and publishing APIs.

As of API version 2025-10, the following fields will usebackupRegion as a fallback:

• Product.contextualPricing
• ProductVariant.contextualPricing
• Product.publishedInContext

Previous versions will continue to fallback to store defaults.

The shopify app dev command now supports post-purchase checkout extensions without requiring the deprecated Chrome extension. This enhancement simplifies development, aligning it more closely with other checkout UI extension patterns.

Now, when you run shopify app dev with a post-purchase extension, the CLI will:

• Automatically configure cart permalinks with the necessary parameters for testing.
• Allow direct testing through the checkout flow without a browser extension.
• Redirect to the post-purchase page after the "Pay now" button is clicked.

For more detailed guidance, refer to the Build a post-purchase product offer checkout extension documentation.

Installation of individual presets will now match the expectations set by the demo stores in a theme. Previously, only the first preset was installable.

To enable this:

1. Submit your theme files that include /listings folders for approval by the Theme Review Team
2. Once approved, you’ll receive an email notifying you
3. Update your listing page details for each preset
4. Hit submit

Once submitted, preset names and their associated listing files will be published to your existing theme details page, making each preset immediately installable when a merchant hits “Try theme”.

Note: New listing information specific to presets will not be live until dedicated preset listing pages launch in July alongside the Theme Store redesign.

Shop metafield definitions and values are now be exposed in the Shopify Admin UI, making them more accessible and manageable by merchants.

Additionally, it's now possible to query for shop metafield definitions using the metafieldDefinitions query in the Admin GraphQL API.

Shop is already a supported metafield owner type, and this change enables apps and merchants to manage definitions for shop-level metafields.

We've added a title filter to the articles query, allowing you to fetch a list of articles by their title.

{
  articles(query: "title:about us", first: 10) {
    edges {
      node {
        id
        title
      }
    }
  }
}

We've added a new new type of warning to the DraftOrder object: DraftOrderMarketRegionCountryCodeNotSupportedWarning.

The marketRegionCountryCode field is deprecated and does not affect draft orders on shops that use Markets. Because of this, the DraftOrderMarketRegionCountryCodeNotSupportedWarning warning indicates that the marketRegionCountryCode field was set when creating, calculating, or updating a draft order on a shop that uses Markets.

Carriers occasionally respond with HTTP 3xx redirects or 4xx client errors. Previously, this left merchants without shipping options at checkout. The rate service now extends its existing error-handling path to treat these responses as recoverable failures. This change triggers a fallback to backup rates instead of resulting in a hard failure. As a result, shoppers still see viable shipping methods, safeguarding conversion and improving overall checkout reliability.

You can now recommend specific theme blocks in the block picker, making them easier to find.

To do this, include the @theme block type along with your recommended blocks in the blocks array of the schema. All other blocks remain accessible by selecting Show all. Learn more.

We've updated Polaris, making it a unified web component toolkit for all Shopify surfaces: Admin, Checkout, Customer Accounts. Additionally, Polaris is now smaller, faster, framework-agnostic, and always up-to-date via Shopify’s CDN. This update is in early access.

To get started, check out the developer documentation, or learn more about the library by reading our blog post.

Polaris web component support is now available in early access on the Shopify Dev MCP server. You'll get up-to-date Polaris API documentation, and integration with LLM-assisted workflows for faster and easier development with the updated components. Get started by setting the POLARIS_UNIFIED = true environment variable, or see the early access docs for more information.

We have introduced a new visible_if Liquid setting property that allows you to control the visibility of settings in the Theme Editor. This attribute enables you to hide theme settings that are not currently relevant, while still preserving their data. It applies to all basic and sidebar settings, as well as most specialized input settings, enhancing the customization experience.

For more detailed information, please refer to the developer documentation.

The new retailLocation field in the Function APIs allows you to tailor your logic based on whether a checkout is happening in a retail environment. This allows you to create different behaviors depending on the sales channel or even the specific retail store location. For example, you can implement location-specific discounts only for in-store purchases, creating differentiated experiences between online and retail customers.

The retailLocation field is currently available in the unstable API version, and will be included in the stable 2025-07 API version.

We've completely revamped our highly-visited and least-loved Shopify Function API reference docs. You’ve shared many helpful comments and questions through our Was this page helpful? form, and we’ve reviewed and addressed them in this latest revision.

Here’s the lowdown on the latest updates.

One comprehensive overview

We’ve added a single, consolidated overview that outlines the foundational information you need before diving into any specific Function API. No more feeling lost right from the start!

A dedicated page for each Function API

Each Function API now has its own dedicated page, meaning you’ll no longer need to jump between various pages to find the information you need. This streamlined approach helps you to understand the API, its targets, data structures, and common use cases.

And what can you expect on each page?

• End-to-end examples for every Function API, demonstrating complete implementation patterns tailored to common merchant scenarios.
• Interactive object exploration to help you dive deep into GraphQL objects—all in one convenient location.
• Visual diagrams that clearly illustrate how each Function operates within the Shopify ecosystem, making complex concepts easier to grasp.
• Performance metrics that show execution costs for each Function API, helping you to optimize your integrations efficiently.

A version picker for easy navigation

We’ve introduced a centralized version picker that allows you to toggle between different API versions easily, right from the sidebar.

Give it a try!

These updates are all about making your life easier. Less time scratching your head or making guesses means more time building amazing things!

Explore the revamped docs—we'd love to know what you think. Where have these updates helped, and where else in the Function API docs would you like to see improvements? You can leave comments by clicking the Was this page helpful? button.

New features, good vibes. Announcing 150+ updates to Shopify.

See the updates

The latest version of Hydrogen, 2025.5.0 is out today. With this release, Hydrogen is upgrading from Remix 2 to React Router 7. Follow the upgrade guide shared in our Hydrogen May 2025 release blog post https://hydrogen.shopify.dev/update/may-2025. And please drop your comments, feedback, and suggestions in GitHub Discussions!

Shopify Catalog provides select apps and AI agents with access to Shopify’s global product catalog delivering detailed product information including pricing, options, and availability in real-time. It is available as both an API and an MCP server, giving developers a choice in how they build their app and access product data.

Select partners will be given access to Shopify Catalog. To be considered, please sign up through the Summer ‘25 Shopify Editions site.

We've optimized Shopify App Store search for Japanese, Chinese, Korean, and Thai, allowing global merchants to discover apps faster and easier. Updates include:

• Better synonym and character matching in app search results
• Improved autocomplete suggestions
• Better typing experience with ENTER no longer submits search

We’ve improved the recommendation algorithm for large merchants to better surface apps installed and liked by similar-sized businesses.

In addition to where personalized results are currently shown, the app listing page will have a new section highlighting key insights for large businesses.

We've enhanced the Dev Assistant and the shopify.dev MCP server, adding support for Shopify Functions. Now, AI-powered assistance can help you build and optimize Functions code, streamline your development process, and accelerate your implementation. When you describe your desired outcome to the Dev Assistant, it can do the following things:

• Suggest a Function API : Identify the most suitable Function API for your use case.
• Generate code: For example, input queries, Function logic (in Rust), and the expected output.
• Convert JavaScript to Rust: Convert existing JavaScript code to Rust, enhancing performance and lowering execution costs.

Together, these features simplify Shopify Functions development, making it more accessible to developers who are new to Rust or unfamiliar with the Function APIs.

To get started, simply describe your Functions-related goals to the Dev Assistant. Then, let it guide you through your implementation with relevant code examples and explanations.

This new functionality is available in the Dev Assistant on shopify.dev, or through the shopify.dev MCP server.

Block presets now have visual previews in the picker, similarly to section previews.

No action is required—previews will work automatically. If you want to further customize how your blocks appear in preview mode, learn more about the optional visual_preview_mode attribute in our theme editor documentation.

You can now edit line items with selling plans (including subscriptions and pre-orders) before an order ships. This update gives you the flexibility to change quantities, add discounts, and remove line items that contain a selling plan.

This functionality is available through the Order Edit API and Shopify Admin.

The Shopify CLI app dev command enables development, preview, and testing of your app on development stores. This command includes a number of improvements when used with early access to the Next-Gen Dev Platform:

• All changes are isolated to your chosen development store.
• All changes to app configuration can now be previewed, without the need to run app deploy.
• Extension additions and deletions are now included, without the need to restart app dev.
• Your app is now automatically installed on your chosen development store.
• Access scope changes are automatically accepted on your chosen development store when you change them in the shopify.app.toml.
• The app preview created during app dev remains on your development store until you run app dev clean or uninstall the app.
• The Dev Console in the Shopify Admin will inform you about any active app previews on the store.

Note: For existing apps, the behavior of app dev is currently unchanged.

For more information, see documentation on improvements to the app dev command.

Please report any issues and provide your feedback about these updates on the Shopify Developer Community.

Shopify Functions now support a WebAssembly query API, letting you build smaller, faster, and more powerful functions. Deserialize data just-in-time, and only pay for the fields your function actually uses.

Learn more about WebAssembly for Functions.

Skeleton theme is now available: a minimal, carefully structured Shopify theme designed to help you quickly get started. Built with modularity, maintainability, and Shopify's best practices in mind.

Key features:

• Minimal and modular: A clean, flexible starting point.
• Best practices built-in: Performant and easy to maintain.
• Developer-focused: Easy to extend and customize.

Get started by visiting the Skeleton theme repository or by running shopify theme init from your command line.

You can now use the CustomerPrivacy API to manage customer privacy on customer account pages, including the Order status page. Use the new footer extension target to build cookie banner extensions that display on each customer account page, or use the API directly to ensure your existing extensions respect customer consent preferences. This update is only available for shops using a custom domain for customer accounts.

Learn more in the CustomerPrivacy API reference.

Now, you can serve your app using localhost (127.0.0.1) with a self-signed HTTPS certificate, which Shopify CLI generates for you. This allows you to develop some Shopify app features without the use of network tunnels.

To serve your app using localhost, run the following command using Shopify CLI 3.80 or higher: shopify app dev --use-localhost.

Newly added since developer preview:

• --use-localhost will now use a static port by default, which you can override with --localhost-port.
• Detection of Windows Subsystem for Linux and documentation on additional required steps for its setup.

Note: Localhost-based development isn't compatible with the Shopify features that directly invoke your app, such as Webhooks, App proxy, and Flow actions, and features that require you to test your app from another device, such as POS.

For more information, you can read about networking options for local development.

Please report any issues and provide your feedback about this feature on the Shopify Developer Community.

Declarative custom data definitions offer a streamlined approach for managing and maintaining metafields and metaobjects. Key benefits include:

• Metafield and metaobject definitions are organized in TOML, and managed through the improved app dev command.
• Shopify automatically distributes these definitions to multiple shops simultaneously, significantly speeding up migration processes.
• Updates are atomic, ensuring that all stores consistently maintain the same version of your definitions.
• All declarative definitions include app-scoped limits, which prevent resource competition among different apps.

For more information, see the declarative custom data documentation on shopify.dev.

You can now use the new Dev Dashboard to create development stores with any Shopify plan, including Plus. This provides a testing environment that mirrors the features and limitations of specific production plans.

• Dev stores with any plan: Create development stores with Basic, Grow, Advanced, or Plus plans.
• Streamlined UI: Access all your stores through a single, streamlined interface in the Dev Dashboard.
• No-cost: Create and manage these stores at no cost.

Learn more about how to use development stores in the Next-Gen Dev Platform.

Shopify Flow has an improved Send HTTP request action that supports a broader range of integrations with external services by securely storing secrets and returning data to subsequent workflow steps. The action can be securely configured with secrets, such as access tokens or passwords, that are encrypted and obfuscated in Flow. After sending an HTTP request, the full response is returned to the workflow and can be parsed using a Run code action with a JSON.parse method to define a schema so that returned data can be used as variables in conditions and actions.

Review these new templates to learn more about using this improved action:

• Send new orders to Airtable
• Send all existing and new products to Airtable
• Update products in batches from product data stored in Airtable
• Notify customers of expiring gifts cards using SendGrid
• Send email using SendGrid when customers places an order for a custom item

For more information about how it works, visit the documentation. For questions and feedback, visit the Shopify community.

The all new Dev Dashboard serves as a comprehensive hub for all your app development activities, whether you're a merchant creating custom apps or a partner developing public apps. Key features include:

• Unified App Management: Seamlessly create, configure, and deploy apps from a single, streamlined interface to simplify your workflow.
• Enhanced Development Stores: Easily create and manage development stores with any Shopify plan, including Plus, offering flexibility and scalability for testing and development.
• Improved App Versioning: Confidently create new versions, manage extensions, and release updates to keep your apps current and functional.
• Monitoring and Logs: Access webhook and function metrics and logs to ensure your app operates correctly.

LiquidDoc is a new way to add structured documentation directly within your Liquid snippets, and blocks. Define clear input parameters, include helpful descriptions, and provide practical usage examples right alongside your Liquid code.

LiquidDoc integrates seamlessly with theme checks, code completions, and hover information, helping you catch common mistakes - like missing or misspelled parameters - before they become issues. This makes theme development faster, simpler, and more reliable.

Learn more in the official LiquidDoc documentation.

What is changing? Effective June 1st, 2025, all apps undergoing Built for Shopify (BFS) review, will be graded against the simplified BFS design requirements.

Why are we making this change? This change is in response to feedback from our partner community. The previous 104 BFS design requirements (spread across 13 design sub-categories) were overwhelming, and could be challenging for Partners to interpret correctly.

The goal with this change was to streamline and simplify the BFS design requirements while still ensuring that the BFS program continues to be a high-water mark for overall app quality. There are now only 19 BFS design requirements spread across 3 design sub-categories.

What action is required? If you are planning to submit your app for BFS review or your existing BFS app is coming up for renewal, please make sure that your app adheres to the simplified BFS design requirements.

As of May 20th, 2025 apps will be permitted to complete refunds to store credit when store credit was not the original payment method. With this update you can issue store credit to customers as a refund and they can later spend that store credit at checkout. A customer's store credit is visible on their customer accounts profile page and it can be queried via the GraphQL Admin API.

Learn how to issue store credit refunds in the GraphQL Admin API.

The latest version of Hydrogen v2025.4.0 is out. This release contains updates to internationalization, cart functionality, and template improvements, as well as the latest SFAPI version.

• Update SFAPI to 2025-04 (#2886)
• Fixed duplicate content issues with internationalized product handles (#2821).
• Fixed cart quantity validation (#2855)
• Improved customer account logout handling (#2843)
• Deprecated <VariantSelector /> (#2837)
• Refactored ProductItem into a separate component (#2872)

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

This API enables you to efficiently retrieve all available delivery options for draft orders with a single request. It introduces a specialized endpoint that replaces the legacy CalculatedDraftOrder field for available shipping rates.

The new endpoint allows developers to fetch not only shipping rates but also options for local delivery and pickup, with support for pagination. This feature is now accessible to all apps with the read_draft_orders access scope. This enhancement streamlines the process of obtaining comprehensive delivery options, improving the efficiency of order management.

As of version 2025-07 of the GraphQL Storefront API, the Cart object now provides detailed warnings for non-applicable CartDiscountCodes.

Previously, when a discount code could not be applied, the CartDiscountCode was returned with applicable: false, and no additional details. This lack of information made it difficult for developers to provide helpful feedback to buyers.

With the introduction of the new CartWarning types, you can now clearly identify the specific reasons why a discount code isn't applicable.

Shopify Functions now supports up to 25 active functions per Function API, increased from the previous limit of 5. This allows developers to split complex or unrelated logic into smaller, dedicated functions rather than combining everything together.

This change applies to:

• Payment customizations
• Delivery customizations
• Cart and checkout validations
• Fulfillment constraints

All count APIs in GraphQL now return uncapped results. To retrieve an uncapped count, set the limit argument to null.

As part of this update, we've standardized the implementation across all GraphQL APIs. This change introduces a breaking change: all APIs now include a limit argument, with a default value of 10000.

List of APIs impacted

• abandonedCheckoutsCount
• blogsCount
• catalogsCount
• collectionsCount
• customersCount
• discountCodesCount
• discountNodesCount
• draftOrdersCount
• giftCardsCount
• locationsCount
• ordersCount
• pagesCount
• productsCount
• productVariantsCount
• urlRedirectsCount
• webhookSubscriptionsCount

Note: Due to the large number of events generated, we're continuing to cap eventsCount at 10,000.

In line with last year's announcement regarding metafields access simplification, we are now implementing the removal of PUBLIC access for app-owned metafields and metaobjects.

The following updates have been applied across all API versions:

1. Metafields and metaobjects previously set to PUBLIC_READ_WRITE are now set to MERCHANT_READ_WRITE.
2. Metafields and metaobjects previously set to PUBLIC_READ are now set to MERCHANT_READ.

Required Action: If your app needs metafields or metaobjects to be accessible by other apps, you must migrate them to a custom namespace rather than using your app's reserved namespace. A custom namespace allows for broader access options, while a reserved namespace is specific to your app.

We've added a new optional category property for section and block presets that helps you organize your presets into logical groups. Now your merchants can find the right design elements faster and more intuitively in the Online Store Editor.

You can learn more by visiting block preset and section preset docs.

Starting May 15, 2025, all Shopify themes must meet the updated Theme Store requirements for new submissions and updates.

Key changes include:

• Theme Zip File Structure: New /listings folder is now required in theme zip files.
• Preset Naming Requirements: Theme name requirements now apply to each preset.
• Industry Categories + Tagging: Each theme preset can be tagged with a maximum of two industries. There are now 20 industry categories to choose from.
• Catalog Size Categories + Tagging: Each theme preset must be tagged with one catalog size. Four catalog size categories are now available.
• Demo Store Requirements:
• Each demo store must match the primary industry and catalog size the preset is tagged with.
• The install store must match the expectations set by the demo store.
• Listing Page Structure: The submission form is updated to support individual listing pages for every preset.
• Simplified UX & Design Requirements: Simpler, more explicit, and easier for you to follow.

These updates are part of a broader redesign of the Shopify Theme Store, set to launch in July 2025. This redesign aims to enhance theme discovery for merchants and streamline their setup process, while providing developers with better marketing opportunities.

IMPORTANT – Next Steps for Developers: To keep your themes listed after the redesign launches in July, please update and resubmit your theme files by June 22. Updated themes and listing pages will not be published until the new Theme Store goes live in July.

Note: Expect potential delays for new theme submissions and updates during the migration period from May 15 to July 1, 2025.

To increase the trustworthiness of the Shopify App Store, we’re archiving a significant number of outdated, unhelpful, and untrusted reviews.

Archived reviews are not factored into app ratings or total review counts. Some will remain visible at the end of the reviews section on app listings.

While many reviews are being archived, the vast majority of apps will not see changes to their app rating or ranking.

In the coming months, we’re adding more quality signals to help businesses find apps that are truly right for them. Together, these updates combat manipulative practices like review farming, fake reviews, and other bad faith reviews so you can focus on what matters most—building exceptional apps that help businesses grow.

To streamline feedback, developers now receive instant email notifications when merchants submit new reviews. Later this year, we’ll also introduce tools to help app developers collect merchant feedback directly within the Shopify admin.

Archived review decisions cannot be appealed. For more details, explore our updated docs.

We have added support for discounts in the Cart AJAX API's /cart/update.js endpoint. You can now add or remove discounts from your cart using the discount parameter.

Learn more about cart discount support on shopify.dev.

We’ve added a new error code, FREE_GIFT_CARD_NOT_ALLOWED, to the SubscriptionBillingAttemptErrorCode enum. This error occurs when a subscription contract includes a gift card product with a purchase price of $0, which is not permitted under Shopify’s business rules.

While the situation is rare, this error can occur due to edge cases in dynamic pricing scenarios (for example, bundles or cart transformations could inadvertently set a gift card’s price to zero when part of a subscription contract). Previously, this resulted in a generic error message, making the cause difficult to troubleshoot.

Note: This error concerns the purchase price of the gift card as a product, not the monetary value loaded onto the card for the gift recipient.

Adding this specific error code improves clarity for Partners and developers, making it easier to diagnose and resolve issues related to subscriptions containing zero-priced gift cards.

This error code has been added to API versions 2025-01 and later.

We've introduced a BUYER_CANNOT_PURCHASE_FOR_COMPANY_LOCATION CartErrorCode, which indicates a buyer has lost permission to purchase for their selected company location.

Shopify is retiring gates types and fields due to limited usage and our commitment to enhancing developer tools with more robust APIs. To ensure your applications continue to function optimally, we recommend transitioning your implementations to metafields and metaobjects. These solutions offer powerful capabilities for managing structured custom data, seamlessly integrated across Shopify's Admin API, Storefront API, and Functions.

Metafields and metaobjects provide a flexible and efficient way to store and retrieve custom data, enhancing your ability to tailor Shopify experiences to your specific needs. For detailed guidance on migrating your implementations, please refer to our custom data documentation.

Shopify is retiring gates types and fields due to limited usage and our commitment to enhancing developer tools with more robust APIs. To ensure your applications continue to function optimally, we recommend transitioning your implementations to metafields and metaobjects. These solutions offer powerful capabilities for managing structured custom data, seamlessly integrated across Shopify's Admin API, Storefront API, and Functions.

Metafields and metaobjects provide a flexible and efficient way to store and retrieve custom data, enhancing your ability to tailor Shopify experiences to your specific needs. For detailed guidance on migrating your implementations, please refer to our custom data documentation.

You can now remind customers of their store credit balance by displaying it on the storefront using the new store credit account object. This object can be accessed through the store_credit_account property of the customer object.

To display the customer's store credit balance in the current context, use the following Liquid expression: {{customer.store_credit_account.balance | money_with_currency}}.

Learn more about using store credit in Liquid.

Shopify now enables developers to retrieve Shop Pay payment request details and statuses directly through GraphQL queries. This feature allows easy access to payment information by specifying a custom source_identifier or using the Shop Pay payment request receipt token. By using these identifiers, developers can streamline payment processing workflows and improve the accuracy of data retrieval.

Please note that this feature is available exclusively to merchants using Shop Compoent.

We have added new query parameters to the orders connection (OrderConnection) within the customer query of the GraphQL Customer Account API.

Developers can now filter orders using the name and confirmation_number parameters, which enables more precise order filtering.

As of API version 2025-07, the draftOrderCreateMerchantCheckout mutation has been deprecated. Please use the draftOrderComplete mutation instead.

For more information, please visit our help docs.

We’ve added new automated checks to the Shopify App Store review process to help you prepare your app for submission, provide faster feedback, and prevent common errors. New auto-checks include:

• App immediately authenticates after install
• Redirects to app UI directly after install
• Uninstalls and re-installs correctly
• Using the latest version of App Bridge
• Additional checks for app listing compliance (with guidance for app name, description)

As of April 30, 2025, payment apps are no longer eligible to be embedded apps within the Shopify admin. The Payment Apps requirements have been updated to reflect this change.

The new paymentSessionModal mutation raises a modal that will be displayed to the buyer after purchase. This modal uses provided data to display additional info to buyers. For example, you could show a QR Code that a buyer can scan, or render message telling buyers to complete an action on an external device.

During the pandemic, we lowered our revshare to help small developers and introduced an exemption on the first $1M earned each year. Our ecosystem is stronger than ever—merchants have more than 16,000 apps to choose from, and we paid out more than $1B to developers last year.

The time has now come to sunset the annual exemption reset. Developers will continue to enjoy a revshare exemption on the first $1 million USD of lifetime revenue, and a 15% share on amounts above that.

Key details:

• Earnings before January 1, 2025 do not count toward the $1 million threshold.
• Earnings are aggregated at the partner level, including apps developed under associated developer accounts.
• Updates to Shopify’s Partner Program Agreement will go into effect June 16, 2025. Continued use of Shopify services on or after June 16, 2025 confirms that you’ve read, understood, and accepted these new terms.

The additional revenue collected will fund tools, infrastructure, and innovation that benefit developers at every stage. Over the past two years alone, we’ve:

• Introduced platform-managed features, including Shopify-managed installation, webhooks, and pricing—all of which reduce complexity for app developers.
• Added admin extensions, Checkout UI extensions, and Shopify Functions, helping developers integrate into admin and offload logic and UI rendering to Shopify.
• Offered app metafields and metaobjects with Direct API access, enabling developers to use Shopify for app storage.
• Made it easier to grow your app business with a streamlined app review process, a full-funnel ads product, and much more surface area for discovery on the redesigned Shopify App Store.

You can now pass arbitraty parameters to static blocks, making it possible simplify the theme code by building more composable components.

As an example, you can pass color from your section to your static block:

{% content_for "block", id:"slide-1", type:"slideshow", color: "#F00" %}

From the block that data can be easily accessed:

{{ color }}

You can learn more about this feature in our developer docs.

You can now issue a specified amount as new store credit when processing refunds. This can be done in addition to refunding amounts to the original payment methods. If a customer requests a refund to their original payment method after already receiving a refund to new store credit, you can accomplish this by specifying a parameter that allows over-refunding. Note that this parameter is disabled by default.

To use this feature, ensure the following prerequisites are met:

• New customer accounts must be enabled in the store.
• The order must be associated with a customer.

This feature integrates with the standard refund API process as follows:

• Use the Order.suggestedRefund field to create a suggested set of transactions and refund methods. You can now use the refundMethodAllocation parameter to define this set.
• Pass the transactions and other refund components (e.g. refundLineItems), as before, to the refundCreate mutation. Additionally, you can now use the refundMethods parameter to pass in any refunds to new store credit.

You can also refund to store credit using new return processing APIs:

• Use the Return.suggestedFinancialOutcome field to query for suggested refund amounts. Specify STORE_CREDIT as the refundMethodAllocation parameter to retrieve a suggested store credit refund amount.
• Use the financialTransfer.issueRefund.refundMethods parameter of the returnProcess mutation to specify the storeCreditRefund amount and complete the refund.

The event.data.checkout.subtotalPrice.amount value in the Web Pixels API has been updated.

Previously, this value included the sum of all line item prices and product-level discounts, but not order-level discounts. Now, event.data.checkout.subtotalPrice.amount reflects the sum of all line item prices after applying both product and order-level discounts. This update aligns the definition with the event.data.checkout.subtotalPrice.amount field on the old /thank_you page.

The event.data.checkout.subtotalPrice.amount changes will affect the following events:

• checkout_completed (on the new /thank-you page only)
• checkout_started
• checkout_address_info_submitted
• checkout_shipping_info_submitted
• checkout_contact_info_submitted
• payment_info_submitted

If you use any of the above events, you should ensure that your pixel expects both product and order-level discounts to be included in this field.

In the release candidate for version 2025-07 of the Storefront, GraphQL Admin, and Customer Account API, the UnitPriceMeasurementMeasuredUnit enum now supports values for imperial units and counts.

For example:

• $10/oz or $5/ft
• $2/item

This update enables merchants to display more relevant and transparent pricing.

When 2025-07 is in the latest stable version, you can do the following to ensure that your app is compatible with the new measurement units:

• Update your app to API version 2025-07.
• Make relevant requests to API version 2025-07 for unit pricing.

Otherwise, the API will return the price value but return null imperial units and counts.

The POS UI Extensions Cart API has been updated, removing the email, firstName, lastName, and note Customer fields from the subscribable hook. Any extension used in POS version 10.0.0 or higher, and any extension targeting API version 2025-01 or higher, won't have access to these fields.

To get this data, update your code to use the customerId to retrieve the customer record from the GraphQL Admin API. To do this, your extension must have the read_customers permission access scope.

To learn more, read the POS UI Extensions documentation.

The publicDisplayName field is being added to the ShopPlan object. This field provides the publicly displayable name of the shop's current plan when requesting shop properties.

The publicDisplayName field returns a standardized set of plan names, similar to those currently provided by the displayName field. This standardization aims to simplify and unify the plan names that are publicly exposed.

Additionally, the plan previously known as Shopify has been renamed to Grow, and this change is reflected in the publicDisplayName field.

Please note that the displayName field will be deprecated in the future. We recommend updating your applications to use the publicDisplayName field to ensure compatibility with future updates.

To clear all delivery addresses associated with a cart, you can now call the cartDeliveryAddressesUpdate mutation and set addresses to an empty array([]).

Previously, to clear a cart’s addresses, you could call the cartBuyerIdentityUpdate mutation and set buyerIdentity.deliveryAddressPreferences to an empty array. However, deliveryAddressPreferences is deprecated.

Action required before API version 2025-10

Review your existing code. Starting with API version 2025-10, setting the addresses field of the cartDeliveryAddressesUpdate mutation to an empty array ([]) clears cart addresses. If you do not want this behavior, update your code.