POS UI Extensions 2026-07 introduces the Printing API (shopify.printing), which enables extensions to discover hardware printers with getPrinters() and send documents directly to a connected receipt printer with print().

The Printing API supersedes shopify.print, which is now deprecated. No immediate action is required; plan to migrate when you adopt 2026-07.

What changed

• shopify.printing.getPrinters() returns the hardware printers available to the device. Each printer includes an id, name, and connected status.
• shopify.printing.print(src, options?) prints the document at src. If you omit options.printer, the system print dialog opens. If you pass a printer returned by getPrinters(), the document prints directly to that printer with no dialog.

The src must be either a relative path appended to your app’s application_url, or a full URL on the same origin. The document is fetched using the extension’s session token.

Receipt printers can render HTML and images directly. PDFs require the system print dialog: if you pass a printer when src points to a PDF, shopify.printing.print throws an error. For PDFs, always omit options.printer and rely on the system print dialog.

Previously, shopify.print could only open the system print dialog, which cannot target dedicated receipt printers. Earlier POS UI Extensions API versions are unchanged.

Note: Hardware printer discovery requires Shopify POS version 11.11.0 or later. On earlier versions, getPrinters() returns an empty array, even when a receipt printer is paired. This does not affect the system print dialog, which remains available.

Always handle the empty-array case by falling back to the system print dialog. This also covers merchants without a receipt printer:

const printers = await shopify.printing.getPrinters();
const receiptPrinter = printers.find((printer) => printer.connected);

if (receiptPrinter) {
  await shopify.printing.print('/print/receipt', {printer: receiptPrinter});
} else {
  await shopify.printing.print('/print/receipt');
}

The Printing API is available on all POS UI extension targets. To verify direct printing, test on a development store with POS 11.11.0 or later and a paired receipt printer. Call shopify.printing.print with a printer from getPrinters(); if the job prints without a dialog, direct printing is working.

Related docs

• Printing API reference
• Print API reference (deprecated)

Starting in API version 2026-10, the GraphQL Admin API returns an error when a query filters by a metafield that isn't set up for filtering, instead of silently returning incorrect results. This is a breaking change. It affects apps that filter resources by metafield on version 2026-10 or later, and you'll need to update affected queries before you upgrade.

What changed

In API version 2026-10 and later, the GraphQL Admin API checks metafield filters before it runs a query. If a query filters by a metafield that can't be used for filtering, the query returns an error explaining the problem instead of ignoring the invalid predicate and returning an incorrect result.

A metafield filter commonly fails when:

• The metafield doesn't have a definition.
• The metafield's definition isn't configured to allow filtering.
• The metafield's type doesn't support the filter or comparison you used.

Previously, invalid predicates in metafield filters were silently ignored, so a query with an invalid filter could return misleading results. Now the response tells you the filter is the problem, so you can correct it.

Who's affected

This change affects apps and integrations that filter by metafields in the GraphQL Admin API (for example, filtering products, orders, or customers by a metafield) on API version 2026-10 or later. Queries on version 2026-07 and earlier keep the previous behavior and aren't affected until you upgrade.

You're affected only when a query filters by a metafield that isn't valid for filtering. Queries that filter by metafields set up for filtering, using a supported comparison, behave exactly as before and return the same results.

Why this matters

Silently returning incorrect results made invalid metafield filters hard to catch: a mistyped or unsupported filter looked identical to a query that simply had different matches. Returning an error instead lets you find and fix these problems during development, rather than shipping a filter that quietly returns nothing in production.

Breaking changes and migrations

API version 2026-10 is scheduled for release on October 1, 2026. Once you make requests on 2026-10 or later, a query that filters by a metafield that isn't set up for filtering returns an error instead of an empty result.

To migrate:

1. Find the queries in your app that filter by metafields in the GraphQL Admin API.
2. For each one, confirm the metafield has a definition, the definition allows filtering, and the comparison you use is supported for that metafield's type.
3. Update any filter that references a metafield that isn't set up for filtering.
4. Test your queries against version 2026-10 and confirm they return results without an error.

If a metafield you rely on can't be filtered yet, keep those queries on version 2026-07 or earlier until you've updated your app, and set up the metafield definition for filtering before you upgrade.

Apps can now subscribe to events for Order, Collection, InventoryItem, InventoryShipment, Location, and can subscribe to metafield changes on Product, Order, Customer, Collection and Location. ProductVariant metafields are supported through the Product topic.

This gives apps a precise way to react to more objects and custom data changes. Apps can target the fields that matter in triggers, query the resource that changed, and avoid subscribing to every resource update just to diff payloads in their event handler.

Both $app metafields and regular metafields are supported. Access control still applies, so an app must have access to the metafield to subscribe to changes and receive the queried data. For example, an app can subscribe to two targeted product metafields in shopify.app.toml and use query_variables to fetch the metafield that actually changed:

[events]
api_version = "unstable"

[[events.subscription]]
handle = "product_material_sync"
topic = "Product"
actions = ["update"]
triggers = [
  "product.metafield(namespace: 'custom', key: 'material').value",
  "product.metafield(namespace: '$app', key: 'sourcing_status').value"
]

uri = "/events/product"

query = """
query ProductMetafieldSync(
  $productId: ID!
  $metafieldNamespace: String!
  $metafieldKey: String!
) {
  product(id: $productId) {
    id
    title
    metafield(namespace: $metafieldNamespace, key: $metafieldKey) {
      namespace
      key
      value
      type
    }
  }
}
"""

When one of those metafields changes, apps receive the payload they designed:

{
  "topic": "Product",
  "action": "update",
  "handle": "product_material_sync",
  "data": {
    "product": {
      "id": "gid://shopify/Product/1234567890",
      "title": "Canvas Tote",
      "metafield": {
        "namespace": "custom",
        "key": "material",
        "value": "Cotton",
        "type": "single_line_text_field"
      }
    }
  },
  "fields_changed": [
    "product.metafield(namespace: 'custom', key: 'material').value"
  ],
  "query_variables": {
    "productId": "gid://shopify/Product/1234567890",
    "metafieldNamespace": "custom",
    "metafieldKey": "material"
  }
}

If your subscription has no triggers, or subscribes to a parent trigger such as product, it can now receive events for metafield changes on supported resources too. To receive only specific metafield changes, add targeted metafield triggers for the namespace and key your app needs.

Events remain available in the unstable API version during developer preview. For topics that are not supported yet, continue using webhooks alongside Events in shopify.app.toml.

Learn more about

• Events: https://shopify.dev/docs/apps/build/events
• Order: https://shopify.dev/docs/api/events/latest/order
• Collection: https://shopify.dev/docs/api/events/latest/collection
• InventoryItem: https://shopify.dev/docs/api/events/latest/intentory-item
• InventoryShipment: https://shopify.dev/docs/api/events/latest/inventory-shipment
• Location: https://shopify.dev/docs/api/events/latest/location

The Liquid July ’26 developer preview introduces a simpler way to build theme pages. Page structure can live directly in a Liquid template, where developers and coding agents can read and edit everything in one place. The peview adds two Liquid tags:

• {% block %} renders a reusable theme block directly from a template. Name the block, pass its inputs, and provide body content much like you would with {% render %}.
• {% partial %} defines a named region of server-rendered HTML that JavaScript can refresh without reloading the full page.

Together, these tags let you compose pages in Liquid and add dynamic storefront interactions without moving rendering into a client-side framework.

The preview also adds new Theme Check rules for Liquid-first themes. They catch syntax errors, excessive complexity, oversized files, invalid schema structure, and mismatches between block arguments, schemas, and {% doc %} declarations. See the Theme Check 3.28.0 release notes for the complete list.

Existing themes continue to work with sections, theme settings, and JSON templates. This preview adds a Liquid-first composition model alongside the existing theme architecture.

To try it, create a development store with the Liquid July ’26 developer preview. Start with the skeleton theme release candidate, or add the new tags to your own theme.

Learn more by reading the developer preview overview, {% block %} reference, and {% partial %} reference. Share feedback in the Shopify developer community.

For app developers, building merchant-facing analytics has always meant standing up your own stack: a charting library, a data warehouse to sync merchant data into, handling currencies and locales, and a UI that never quite matched the Shopify admin. With these updates, Shopify Analytics becomes a full-stack analytics platform that apps can build on directly, offloading the infrastructure to Shopify and putting your app's data where merchants already make decisions.

Here's what shipped, and how it fits together.

Bring your app's data into Shopify Analytics

Metafields

Mark a metafield definition as analytics-queryable, and it becomes a dimension in ShopifyQL alongside store data. Add, for example, a campaign_source metafield to an order or a subscription_status metafield to a customer. Merchants can group, filter, and chart on it—no ETL, no separate schema.

FROM sales
  SHOW total_sales
  GROUP BY order.metafields.my_app.campaign_source
  TIMESERIES day
VISUALIZE total_sales

App Events (early access)

App Events in Analytics makes the custom events your app already emits queryable in Shopify Analytics. Declare events from the new registry in shopify.app.toml, emit them through the App Events API, and merchants can query FROM app_events in ShopifyQL the same way they query their store data.

FROM app_events
  SHOW emails_sent
  GROUP BY app_name
  TIMESERIES day
VISUALIZE total_sales

Query it: ShopifyQL API + dev docs

The ShopifyQL API, Shopify's analytics query layer, is now a first-class part of the platform, with schema-level reference documentation on shopify.dev. Every metric and dimension is defined in the docs with its type, description, and working examples.

Why it matters:

• For developers: Build against a stable, versioned, schema-documented surface.
• For LLMs and agents: Public schema docs mean AI toolchains can generate working ShopifyQL.

Embed it: Analytics Web Components

The same web components that render analytics in the Shopify admin— the metric card (<s-shopifyql-metric-card>), the metrics bar (<s-metrics-bar>), and its date picker (<s-metrics-bar-date-picker>)—are now available for third-party apps to embed. Render a chart with a single element:

<s-shopifyql-metric-card
  heading="My weekly sales"
  query="FROM sales SHOW total_sales TIMESERIES week VISUALIZE total_sales TYPE bar">
</s-shopifyql-metric-card>

Load analytics-ui.js (after polaris.js), enable Direct API access, then drop in the element. No charting library. No currency or locale handling. No data-formatting code. The component runs the query, renders the chart, and stays in sync with the Shopify admin.

Enrich it: Annotations API + Metric Targets API

Two new APIs let apps and merchants add context on top of the numbers.

Annotations API

Partner apps can now create annotations directly on merchant charts through the GraphQL Admin API. Loyalty apps can mark the day a program launched; email apps can mark a new campaign; subscription apps can mark a pricing change—with proper app attribution rendered in the chart panel.

Required scopes: read_analytics_annotations, write_analytics_annotations.

Metric Targets API

Merchants can now set targets on any metric—total sales next quarter, ad-attributed revenue this week—and track progress visually inside reports and dashboards. Targets are a new core primitive in the GraphQL Admin API, so apps can create, read, and overlay them on charts programmatically.

How it fits together

1. Model your data with Metafields (and App Events, in early access).
2. Query with the ShopifyQL API.
3. Embed with Analytics Web Components.
4. Enrich with Annotations and Metric Targets.

All inside Shopify, where merchants already make decisions.

Get started

• Analytics for Developers
• Metafields
• App Events in Analytics — Sign up for early access
• ShopifyQL API
• Web Components
• Annotations API
• Metric Targets API

The physical inventory feature preview gives you early access to a new set of inventory APIs in the unstable version of the GraphQL Admin API. Enable it on a development store to build and test against the core primitives merchants use to organize a stockroom: bins, counts, and purchase orders.

Because these APIs are under active development, they're available behind a feature preview. This lets you start building early and provide feedback on the schema and behavior before the APIs become stable.

What's included

• Bins. Named storage locations within a location, such as a shelf or rack. Create and update bins, and read the on-hand quantities held in each one.
• Counts. Set the on-hand quantity of an inventory item in a specific bin with the inventoryCountCreate mutation.
• Purchase orders. Read purchase order data through the GraphQL Admin API, including the purchase order, its line items, and its supplier.

How to enable it

1. Create a development store or use an existing one.
2. Enable the Physical inventory feature preview on that store.
3. Configure your app to use the unstable version of the GraphQL Admin API for all physical inventory queries and mutations.

Only stores with the feature preview enabled can call these APIs; calls from stores that haven't enabled the preview return an access error.

For examples and details on how bins integrate with your existing location inventory, see the Physical inventory feature preview guide.

Shopify's card-deposit endpoint now requires a Shopify-issued mTLS client certificate. Apps that store cardholder data with the customerPaymentMethodCreditCardCreate and customerPaymentMethodCreditCardUpdate GraphQL Admin API mutations must first deposit that data at Shopify's /sessions card-deposit endpoint to receive a session identifier. That deposit call must present a Shopify-issued certificate by October 15, 2026. This is a required change: after enforcement begins, deposit requests will be required to have a valid certificate. If your app deposits cardholder data, you must update.

What changed

The card-deposit endpoint at https://checkout-mtls.pci.shopifyinc.com/sessions is unchanged. What's new is that every request to it must present a Shopify-issued mTLS client certificate. Previously, requests to this endpoint did not require a client certificate.

The GraphQL Admin API vault mutations are unchanged. You continue to call customerPaymentMethodCreditCardCreate and customerPaymentMethodCreditCardUpdate with the session identifier returned by the deposit call, and your GraphQL Admin API OAuth flow is unaffected.

customerPaymentMethodRemoteCreate is out of scope. It imports references to payment methods already held at external gateways and deposits no cardholder data to Shopify.

Who's affected

This applies to apps that deposit cardholder data to Shopify through customerPaymentMethodCreditCardCreate or customerPaymentMethodCreditCardUpdate.

Apps that only call customerPaymentMethodRemoteCreate to import payment methods from external gateways such as Stripe, Braintree, Authorize.Net, Adyen, or PayPal are not affected and need to take no action.

Why this matters

All cardholder-data traffic reaching the deposit endpoint must be attributable to an authenticated caller. Requiring a client certificate lets Shopify verify who is depositing card data ahead of Black Friday and Cyber Monday 2026, and is the prerequisite for rejecting unauthenticated deposit traffic.

What to do

If your app deposits cardholder data, migrate before October 15, 2026:

1. Confirm whether your app calls customerPaymentMethodCreditCardCreate or customerPaymentMethodCreditCardUpdate. If it only calls customerPaymentMethodRemoteCreate, no action is required.
2. Request a Shopify-issued client certificate at shopify-mtls-partnerships@shopify.com. Include your API client ID and technical point of contact. First certificates are signed manually by Shopify and take a few days, so start early.
3. Present the certificate on your /sessions deposit call, and continue passing the returned session identifier to the vault mutations unchanged.
4. Confirm your deposit traffic now arrives with a valid certificate. Shopify validates the cutover on our side.

After your first certificate, rotate it self-serve with Shopify's Certificate Signing Service before the 1-year TTL expires . No Shopify involvement is needed. A missed rotation stops your deposits, so monitor certificate expiry as part of your standard observability.

Apps that haven't migrated by October 15, 2026 lose the ability to deposit new cardholder data once the certificate requirement is enforced.

Related docs

• customerPaymentMethodCreditCardCreate reference
• customerPaymentMethodCreditCardUpdate reference

Your app's name is what merchants use to discover, identify, and remember your app. We've added requirement 4.1.2, "Use a unique name for your app," to reduce merchant confusion over identical and copycat app names in Shopify’s App Store.

We know that changing an app name isn't easy — it affects your brand, your discoverability, and your existing merchants. That's why this requirement establishes the standard now, while enforcement will roll out gradually. Affected apps will be audited in waves and given a designated timeframe to achieve compliance.

What's changing

This requirement gives Shopify the ability to act on app name violations. Non-compliant apps will be notified and given a defined timeframe to update their names where failure to comply may result in being delisted from the App Store. Enforcement actions will roll out gradually, so affected developers will have time to plan and make changes.

What this means for you

• If you believe your published app violates this policy: Start considering a plan to rename your app to get ahead of enforcement actions. Ensure that your app name starts with your distinctive brand identifier and does not mislead merchants in confusing it with another app, developer, brand, or Shopify product.
• If you're submitting a new app: Choose a distinct name that represents your own brand. Don't impersonate other apps or mislead merchants with your app name.
• If your app name is being copied: At this time, we can only accept reports with a valid registered trademark. If your app trademark is being copied, you can submit a report to Shopify.

As of Storefront API version 2026-10, the @inContext directive accepts an optional channelId argument. Use channelId to apply a specific sales channel’s context to an entire query, including channel-specific product availability and pricing.

Example:

query Product($handle: String!, $channelId: ID!)
  @inContext(channelId: $channelId) {
  product(handle: $handle) {
    id
    title
    availableForSale
    priceRange {
      minVariantPrice {
        amount
        currencyCode
      }
    }
  }
}

Why it's changing

The existing @inContext directive lets you set buyer context such as country and language. With channelId, you can now:

• Target a specific channel (for example, a marketplace or custom sales channel) when fetching products, prices, and availability.
• Build channel-aware storefronts that show the correct catalog, pricing, and merchandising rules for each channel.
• Reduce custom logic in your app by relying on the API to apply channel-specific behavior.

Requirements

Access requirement: You can only pass the ID of a channel created by the API client making the request.

Fallback behavior: If you omit channelId, the Storefront API uses the first channel owned by that API client. Pass channelId explicitly when your app owns multiple channels or needs to select a specific channel.

Learn more about contextual queries.

Starting with POS UI Extensions API version 2026-07, product bundle components in cart line item data include discount allocation details.

Apps can access component-level discount allocations from bundle components on a cart line item, for example:

shopify.cartLineItem.components?.[0]?.discountAllocations

The same LineItem shape is also used in Cart API cart state, so apps that read line items from shopify.cart.current.value.lineItems can access component discount allocations on bundle components there as well.

Previously, POS UI Extensions exposed discount allocations on the parent line item through lineItem.discountAllocations, while bundle components exposed component-level tax information but not component-level discount allocations. This made it difficult for apps to calculate component-level discount, tax, reporting, or compliance values for discounted product bundles.

This change is additive. Apps using API version 2026-04 or earlier do not need to make any changes.

Apps adopting API version 2026-07 can use components[].discountAllocations when working with discounted product bundles. Apps should handle the property being absent or empty when a bundle component has no discount allocations.

For more information, see the [Cart Line Item API reference](https://shopify.dev/docs/api/pos-ui-extensions/2026-07-rc/target-apis/contextual-apis/cart-line-item-api#cartlineitemapi- propertydetail-cartlineitem) and the [Cart API current property](https://shopify.dev/docs/api/pos-ui-extensions/2026-07-rc/target-apis/contextual-apis/cart-api#cartapi-propertydetail-curr ent).

The pos.app.ready.data target runs for the entire POS session, letting your extension observe POS events and run background logic without rendering any UI surface. Use it for event observation, data storage, and calling non-visual background APIs.

What you need to do

Subscribe to Shopify POS events with shopify.addEventListener():

shopify.addEventListener('transactioncomplete', (event) => {
  console.log('Transaction complete', event);
});

Supported events

Supported events include:

• transactioncomplete
• cashtrackingsessionstart
• cashtrackingsessioncomplete

For comprehensive details and best practices, refer to the app background target documentation.

Trust is foundational to the Shopify Partner ecosystem. Partners take actions across Shopify that can directly affect merchants, and merchants need confidence when granting access to their stores. We’re introducing identity verification for partners to help protect merchants, reduce abuse, and make it harder for bad actors to operate, while creating a better experience for legitimate partners.

What changed

Starting today, Shopify Partners can complete identity verification before requesting collaborator access to merchant stores. Identity verification is optional today and will become mandatory in the coming weeks before sending a new collaborator request.

For this launch:

• Identity verification applies to sending new collaborator requests. Every user in your partner organization sending a new collaboration will need to verify their identity.
• Identity verification isn’t required just to access collaborator shops where a merchant has already granted access.
• Verification is completed through Stripe and requires a government-issued photo ID and a selfie or liveness check.

We’re starting with collaborator requests because collaborator access is one of the clearest trust moments between merchants and partners. When a merchant approves a collaborator request, they’re giving a partner access to a live store.

Action required

If you or anyone in your partner organization sends collaborator requests, complete identity verification on the Request collaborations page in the Dev Dashboard.

Identity verification is optional today, but we recommend completing it now to avoid interruption when it becomes mandatory in the coming weeks. After enforcement begins, unverified users won’t be able to send new collaborator requests until they complete verification.

To prepare:

• Complete identity verification before sending new collaborator requests.
• Make sure every user in your partner organization who requests collaborator access verifies their own identity.
• Have a government-issued photo ID ready, along with access to a device that can complete a selfie or liveness check.
• Review the related docs below for more context on identity verification and collaborator access.

Related docs

• Verifying your identity as a Shopify Partner
• Collaborator requests: Information shared with merchants

The Hydrogen developer preview adds new capabilities to the toolkit and extends the ways developers can build Shopify storefronts:

• Storefront API caching for catalog data: Cache products, collections, and pages at the edge instead of hitting the Storefront API on every request.
• WebMCP tools for in-browser AI agents: Expose your storefront to in-browser AI agents so they can search the catalog, browse products, and manage the cart. Loads automatically from Shopify's CDN, no extra integration required.
• Customer Account API support: Build logged-in experiences like order history and profile pages with a typed client that handles login, token refresh, and logout.
• Same-origin predictive search: Add autocomplete search that runs through your own server instead of calling the Storefront API from the browser.
• Typed routes and redirects: Describe your URL structure once and reuse it for redirects, predictive-search URLs, and Shopify-standard resource mapping.
• ShopifyScripts for the Shopify browser runtime and unified cart route handling: Render Shopify's standard script tags and browser runtime in one place, and handle cart routes through a single registration that works the same across frameworks.

To get started, visit the Hydrogen developer preview documentation. For a detailed breakdown of this release, read the full release notes.

We’ve made several updates to App Pricing:

Increased plan limits: You can now create up to 8 public plans (previously 4) and 15 private plans (previously 10) per app.

No-charge plan testing: Test app billing flows without generating real charges:

• During app review, reviewers can now select any of your existing plans, so you no longer need to create a dedicated test plan.
• In development stores, you can install your own apps and subscribe to any plan at no cost.
• Mark a plan as free to let other partners and developers install your app and test that plan in their own development stores.

Additional App Events support: The App Events API now accepts:

• Negative values, to adjust or credit previously reported event usage
• Fractional values, such as 1.5

Previously, event values were limited to whole numbers greater than 0.

For more details, see App pricing and the App Events API reference.

Starting with POS UI extensions API version 2026-07, FixedAmount line item discounts passed to setLineItemDiscount and bulkSetLineItemDiscounts from the Cart API must represent a per-unit discount.

Why it's changing

In API version 2026-04 and earlier, apps could pass a total fixed discount for the entire line item, and Shopify POS automatically converted it to a per-unit value. In API version 2026-07, this conversion no longer occurs. The value you pass is interpreted directly as the discount applied to each unit in the line item.

For example, in API version 2026-07, if you pass '5.00' on a line item with quantity 2, POS applies a $5.00 discount to each unit, for a $10.00 total discount. To apply a $5.00 total discount to a line item with quantity 2, you must instead pass '2.50' as the per-unit discount.

What you need to do

This change only affects FixedAmount line item discounts. Percentage discounts are not affected. Apps using API version 2026-04 or earlier do not need to make any changes.

Apps adopting API version 2026-07 must update their discount calculations before using the new version. If your app currently calculates discounts as a total line discount, compute the per-unit discount before calling setLineItemDiscount or bulkSetLineItemDiscounts — for example, by dividing the total discount by the line item quantity.

If the total discount does not divide evenly by the line item quantity, choose a rounded per-unit value that matches your app’s intended discount behavior and ensures the final discount is consistent with your logic.

For more information, see the Cart API reference.

Developers using the Billing API can now begin preparing their apps to move to Shopify App Pricing. The first part of our migration tool lets you generate, review, edit, and test Shopify App Pricing plans before moving any existing merchant subscriptions. This gives you time to confirm that your pricing configuration is ready while your app continues using its current billing setup.

Shopify App Pricing provides a standardized pricing experience across the Shopify App Store, plan selection, subscription management, and merchant billing.

Generate your App Pricing plans

In the Pricing Details of your app's listing in Partner Dashboard click manage. You'll see the migration tool above your list of plans. The tool automatically creates App Pricing draft plans from your eligible manual plans. Plans that are missing App Pricing required fields, like usage charges, are marked with an Action needed badge.

Review and test your configuration

After your public and private plans are drafted, you can:

1. Review the generated plan names prices, features, and billing intervals.
2. Edit plans or create additional plans as needed.
3. Configure usage charges and app events for usage-based pricing.
4. Test the plans on a development store owned by the same Partner organization as your app.
5. Review your plans using the readiness checklist

Preparing plans in the tool doesn't migrate your existing shops or subscriptions. Merchants don't need to take action during this stage. For detailed instructions, plan-generation behavior, limitations, and testing requirements, read the Shopify App Pricing migration guide.

Coming next: move existing subscriptions

This release is the first part of the manual billing migration tool. In the coming days, we'll be inviting partners to preview the next part of the tool for moving existing shops and subscriptions to your Shopify App Pricing plans. If you'd like to join this Early Access preview, enter your information on this form.

Your server-side code now has more control over how breaking changes to an action’s configuration fields are handled. Instead of failing validation when there’s a field mismatch, workflows that use older versions of an action will continue to execute, and Shopify will still send the request to the configured endpoint URL. Your server can then decide how to handle schema differences: for example, it can set default values for new required fields, ignore fields that were removed, or reject the request.

Why it’s changing

Previously, any change to an action’s configuration fields was treated as a breaking change in merchant workflows. Runtime validation would fail, and Shopify wouldn’t send the request to the partner server. For example, if a new required field was added or an existing field was removed, any workflows using an older version of that action would always fail and never reach your endpoint.

With this change, those workflows continue to run, and your endpoint receives the request even when the payload is based on an older configuration.

What you need to do

Your action’s endpoint may now receive payloads that don’t exactly match the action’s current configuration, but instead match a previous version that merchants are still using in their workflows. Make sure your endpoint can safely handle:

• Missing fields that have become required in newer versions
• Extra fields that existed in older versions but have since been removed
• Any other unexpected fields or schema differences

Typical strategies include applying sensible defaults for missing fields, ignoring unknown or legacy fields, or returning a clear error response when the payload can’t be processed safely.

For more details on how requests are sent and executed, see Flow action execution.

Shopify Flow now resolves an action’s runtime_url on every execution. When the runtime_url is changed and the app is redeployed, the new URL is automatically used by existing workflows the next time they run. Merchants no longer need to edit or re-save their workflows to use the updated URL.

During local development, when you use shopify app dev, the runtime_url is also updated automatically in any development shops that have workflows using the action. This mirrors the behavior in production.

Why it’s changing

Previously, the runtime_url for a Shopify Flow action was hard-coded into the workflow at the time it was activated. As a result, changes to an extension’s runtime_url only took effect after a merchant reactivated (re-saved) the affected workflow. Because merchants might not do this frequently, existing workflows could continue calling an outdated runtime_url.

What you need to do

No action is required. However, if you previously relied on an action’s runtime_url remaining fixed for a workflow until it was reactivated, be aware that updates now propagate to existing workflows automatically.

For more details, see Create Flow action endpoints.

All apps published to Shopify’s App Store are subject to policy 1.3 “Always use honest and transparent review practices”.

What’s changing: The Shopify App Store requirements policy 1.3 further clarifies our enforcement on the existing Partner Program Agreement Section C.2.1 about reviews in Shopify’s App Store.

• Incentivizing reviews: While incentivizing reviews has always been against policy, we’re further clarifying how we enforce it. Developers found to be incentivizing reviews may face consequences such as the removal of a portion of reviews, demotion or delisting of your app, or termination of your Partner account.
• Review trust: We're making adjustments to our logic to evalulate reviews. Going forward, only reviews that meet our trust standards will appear publicly. Reviews that don’t meet this standard will be unpublished, and may be published automatically once they meet the standards.

Please make sure your app is in compliance by:

• Using the Reviews API when possible to collect authentic reviews from your users
• Asking for reviews only in neutral language. Offering any incentives within or outside the app is not allowed.

To learn more, see the Shopify App Store Requirements.

Reviews on the Shopify App Store are foundational to a fair marketplace. They're how merchants find the right apps, and how developers earn trust for the products they build. Reviews are one of the most important ways merchants decide which apps to trust. To keep that signal honest, we're making two changes to how we handle review incentivization and untrusted reviews. We're announcing both together. Here's what Partners need to know.

1. A dedicated policy on review incentivization

What it is: Offering, unlocking, or withholding app features in exchange for a merchant leaving a review.

What's changing: Rules on this practice previously lived within the Partner Program Agreement, which made them easy to overlook. We're introducing a dedicated App Store requirement on review incentivization with clear consequences.

The consequence: When an app is found to be incentivizing reviews, we'll remove a significant portion of its reviews. We've already identified apps engaged in this practice, and we'll be enforcing this policy as soon as the change goes live.

2. Stronger untrusted review detection

What it is: Reviews that don't come from genuine users of an app. These are posted to inflate an app's ranking or to harm a competitor's.

What's changing: We're expanding the set of signals we use to determine whether a review is authentic. Because we're applying these signals to existing reviews as well as new ones, a meaningful number of reviews that don't meet our authenticity bar will be unpublished over the coming weeks.

What to expect: Because untrusted reviewers often leave reviews across many listings to appear more legitimate, some genuine apps might see reviews unpublished too. This isn't a reflection of wrongdoing on your part, but it's a result of removing the untrustworthy activity connected to those reviews. Our goal is to ensure that the reviews that remain carry more weight. Unpublishing will roll out gradually as the backfill completes.

Why now

As the Shopify App Store grows, so does our responsibility to protect it. Untrusted and incentivized reviews undermine the trust merchants place in the review systems, and they create an uneven playing field for developers who play by the rules. A trustworthy App Store benefits everyone who builds honestly. These changes make our standards clearer, our enforcement more consistent, and the reviews merchants rely on more genuine.

What you should do

As you collect reviews, make sure you're doing so honestly and fairly. These are some best practices we recommend:

• Use the Reviews API to request reviews from merchants who actually use your app.
• Ask in neutral language at the right moment. A simple "How's your experience? Leave a review" after the merchant has used your app is fine. Offering anything in return is not.
• Reply to negative reviews instead of trying to bury them. Merchants value developers who engage with feedback.

Reach out to Support with any concerns or if you feel that trusted reviews have been removed.

What's next

This is the start of a broader investment in App Store quality. We're continuing to improve automated detection, strengthen policy enforcement, and strengthen the overall health of a trustworthy ecosystem.

The Shopify App Store should be a place where the best apps win. That's what we're building toward.

As of Customer Account API version 2026-10, the deprecated Customer.lastIncompleteCheckout field is removed.

This also removes the now-unreachable Customer Account API Checkout type subtree, including:

• Checkout
• Checkout.appliedGiftCards
• AppliedGiftCard
• AvailableShippingRates
• CheckoutLineItem
• CheckoutLineItemConnection
• CheckoutLineItemEdge
• ShippingRate

The Customer.lastIncompleteCheckout field was previously deprecated and returned null. This change removes stale Checkout Classic schema from the Customer Account API.

Action required

If your app queries Customer.lastIncompleteCheckout or any nested fields on the returned Checkout object, update your queries before upgrading to API version 2026-10.

Remove selections such as:

customer {
  lastIncompleteCheckout {
    id
    appliedGiftCards {
      id
    }
  }
}

There is no replacement field in the Customer Account API.

If you need active cart or checkout state for a buyer storefront experience, use Storefront API cart flows instead. If you need completed customer purchase history, use the Customer Account API Customer.orders field.

Sub-region Markets are available in the Admin GraphQL API 2026-07

Apps using Admin GraphQL 2026-07 can encounter Markets configured with country-subdivision regions, such as states and provinces as merchants upgrade to market-driven shipping. Apps can get more informtion about market-drive shipping feature preview shipping upgrade guide

Use MarketRegionSubdivision as the stable country-subdivision region type, and read sub-region membership through market.conditions.regionsCondition.regions. Do not use deprecated market.regions as the source of truth for sub-region membership, because it may omit subdivision regions.

Sub-region Markets support shipping first. Other configurations including Discounts, Catalogs, Theme contextualization, Market metafields, are not yet supported. Unsupported API paths will return validation errors instead of allowing unsupported configurations.

As of API version 2026-10, the OrderDisplayFulfillmentStatus enum can return a new value: FULFILLMENT_NOT_REQUIRED. It is returned for orders that are not fulfilled but have no items remaining to fulfill — for example, an order that was fully cancelled or fully refunded before any items were fulfilled. Previously, these orders returned UNFULFILLED.

This is a backward-compatible, additive change: integrations that already handle unrecognized enum values gracefully don't need to do anything. As with all GraphQL enums, treat the set of values as open — new values may be added in future versions.

What's changing

• Order.displayFulfillmentStatus (and any field typed as OrderDisplayFulfillmentStatus) may return FULFILLMENT_NOT_REQUIRED on API version 2026-10 and later.
• This value represents an order whose remaining fulfillable quantity is zero — for example, all line item quantities were removed through order edits, or the order was closed by cancellation.
• API versions earlier than 2026-10 are unchanged and continue to return UNFULFILLED for these orders.

Why The UNFULFILLED status was misleading for orders that have nothing left to fulfill. FULFILLMENT_NOT_REQUIRED makes the order's true state clear to merchants and to the apps that read it.

What you may need to do

• If your app exhaustively maps OrderDisplayFulfillmentStatus values (switch statements, status-to-label/badge maps, or generated types), add handling for FULFILLMENT_NOT_REQUIRED when you adopt 2026-10.
• If your app branches on or filters by UNFULFILLED, note that orders with no fulfillable items report FULFILLMENT_NOT_REQUIRED instead on 2026-10 and later.

Starting in version 2026-07, the useBuyerJourneyIntercept hook on checkout UI extensions, and the block_progress capability it depends on, are deprecated. Existing extensions will continue to work on current and prior API versions, but this API will be removed in a future version, so you should plan to migrate.

The following are deprecated:

• useBuyerJourneyIntercept (Preact hook) in checkout UI extensions
• The block_progress capability in the extension’s shopify.extension.toml configuration file

If you currently use useBuyerJourneyIntercept to enforce merchant business rules, migrate to a cart and checkout validation Function. These Functions run server-side and apply your rules consistently across all checkout surfaces, including express wallets and agentic checkout.

If you use useBuyerJourneyIntercept to reject discount codes, migrate that logic to the discount Function API, which now supports rejecting discount codes with a custom message.

To learn more and if you've got a use case that's keeping you from moving to Shopify Functions: https://community.shopify.dev/t/the-buyer-journey-intercept-api-is-now-deprecated/35930.

New Features

Product variant intents

The React SDK added typed product variant intent hooks for selecting variants, adding variants to cart, and sending buyers to express checkout:

• useSelectVariant wraps select:shopify/ProductVariant.
• useAddToCart wraps add_to_cart:shopify/ProductVariant.
• useBuyNow wraps buy_now:shopify/ProductVariant.

These hooks can open the native Shop variant selector sheet over the Mini WebView when a Mini has a product ID but needs the buyer to pick a variant or quantity. Results distinguish successful actions, user dismissal, host errors, navigation to PDP, and referral-product handoffs.

Usage:

const {addToCart} = useAddToCart()

const result = await addToCart({productId})

if (result.code === 'ok') {
  switch (result.data.outcome) {
    case 'added_to_cart':
      break
    case 'navigated_to_product':
      break
    case 'redirected_to_product':
      break
  }
}

Build verification during submit

The CLI now runs Minis build verification as part of submit. The verification system was also split into per-check orchestration with human-readable progress and JSON output support. Current checks cover dependency validation, ESLint disables, ESLint, TypeScript, build output, and manifest validation.

Scoped hook setup warnings

The CLI now warns when a Mini uses scoped SDK hooks before completing the required setup. This gives partners earlier feedback when code uses features that depend on declared scopes or account setup.

Market-driven shipping moves merchant-owned shipping configuration out of delivery profiles and into Markets. Merchants will attach shipping options directly to each market, and then vary rates by product and location conditions within a single option. This makes checkout rate behavior more predictable and easier to understand.

What this means for your app:

• Merchant shipping configuration (today’s merchant delivery profiles) moves from the delivery profile API to the Markets API.
• App delivery profiles (delivery profiles created by apps) keep using the delivery profile API.
• App-provided rates (rates defined within app delivery profiles) still appear alongside merchant rates in the new experience.
• App delivery profiles are getting more powerful: they can now target all products instead of just a subset, and adding a product to an app profile will no longer impact the merchant configuration.
• If your app reads, creates, or updates merchant shipping settings through the delivery profile API, you’ll need to update it. Market-driven shipping will start rolling out to merchants on October 1, 2026, and all merchants will be on it by July 1, 2027.

The feature preview is available today. Create a new development store, enable the feature preview, and validate your existing integration and rate logic.

To learn how market-driven shipping works and how to upgrade your app see Market-driven shipping feature preview.

As of the 2026-07 API version, draft order deposit fields are available in the GraphQL Admin API and Customer Account API.

Apps can now set a deposit when creating or updating a draft order with DraftOrderInput.deposit in the GraphQL Admin API. This supports draft order flows where part of the payment is due at checkout and the remaining balance is due later, such as due-on-fulfillment payment terms.

The Customer Account API also exposes read-only deposit information on draft orders, including the amount due now and the amount due later.

This feature is available to Shopify Plus stores.

The isCumulative argument to the marketingEngagementCreate mutation is being deprecated, defaulting to false. Please update your integration to send non-cumulative engagements, as needed. Existing activities that have been sending cumulative metrics can migrate to non-cumulative at any time.

As of GraphQL Customer Account API version 2026-07, draft orders now expose discount applications.

You can use the new discountApplications field on DraftOrder to query discounts applied to a draft order, and the new discountAllocations field on DraftOrderLineItem to query how discounts are allocated across line items.

For example:

   query DraftOrderDiscounts($id: ID!) {
     draftOrder(id: $id) {
       discountApplications(first: 10) {
         nodes {
           __typename
           ... on DiscountCodeApplication {
             code
           }
           ... on ManualDiscountApplication {
             title
           }
           allocationMethod
           targetSelection
           targetType
           value {
             ... on MoneyV2 {
               amount
               currencyCode
             }
             ... on PricingPercentageValue {
               percentage
             }
           }
         }
       }
       lineItems(first: 10) {
         nodes {
           title
           discountAllocations {
             allocatedAmount {
               amount
               currencyCode
             }
             discountApplication {
               __typename
             }
           }
         }
       }
     }
   }

Use these fields to understand which discounts apply to a draft order and how those discounts affect individual draft order line items.

The discountedUnitPrice field on the DraftOrderLineItem object in the Customer Account API is now deprecated.

Use approximateDiscountedUnitPrice instead. This new field calculates the discounted total divided by the quantity, resulting in an approximate per-unit price reduction. Update your queries to use approximateDiscountedUnitPrice.

As of API version 2026-07, the BusinessEntity type in the GraphQL Admin API includes a new legalEntityId field. This field returns the stable Central Legal Entity ID from Shopify's Organizations Platform, giving Partners a consistent identifier for the same legal entity across multiple shops, markets, and sales channels.

What's new

The BusinessEntity type now includes:

• legalEntityId (BigInt, nullable): The stable organization-level legal entity identifier. This ID is consistent across all shops belonging to the same legal entity, enabling partners to recognize the same underlying company regardless of how many shops or markets it operates.

This field returns null when the business entity has no backing Central Legal Entity or when the legal entity does not have a stable external ID.

Example query

query {
  businessEntity(id: "gid://shopify/BusinessEntity/123456") {
    id
    legalEntityId
    companyName
    displayName
  }
}

Example response

{
  "data": {
    "businessEntity": {
      "id": "gid://shopify/BusinessEntity/123456",
      "legalEntityId": "223432432",
      "companyName": "Acme Corporation",
      "displayName": "Acme US"
    }
  }
}

Why this matters

Previously, BusinessEntity.id was scoped to individual shops, meaning the same company operating multiple shops would appear with different IDs. The new legalEntityId provides a single, stable identifier at the organization level that Partners can use to:

• Map a merchant's legal entity to a company code in their own systems
• Consistently identify the same company across multiple shops and markets
• Correlate legal entity data between the GraphQL Admin API and tax webhook payloads (where the same identifier appears as merchant_business_entity.legal_entity_id)

API version

This field is available starting in API version 2026-07 and in unstable.

What's changing

We’re moving merchant-owned shipping configuration from legacy delivery profiles to Markets as part of market-driven shipping, a new model where shipping is configured per Market.

When a shop uses market-driven shipping, the legacy delivery profile fields and mutations in the Admin GraphQL API no longer represent the shop’s live merchant-owned shipping configuration. Reads may return a stale snapshot of the legacy configuration, and writes may succeed without errors but will not update the merchant’s live shipping settings.

This affects merchant-owned usage of the following Admin GraphQL delivery profile APIs:

• deliveryProfile
• deliveryProfiles
• deliveryProfilesCount
• deliveryProfileLocationGroup
• deliveryProfileLocationGroups
• deliveryProfileCreate
• deliveryProfileUpdate
• deliveryProfileRemove

App-owned delivery profiles aren’t affected and continue to function as before.

What to do

If your app currently reads or manages merchant-owned shipping configuration, you must follow the upgrade guide for market-driven shipping. The guide explains how to:

• Detect shops that are using market-driven shipping.
• Stop relying on merchant-owned delivery profile APIs for those shops.
• Migrate to Contextual Product Feeds, app-owned delivery profiles, or Markets APIs, depending on your use case.

Starting in API version 2026-07, the GraphQL Admin API supports market-driven shipping configuration. You can now configure shipping directly on a market, which helps apps support different shipping strategies for different markets without creating a separate shipping profile resource.

What changed

The Market object now includes a delivery field for market delivery settings. Use Market.delivery.shipping to read the shipping configuration for a market.

Use the existing marketCreate and marketUpdate mutations to create, update, or remove a market's shipping configuration:

• Use MarketCreateInput.delivery.shipping to add shipping configuration when creating a market.
• Use MarketUpdateInput.delivery.shipping to update shipping configuration on an existing market.
• Use MarketUpdateInput.delivery.removeShipping to remove a market-level shipping configuration so the market inherits shipping from its parent.

Shipping options are managed through DeliveryOptionDefinitionCreateInput and DeliveryOptionDefinitionUpdateInput. The API supports these option types:

• DeliveryFlatRateOptionDefinition for fixed-price shipping options.
• DeliveryValueBasedOptionDefinition for rates based on cart value.
• DeliveryWeightBasedOptionDefinition for rates based on package weight.
• DeliveryCarrierCalculatedOptionDefinition for rates calculated by carrier services.

Each shipping option includes fields such as currency and isActive. You can optionally configure a free delivery threshold with freeDeliveryMinimumValue. Flat and value-based options can include one or more rate groups. Weight-based options include exactly one weight-based rate group, and carrier-calculated options include a single carrier-calculated rate group.

What you can do

• Configure shipping options for a specific market.
• Offer different flat, value-based, weight-based, or carrier-calculated rates by market.
• Restrict rate groups to specific product collections or origin locations.
• Unconfigured markets naturally inherit shipping from their parents.
• Disable shipping for a market by setting isEnabled to false.

What you need to know

• Queries require read_markets access.
• Mutations require both read_markets and write_markets access.
• A null value for Market.delivery.shipping means the market inherits shipping from its parent. For markets without a parent, shipping inherits the shop default of no shipping
• isEnabled: false means customers in that market will not see shipping options at checkout. This also disables any app managed shipping options that may otherwise apply to this market.
• There are no root queries or standalone mutations for market shipping configuration. Read and write shipping configuration through Market, marketCreate, and marketUpdate.

Example query

This query reads a market's shipping configuration, including whether shipping is enabled, how many active shipping options are configured, and the details for each flat-rate option.

{
  market(id: "gid://shopify/Market/123") {
    delivery {
      shipping {
        isEnabled
        activeOptionDefinitionsCount {
          count
        }
        optionDefinitions(first: 10) {
          nodes {
            __typename
            currency
            isActive
            freeDeliveryMinimumValue {
              amount
              currencyCode
            }
            ... on DeliveryFlatRateOptionDefinition {
              name
              rateGroups(first: 10) {
                nodes {
                  conditions {
                    collectionsCount {
                      count
                    }
                    originLocationsCount {
                      count
                    }
                  }
                  rate {
                    price {
                      amount
                      currencyCode
                    }
                    transitTimeMinSeconds
                    transitTimeMaxSeconds
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Example mutation

This mutation updates an existing market with shipping enabled and adds a standard flat-rate shipping option with a fixed price and estimated transit time.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        shipping: {
          isEnabled: true
          optionDefinitionsToCreate: [
            {
              flatRate: {
                name: "Standard Delivery"
                currency: USD
                rateGroups: [
                  {
                    rate: {
                      price: { amount: "5.99", currencyCode: USD }
                      transitTimeMinSeconds: 432000
                      transitTimeMaxSeconds: 604800
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ) {
    market {
      id
      delivery {
        shipping {
          isEnabled
          optionDefinitions(first: 10) {
            nodes {
              __typename
              currency
              isActive
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Example: Disable shipping for a market

Use isEnabled: false when the market should keep its market-level shipping configuration, but not show shipping options at checkout.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        shipping: {
          isEnabled: false
        }
      }
    }
  ) {
    market {
      id
      delivery {
        shipping {
          isEnabled
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Example: Remove market-level shipping configuration

Use removeShipping: true when the market should inherit shipping from its parent instead of using its own shipping configuration.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        removeShipping: true
      }
    }
  ) {
    market {
      id
      delivery {
        shipping {
          isEnabled
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Example: Add a value-based shipping option

This mutation creates a shipping option where the rate depends on cart value.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        shipping: {
          optionDefinitionsToCreate: [
            {
              valueBased: {
                name: "Cart Value Shipping"
                currency: USD
                isActive: true
                rateGroups: [
                  {
                    rates: [
                      {
                        price: { amount: "9.99", currencyCode: USD }
                        minValue: { amount: "0.00", currencyCode: USD }
                        maxValue: { amount: "49.99", currencyCode: USD }
                      }
                      {
                        price: { amount: "0.00", currencyCode: USD }
                        minValue: { amount: "50.00", currencyCode: USD }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ) {
    market {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Example: Add a weight-based shipping option

Weight-based options uses a similar form but can only take a single rate group. The rate group can contain weight-based rates.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        shipping: {
          optionDefinitionsToCreate: [
            {
              weightBased: {
                name: "Weight-Based Shipping"
                currency: USD
                isActive: true
                rateGroups: [
								  {
                    rates: [
                      {
                        price: { amount: "12.99", currencyCode: USD }
                        minWeight: { value: 0, unit: POUNDS }
                      }
                    ]
                  }
							  ]
              }
            }
          ]
        }
      }
    }
  ) {
    market {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Example: Add a carrier-calculated shipping option

Carrier-calculated options also takes only a single rate group that references an existing carrier service.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        shipping: {
          optionDefinitionsToCreate: [
            {
              carrierCalculated: {
                currency: USD
                isActive: true
                rateGroups: [
								  {
                    carrierServiceId: "gid://shopify/DeliveryCarrierService/987"
                    autoIncludeNewServices: true
                    percentageAdjustment: 10
                  }
							]
            }
          ]
        }
      }
    }
  ) {
    market {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Example: Update an existing flat-rate shipping option

Use optionDefinitionsToUpdate with the option ID. For flat-rate options, you can also update individual rate groups.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        shipping: {
          optionDefinitionsToUpdate: [
            {
              flatRate: {
                id: "gid://shopify/DeliveryFlatRateOptionDefinition/456"
                name: "Standard Delivery"
                isActive: true
                rateGroupsToUpdate: [
                  {
                    id: "gid://shopify/DeliveryFlatRateGroup/789"
                    rate: {
                      price: { amount: "6.99", currencyCode: USD }
                      transitTimeMinSeconds: 432000
                      transitTimeMaxSeconds: 604800
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    }
  ) {
    market {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Example: Delete a shipping option

Use optionDefinitionsToDelete with the shipping option ID.

mutation {
  marketUpdate(
    id: "gid://shopify/Market/123"
    input: {
      delivery: {
        shipping: {
          optionDefinitionsToDelete: [
            "gid://shopify/DeliveryFlatRateOptionDefinition/456"
          ]
        }
      }
    }
  ) {
    market {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Related docs

Core objects and interfaces:

• Market
• MarketDeliveryConfigurations
• ShippingConfiguration
• DeliveryOptionDefinition
• DeliveryFlatRateOptionDefinition
• DeliveryValueBasedOptionDefinition
• DeliveryWeightBasedOptionDefinition
• DeliveryCarrierCalculatedOptionDefinition

Rate groups, rates, and conditions:

• DeliveryOptionDefinitionRateGroup
• DeliveryFlatRateGroup
• DeliveryValueBasedRateGroup
• DeliveryWeightBasedRateGroup
• DeliveryCarrierCalculatedRateGroup
• DeliveryRate
• DeliveryRateGroupConditions

Mutations and inputs:

• marketCreate
• marketUpdate
• MarketCreateInput
• MarketUpdateInput
• MarketDeliveryConfigurationsCreateInput
• MarketDeliveryConfigurationsUpdateInput
• ShippingConfigurationCreateInput
• ShippingConfigurationUpdateInput
• DeliveryOptionDefinitionCreateInput
• DeliveryOptionDefinitionUpdateInput

The Hydrogen developer preview can now be deployed to Vercel in a few clicks. A new Deploy button creates a repo from the Next.js starter template, sets up a Vercel project, and builds it. No local setup required.

The template is a working Hydrogen storefront with the typed Storefront API client, cart, and product and collection pages already wired up. Add your store credentials from the Headless channel to connect your own products. You'll find it in the developer preview docs under "Deploy a starter template," alongside the setup paths for other frameworks and existing projects.

Starting in API version 2026-07, sales channel apps can use order attribution definitions to identify the source that created an order.

Order attribution definitions are useful when your sales channel app needs attribution that is more specific than the app or channel itself. For example, you can attribute orders to a marketplace, region, account, or surface.

Apps that only need default app or channel attribution don’t need to make any changes.

What’s new

Sales channel apps can now:

• Create channel-based attribution definitions when creating channel connections.
• Define static attribution sources with the order_attribution_config extension.
• Create or update attribution definitions with the orderAttributionDefinitionUpsert mutation.
• Query attribution definitions with the orderAttributionDefinitions query.
• Delete attribution definitions with the GraphQL Admin API.
• Pass an attribution definition handle when creating orders with orderCreate.
• Pass an attribution definition handle through source_name when creating carts with the Storefront API cartCreate mutation or when using cart permalinks.
• Read resolved attribution details with Order.attribution.

To use order attribution definitions, your app must be a sales channel app with a channel_config extension.

What you need to do

If your app needs attribution that is more specific than app-level or channel-level attribution, create order attribution definitions and pass the definition handle in sourceName when creating carts or orders.

If sourceName doesn’t match an approved order attribution definition, Shopify falls back to app-only attribution.

Use Order.attribution for new attribution reads. Order.channelInformation remains available, but is deprecated.

In API version 2026-07 and later, the PaymentMandateResource object includes a new id field.

PaymentMandateResource is returned by the mandates connection on CustomerPaymentMethod. Its id is the same as the corresponding CustomerPaymentMethod.id, which lets you determine which payment method to use for a given mandate scope (for example, the SUBSCRIPTIONS scope) when a single payment instrument is associated with multiple mandate types.

Starting with GraphQL Admin API version 2026-10, creating a carrier service no longer automatically adds it to the shop’s General shipping profile.

This breaking change affects carrier services created using:

• GraphQL Admin API: carrierServiceCreate
• REST Admin API: POST /admin/api/{version}/carrier_services.json

Previously, active API carrier services created through these APIs were automatically added to eligible shipping zones in the shop’s General shipping profile. In API version 2026-10 and later, creating a carrier service only registers the carrier service. Shopify no longer adds that carrier service to the General shipping profile or any of its shipping zones by default.

If your app relies on the previous behavior where creating a carrier service automatically made rates available to merchants, you must update your integration so that rates are explicitly configured. Without these additional steps, merchants won’t see rates from newly created carrier services at checkout.

After creating a carrier service, you must ensure that its rates are added to a shipping profile by either:

• (Recommended) Directing merchants to manually add the carrier-calculated rate to the appropriate shipping profile in the Shopify admin.
• Programmatically adding the carrier-calculated rate to the appropriate shipping profile using the shipping profile APIs.

Older supported API versions will continue to use the existing automatic-add behavior for carrier services in the General shipping profile until those versions are sunset.

Learn more about carrierServiceCreate and the CarrierService REST resource.

What's changing

The cart tools on the Storefront MCP server are being deprecated in favour of the UCP-conforming Cart MCP tools:

• get_cart and update_cart on https://{shop}.myshopify.com/api/mcp are deprecated.

Cart MCP implements the UCP cart capability (dev.ucp.shopping.cart, version 2026-04-08) and exposes the following tools at the https://{shop-domain}/api/ucp/mcp endpoint:

• create_cart: Create a new cart with line items and optional buyer context.
• get_cart: Retrieve the current state of a cart.
• update_cart: Replace the cart's contents.
• cancel_cart: Cancel a cart.

The deprecated tools will be maintained until August 31, 2026, but all documentation will refer to the Cart MCP tools.

What you should do

If you're building with the Storefront MCP cart tools:

• Migrate get_cart and update_cart calls to the Cart MCP tools, and update endpoints to use https://{shop-domain}/api/ucp/mcp.

• Include a meta object carrying ucp-agent.profile in every request, and a meta["idempotency-key"] (UUID) for cancel_cart.

• Note that update_cart uses PUT semantics: each request replaces the cart's full state, so send the complete line_items array on every update rather than patching individual fields.

• Consult the updated request and response schemas for all cart tools and update your app to match.

  See the documentation for Cart MCP (https://shopify.dev/docs/agents/carts-and-checkout/cart-mcp) for more details.

Starting with GraphQL Admin API version 2026-10, the deprecated priceRule field on the DraftOrderDiscountNotAppliedWarning object is removed.

This is a breaking change for apps that query priceRule on DraftOrderDiscountNotAppliedWarning, which is returned in draft order discount warnings from mutations such as draftOrderCalculate, draftOrderCreate, and draftOrderUpdate. If your app selects priceRule in these responses, you must update those queries before upgrading to 2026-10.

The warning already exposes the relevant discount data directly, so you no longer need the legacy priceRule object. Use the following fields instead:

• discountTitle — the title of the discount that couldn’t be applied. Use this instead of priceRule { title }.
• discountCode — the code of the discount that couldn’t be applied. Use this instead of priceRule { discountCodes { nodes { code } } }.

Update any query that reads priceRule from this warning to select discountTitle and discountCode instead.

Before:

... on DraftOrderDiscountNotAppliedWarning {
  priceRule {
    title
    discountCodes(first: 1) {
      nodes {
        code
      }
    }
  }
}

After:

... on DraftOrderDiscountNotAppliedWarning {
  discountTitle
  discountCode
}

DraftOrderDiscountNotAppliedWarning was the only place where the legacy PriceRule object was reachable from the public GraphQL Admin API. As a result, removing priceRule also removes the PriceRule object and its related types from the public schema in 2026-10 and later.

Older supported API versions continue to expose priceRule on DraftOrderDiscountNotAppliedWarning until those versions reach end of life.

Learn more about the DraftOrderDiscountNotAppliedWarning object.

The ITEM_NOT_STOCKED_AT_LOCATION error will be removed from InventoryAdjustQuantities, InventoryMoveQuantities, InventorySetOnHandQuantities, and InventorySetQuantitiesUserErrorCode as of API version 2026-10.

Following the changes described here, inventory quantities can now be adjusted at any location. As a result, the condition that previously triggered ITEM_NOT_STOCKED_AT_LOCATION can no longer occur, and this error is no longer emitted.

This update removes an obsolete error code. If your app currently handles ITEM_NOT_STOCKED_AT_LOCATION, you can safely remove any logic that depends on this specific error.

You can now use relative paths for endpoint URLs in your Flow action extension configuration. The runtime_url, validation_url, config_page_url, and config_page_preview_url properties accept either an absolute HTTPS URL, such as https://example.com/api/flow/actions/place-bid, or a relative path that starts with a single /, such as /api/flow/actions/place-bid.

When you use a relative path, Shopify CLI resolves it against your development tunnel URL while shopify app dev is running, and against your app’s application_url after you deploy. This means you no longer need to update your runtime_url each time your development tunnel URL changes, making it easier to point Flow actions at routes hosted by your own app.

Use an absolute HTTPS URL when your endpoint is hosted on a different domain or service than your app, or when you want Flow to call the same URL in every environment. Protocol-relative URLs (such as //example.com/api/execute) aren’t supported, and your app configuration must include an HTTPS application_url before you deploy with relative paths.

For more details, see the Flow action configuration reference and Create a Flow action.

You can now configure purchaseType and recurringCycleLimit for app discounts directly from discount UI extensions using the discounts plugin.

Previously, these fields were only accessible through the GraphQL Admin API. App developers building discount UI extensions had no way to let merchants control whether a discount applies to one-time purchases, subscriptions, or both, or how many subscription billing cycles a discount should apply to.

The following fields are now available through the discounts plugin:

• purchaseType: control whether the discount applies to one-time purchases, subscriptions, or both
• recurringCycleLimit: set the number of billing cycles a subscription discount applies to (such as, a value of 4 applies the discount on the first 4 orders, then stops). A value of 0 means unlimited.

These fields work with both DiscountCodeApp and DiscountAutomaticApp discount types, and the values are enforced by purchase type filtering at checkout.

No action is required. To start using these fields, update your discount UI extension to include them in your discounts plugin configuration.

For more details, see the API documentation for DiscountAutomaticAppInput.

Apps can now open Shopify’s native file picker with the Intents API. This lets your app prompt merchants to choose files from their Shopify file library without building a custom picker or sending them through a separate flow.

With a single API call, your app can open the file picker, optionally filter by media type, enable multiple selection, and preselect files. When the merchant finishes selecting files, your app receives the selected file IDs as an array in response.data.ids.

New intent

The following intent is now available:

• pick:shopify/File

How it works

Invoke the intent from App Home or a UI extension:

const activity = await shopify.intents.invoke('pick:shopify/File');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Selected file IDs:', response.data.ids);
  // response.data.ids is an array of selected file IDs
}

Learn more in the App Home (iframe) Intents docs and App Home (UI extension) Intents docs.

As of GraphQL Admin API version 2026-07, app-owned shipping delivery profiles support a new boolean coversAllItems field.

Use coversAllItems on app-owned shipping delivery profiles to indicate that a profile applies to every shippable product variant in the store, without explicitly assigning each product or variant to that profile.

The field is available on the DeliveryProfile type:

query {
  deliveryProfiles(first: 10) {
    nodes {
      id
      name
      coversAllItems
    }
  }
}

You can also set coversAllItems through DeliveryProfileInput when creating or updating an app-owned shipping delivery profile:

mutation {
  deliveryProfileUpdate(
    id: "gid://shopify/DeliveryProfile/123"
    profile: {
      coversAllItems: true
    }
  ) {
    profile {
      id
      coversAllItems
    }
    userErrors {
      field
      message
    }
  }
}

When coversAllItems is true, rates from the app-owned shipping delivery profile apply to all shippable items at checkout, overriding any explicit product or variant assignments.

coversAllItems is only supported for authorized API clients on app-owned shipping delivery profiles. It is not supported on merchant-managed delivery profiles or on non-shipping profiles.

If you omit coversAllItems when creating a profile, it defaults to false. If you omit it when updating a profile, the existing value is preserved.

Learn more in the delivery profiles documentation.

As of GraphQL Admin API version 2026-07, you can define metafields for inventory transfers and set metafields directly when creating or editing transfers.

Use MetafieldOwnerType.TRANSFER with metafield definition mutations to create transfer-specific metafield definitions. You can also pass metafields in the metafields input on the following mutations:

• inventoryTransferCreate
• inventoryTransferCreateAsReadyToShip
• inventoryTransferEdit

Duplicating a transfer will also duplicates its metafields on inventoryTransferDuplicate. This lets apps define, validate, and write transfer-specific custom data, such as ERP references, handling instructions, review teams, or other metadata, without requiring a separate metafieldsSet call after creating or editing a transfer.

Learn more about metafields and the Admin GraphQL API.

The appliesOnSubscription and appliesOnOneTimePurchase fields on app discounts are now enforced at checkout. Previously, these fields existed on DiscountCodeAppInput and DiscountAutomaticAppInput but had no effect. All app discounts applied to every line item regardless of purchase type.

What changed

If an app discount is configured with appliesOnSubscription: false, it will only apply to one-time purchase line items, and vice versa. This filtering happens at the platform level after your discount function runs, so function-targeted lines that don't match the purchase type configuration will be excluded.

As part of this change, we also backfilled all existing app discounts to appliesOnSubscription: true and appliesOnOneTimePurchase: true. This means existing discounts continue to apply to all line items, so there's no behavior change for current discounts.

What you need to do

No action is required. If you're building a full-page app discount experience, you can now use these fields to control which purchase types your discount applies to.

Related docs

For more details, see the API documentation for DiscountAutomaticAppInput.

The next version of Hydrogen moves the commerce logic out of React Router into a framework-agnostic core. You can build storefronts in any JavaScript framework using Shopify's commerce primitives, and it ships with skills that coding agents use to scaffold a storefront for you.

This is an early developer preview, and we're looking for your feedback as we keep building it out.

Learn more about the Hydrogen Developer Preview on Github.

Starting in API version 2026-07, the GraphQL Admin API supports channel markets. Apps can now create and update Markets that apply to one or more sales channels, then use existing catalog and market APIs to manage channel-specific product availability, pricing, and currency.

This is an additive change. Existing apps don’t need to make updates unless they create, query, or make assumptions about Markets or market catalogs types.

What changed

You can now:

• Use MarketType.CHANNEL and MarketConditionType.CHANNEL to identify channel markets.
• Create channel markets with MarketCreateInput.conditions.channelsCondition and MarketConditionsChannelsInput.channelIds.
• Add or remove channel conditions through MarketUpdateInput.conditions.
• Query a market’s channels with Market.channels and Market.channelsCount.
• Query a channel’s markets with Channel.markets and Channel.marketsCount.
• Use Channel.activeRegions to read the regions where a channel has active product feeds.
• Filter markets by type with markets(type: CHANNEL).

What to do

If your app works with Markets or catalogs, update any logic that assumes markets are only regional, retail-location, company-location, or none-type markets.

If your app wants to create channel markets, pass channel IDs through channelsCondition.channelIds, then assign catalogs and pricing configuration using the existing Markets and catalog APIs. Product feed output continues to respect both the channel market’s catalog settings and the sales channel’s own publishing controls.

Related docs

• Market object
• Channel object
• MarketConditionsChannelsInput
• MarketType enum
• Channel config extension

WhatsApp marketing consent can now be managed through both the Customer Account and Admin APIs. Use the customerWhatsAppMarketingConsentUpdate mutation to update a customer’s WhatsApp marketing consent status for their default phone number. You can read the current WhatsApp marketing consent value from the CustomerPhoneNumber object via the whatsAppMarketingConsent field.

For more details on managing WhatsApp marketing consent, see the customerWhatsAppMarketingConsentUpdate mutation in the Admin API and Customer Account API references.

We’ve introduced two new Shopify App Store requirements for Sidekick app extensions to protect platform integrity, ensure merchant transparency, and preserve trust.

Starting today, all Sidekick app extensions must comply with the following guidelines:

• 2.2.8 Sidekick app extensions must align with stated app functionality: Sidekick app extensions must operate within the scope of your app’s core functionality. To ensure platform integrity and merchant transparency, your extension configuration, public App Store listing, and actual runtime execution must be materially consistent. Tools, intents, and actions exposed to Sidekick must be a logical representation of what your app does for the merchant on its own surface.
• 2.2.9 Don't display promotions, advertisements, or cross-sell other services in Sidekick app extensions: Don't use Sidekick app extensions to promote your app, promote related apps, or request reviews.

What this means for developers

If you’ve built (or plan to build) Sidekick app extensions, please review:

• Your extension’s TOML configuration
• Your extension’s runtime behavior in Sidekick
• Your public App Store listing

Make sure that:

• The tools, intents, and actions you expose in Sidekick stay within your app’s core functionality.
• Your extension’s configuration and behavior match how your app is described in its App Store listing.
• Your Sidekick app extension does not include promotions, advertisements, cross-sell content, or review requests.

To learn more, review our App Store requirements and Sidekick app extensions documentation on shopify.dev.

Exporting large datasets from Shopify is now up to 4X faster, thanks to optimizations to bulk queries.

Bulk operations are the most efficient way to import and export data from Shopify stores. Compared to synchronous use of the Admin API, you can build functionality faster with bulk operations, process large datasets in less time, and spend less on infrastructure.

Other recent improvements to bulk operations include:

• New queries for managing bulk operations
• Support for all mutations and up to 5 concurrent bulk operations
• Support for bulk operations in Shopify CLI

You can run your own comparison of bulk queries and mutations against synchronous API calls with the bulk operations sample app, or read more about bulk queries and mutations.

All app developers can now build Sidekick app extensions. These extensions allow your app to integrate with Sidekick, giving Sidekick the ability to access data or take action within your apps.

What's available today

• App data: Make your app's content searchable within Sidekick. Merchants can ask questions like "Find my best-performing email subject lines," and Sidekick will display relevant campaigns from your app along with key metrics.
• App actions: Allow merchants to take action within your app directly from Sidekick. Sidekick will navigate to the appropriate page in your app, pre-filled with relevant context, allowing merchants to confirm actions before any changes are made.

Eighteen launch partners, including Klaviyo, Loop, Smile, Judge.me, Checkout Links, and Matrixify, are already live as part of our developer early access program.

Learn more

Shopify CLI simplifies the process by scaffolding the entire extension setup, enabling you to deploy a functional extension in minutes. To get started, refer to the Sidekick app extensions documentation.

Send us feedback

We invite you to share your feedback, comments, and questions in the Shopify Developer Community. Your insights are invaluable to us, and we look forward to hearing from you.

Themes now support a new color_palette setting type. Palettes give merchants a single grid of colors they can edit directly, and changes apply across the entire theme. Individual color and color_background settings can reference palette entries as defaults, and merchants can override any color at the section or block level for local control.

Color schemes continue to work, so existing themes don't need to change, and color palettes aren't required for new themes or Theme Store submissions. We're focusing future development on palettes because they give merchants a better editing experience, so we recommend them when building new themes.

To see how this works in practice, try the latest version of Horizon (4.0.0), which uses the new palette system throughout.

For implementation details, see the color_palette developer documentation.

Effective December 1, 2026, Returns and exchanges apps and Subscription apps that provide buyer-facing self-service experiences must authenticate customers using the Customer Account API.

Apps that don't meet this requirement by the deadline are at risk of losing Built for Shopify status.

What's changing

Returns and exchanges and Subscription apps with buyer-facing self-service experiences must use the Customer Account API for customer authentication. This gives buyers and merchants a single, secure sign-in across their storefront, apps, and customer accounts.

Who this affects

Your app is affected if it falls into either category and offers buyers a self-service experience (for example, managing returns, tracking exchanges, or updating a subscription).

What you need to do

Integrate the Customer Account API for customer authentication in your buyer-facing flows. Review the updated Built for Shopify requirements for full details.

Deadline

December 1, 2026.

Your app's admin performance data is now available in the Dev Dashboard, alongside your existing monitoring tools. This change eliminates the need to switch between Partner Dashboard tabs to check web vitals.

What's changed

The admin performance dashboards have moved from the Partner Dashboard to the Dev Dashboard. You can now access daily and 28-day P75 rollups for three Core Web Vitals:

• LCP (Largest Contentful Paint): Measures loading performance.
• INP (Interaction to Next Paint): Assesses interactivity.
• CLS (Cumulative Layout Shift): Evaluates visual stability.

Note: FID (First Input Delay) has been retired. INP has replaced it as a Core Web Vital, and the dashboards reflect this update.

Each metric provides a clear pass/fail status based on the thresholds used for the Built for Shopify evaluation. The data displayed is the same as that used by the App Store to assess your app's compliance, ensuring consistency.

What you need to do

No code changes are required. Your app's web vitals telemetry will continue to function as before.

If you've bookmarked admin performance pages in the Partner Dashboard, those URLs will automatically redirect to the Dev Dashboard.

Links on the app ‘Distribution’ page now point to the new location.

Resources

• Built for Shopify requirements
• Core Web Vitals documentation

Liquid storefronts now have a standard communication layer between themes and the code that runs on them. Themes emit events, while apps and agents call actions.

Both work across all themes, and they ship together so you implement only once:

• Events are DOM events for commerce interactions: shopify:product:view, shopify:cart:lines-update, shopify:search:update, and others. Theme developers implement these in their theme code. App developers subscribe with plain JavaScript and get payload data directly, no follow-up API call needed.
• Actions go the other direction. Shopify.actions.updateCart, getCart, and openCart are available on every Liquid storefront. Apps and agents call them to trigger theme behaviors. Out of the box, they hit the Storefront API and reload the page. Theme developers override them to skip the reload and handle the UI update directly. Actions also emit the corresponding event on success.

Read the documentation for more details.

New shippingLabelPurchase mutation in the GraphQL Admin API

The GraphQL Admin API now includes the shippingLabelPurchase mutation, which lets apps purchase Shopify Shipping labels for eligible fulfillment orders.

Apps can provide the fulfillment order, shipping date and time, package details, total weight, customer notification preference, and optional preferred carrier/service selection. If a preferred rate isn't provided, Shopify selects the cheapest available rate.

Label purchase runs asynchronously. The mutation returns a ShippingLabelPurchaseResult, which apps can poll to track the request status:

• PENDING_PURCHASE: the purchase is still processing.
• PURCHASED: the label was purchased successfully, and the purchased labels are available on shippingLabels.
• PURCHASE_FAILED: the purchase failed, and details are available on errors.

Requirements

The mutation requires the write_orders access scope and a user with the buy_shipping_labels permission. Shops must also accept the Shopify Shipping terms of service before purchasing labels through the API.

Related documentation

• shippingLabelPurchase mutation
• ShippingLabelPurchaseInput
• ShippingLabelPurchaseResult
• ShippingLabelPurchaseResultStatus

The 2026-07 release replaces a collection’s single ruleSet with a multi-source model in the GraphQL Admin API. Each collection now has one or more CollectionSource objects that define typed inclusion and exclusion conditions, plus manual selections. Shopify Functions also gain variant-level collection membership fields on the ProductVariant type.

In API version 2026-07 and later, collections that use the new sources model are returned from collections queries, collection(id:) lookups, and other collection-returning fields. In earlier API versions, those same collections using new features are filtered out because the legacy ruleSet shape can’t represent them. Migrate to the 2026-07 API version to see and manage all collections in a shop.

These changes are non-breaking: deprecated members remain queryable in 2026-07 so you can migrate incrementally.

What’s new in the GraphQL Admin API

Collection sources and conditions

A new Collection.sources field returns one or more sources that back the collection. Two concrete types implement the new CollectionSource interface:

• CollectionConditionsSource: includes products through typed inclusion conditions plus manual selections, and can optionally exclude products through exclusion conditions. Each source must target either PRODUCTS or VARIANTS, set by the new CollectionSourceTargetType enum.
• CollectionSubCollectionsSource: pulls membership from one or more referenced collections.

Conditions are strongly typed: each condition uses a concrete type with a matching input type. Exclusion conditions include a subset of inclusion conditions or use a collection-based exclusion condition to target specific collections. Matching behavior for a set of conditions is controlled by the new CollectionConditionMatchType enum: ANY means at least one condition must match; ALL means every condition must match.

To define sources on a collection, collectionCreate and collectionUpdate now accept a collection argument typed as the new CollectionCreateInput or CollectionUpdateInput. CollectionUpdateInput exposes sourcesToCreate, sourcesToUpdate, and sourcesToDelete so you can update sources incrementally without replacing the entire collection definition.

Shareable app collection sources

A CollectionConditionsSource whose shareable field is true is owned by the calling app and can be linked to many of the shop’s collections. Use three new mutations to manage these shareable sources, and two new top-level queries to discover them:

• collectionConditionsSourceCreate, collectionConditionsSourceUpdate, and collectionConditionsSourceDelete manage an app's own shareable sources.
• collectionConditionsSources(appId:) returns the shareable sources owned by a specific app.
• collectionConditionsSourcesByApp paginates the apps that publish shareable sources for the shop.

To attach a shareable source to a specific collection, use CollectionShareableSourceInput { sourceId } inside the sources or sourcesToCreate field of the collection’s create or update input. Only the owning app can update or delete its shareable sources. Deleting a shareable source automatically detaches it from every collection that links to it.

Use shareable sources only when the same logic should be reused across multiple collections. If not, use collection mutations to create, update, or delete sources.

Other additions

• Collection.subCollectionEligibility returns separate inclusion and exclusion eligibility states for using the collection as a sub-collection target, with a stable SubCollectionIneligibleReason enum.
• collectionConditionMetafieldDefinitions returns the metafield definitions that can be used in inclusion conditions, scoped to the calling app's access.
• CollectionSourceExclusionConditionUpdateInput gains a collection field, so you can update a collection-based exclusion condition in place instead of deleting and recreating it.

Variant-level collection membership in Shopify Functions

The ProductVarianttype in Shopify Functions gains two new fields:

• inAnyCollection(ids: [ID!]!): Boolean! returns true when the variant is in any of the specified collections.
• inCollections(ids: [ID!]!): [CollectionMembership!]! returns per-collection membership for the variant.

A variant is a member of a collection when the variant itself is included in that collection. Existing Product.inAnyCollection and Product.inCollections continue to return true when the full product is in any of the specified collections, regardless of variant-level membership.

Deprecations

• Collection.ruleSet is deprecated in favor of Collection.sources. Each ruleSet rule has an equivalent inclusion condition (for example, a tag rule maps to CollectionSourceInclusionConditionProductTag). Sub-collections, exclusion conditions, and multiple sources aren’t supported in the legacy shape.
• collectionCreate(input:) and collectionUpdate(input:) are deprecated in favor of collectionCreate(collection:) and collectionUpdate(collection:). The legacy input argument continues to accept CollectionInput (with its ruleSet field), but only the new collection argument can define sources. If both arguments are supplied, the collection argument takes precedence.
• If your app reads Collection.ruleSet or writes input.ruleSet, switch to Collection.sources and the new collection argument. The legacy shape can’t express multiple sources, exclusion conditions, or shareable sources, and collections that use those features are filtered out of pre-2026-07 query results.
• If your Function needs variant-level collection membership, call inAnyCollection or inCollections on ProductVariant. The existing Product.inAnyCollection and Product.inCollections fields continue to return product-level membership.

Starting today, metafields stored on the app resource must have a metafield definition and customer accounts permissions to be accessible through the Customer Account API. Going forward, when calling the Customer Accounts API, app metafields without a definition will no longer return a value. If your app has functionality which depends on these fields, update those metafields to use definitions with the Customer Account API permission to avoid disruption.

Action required:

You must ensure that every metafield your app uses for customer account UI extensions, a Hydrogen or a Headless store, has a definition.

• Run the metafieldDefinitionCreate for every store that installs your app to ensure the metafields are correctly defined.
• For app-owned metafields, configure declarative metafields in your app’s TOML file.
• Configure the access settings on your definition to allow customer accounts API access.

Metafields owned by Customer or Order resources will not be affected by this change.

Starting with API version 2026-07, Partner API clients can use the new appSubscriptionCancel mutation to cancel app subscriptions for public apps they own.

The mutation supports:

• Immediate cancellation
• Deferred cancellation at the end of the current billing cycle
• Requesting prorated credits, when applicable
• Optionally skipping the final usage charge for usage-billed subscriptions

This mutation is available to Partner API clients that have the View financials permission in the Partner Dashboard.

Learn more in the Partner API 2026-07 documentation.

Shop User is Shopify’s cross-merchant buyer identity. Partners who use metafields on Shop Users can now read those metafields during checkout using Shopify Functions. To learn more, see the Shop User metafields guide in the Shopify developer documentation: https://shopify.dev/docs/api/shop/guides/use-cases/metafields

The CartLine type now exposes a viewKey field, so you can correlate a returned cart line with the viewKey you sent to cartLinesUpdate and cartLinesRemove.

What's new

• CartLine.viewKey returns the same viewKey your Liquid storefront renders, alongside the existing UUID id.

How to use

Previously, identifying a line by viewKey was input-only: you could send a viewKey, but the response returned a UUID id with no viewKey to map back. You can now read it directly off the line.

query CartLines($cartId: ID!) {
  cart(id: $cartId) {
    lines(first: 10) {
      edges {
        node {
          id
          viewKey
        }
      }
    }
  }
}

The field reads a value the cart already stores, so existing UUID-based correlation keeps working unchanged.

The Shopify AI Toolkit now supports upgrading checkout and customer account UI extensions to new API versions, including the migration to Polaris web components. Use the AI Toolkit with your preferred AI coding agent to skip repetitive manual work and speed up the heavy lifting.

Your agent will leverage the Shopify AI Toolkit, paired with our enhanced developer documentation, to go through the required migration steps such as handling React to Preact conversion, mapping and replacing legacy components with Polaris web components, and updating extension APIs.

Extensions built with Polaris web components render significantly faster than legacy React extensions, ensuring optimal loading time and extension performance.

Required for future app updates after October 1, 2026

Shopify CLI blocks apps from being updated if any of their extensions are on an API version that is more than 1 year old. By October 1, 2026, any app that contains checkout and customer account UI extensions on API versions 2025-07 or earlier will be unable to be updated.

All API versions 2025-10 and later use Polaris web components by default. Upgrade your extensions to the latest API version and adopt Polaris web components now to avoid this restriction.

Get Started

Install the Shopify AI Toolkit and follow our dev docs to run the skill in your AI agent:

• Checkout UI extension migration doc
• Customer account UI extension migration doc

It’s now easier to work with metaobjects.

With the new values property, you can fetch all fields of a metaobject in a single call without handling deserialization in your app. The API returns a JSON-compatible object that’s ready to use directly.

You can also use values when creating or updating metaobjects. Provide a JSON-style object that matches your metaobject’s field keys, and the API handles serialization for you. Optional fields are straightforward as well: any fields defined on the Metaobject that you omit from values are cleared.

You can continue to use field and fields if you need additional details about a field (such as type), or if you prefer patch-style behavior when mutating metaobjects, where any unspecified fields are left as-is.

We’ve updated our headless checkout authentication docs to refer to the silent single sign-on query parameter as sso=silent instead of logged_in=true.

This is a terminology and documentation update only. Existing checkout URLs that use logged_in=true will continue to work. Going forward, Shopify docs and examples will use sso=silent when describing the silent SSO flow from a headless storefront to checkout.

Learn more about authenticating buyers in checkout.

Starting with GraphQL Admin API version 2026-07, the [GiftCardCashOutTransaction](https://shopify.dev/docs/api/admin-graphql/2026-07/objects/GiftCardCashOutTransaction type is introduced as a new variant of the GiftCardTransaction interface. This type specifically represents transactions where a gift card balance is paid out through a point of sale (POS) system.

In previous API versions, such as 2026-04 and earlier, these transactions were classified as GiftCardDebitTransaction. From version 2026-07 onwards, they are identified as GiftCardCashOutTransaction. To accurately differentiate cash-out transactions from credit and debit transactions, use the __typename field when querying giftCard.transactions.

Below is an example query:

giftCard(id: "...") {
  transactions(first: 10) {
    nodes {
      __typename
      ... on GiftCardCashOutTransaction {
        id
        amount { amount currencyCode }
      }
    }
  }
}

Starting in API version 2026-07, the GraphQL Admin API supports local currency gift cards. You can create gift card products that are issued in a specific currency, and control whether buyers can redeem those gift cards across currencies. If your app creates gift cards directly, migrate from the deprecated initialValue field to initialAmount.

What changed

Use the new giftCardProductSet mutation to create and update gift card products. The input includes issuanceCurrency and crossCurrencyRedeemable, and automatically applies the product’s gift card settings to its variants. You can set issuanceCurrency and crossCurrencyRedeemable only when you create the product; you can’t change either field afterward.

Inspect a product’s settings through Product.giftCardSettings. If issuanceCurrency is null, Shopify issues gift cards from the product in the shop’s currency. If issuanceCurrency is set, Shopify issues gift cards in the specified currency, and buyers can purchase the product only in that currency. Publish these products only in markets where that currency is supported.

crossCurrencyRedeemable controls redemption behavior across currencies:

• If crossCurrencyRedeemable is false, issued gift cards use a crossCurrencyRedemptionStrategy of NONE.
• If crossCurrencyRedeemable is true and the product has no issuance currency, gift cards use MARKET_FX.
• If crossCurrencyRedeemable is true and the product has an issuance currency, gift cards use SPOT_FX.

Gift card creation now accepts initialAmount, which replaces the deprecated initialValue field. initialAmount includes both the amount and currency. Query GiftCard.isRedeemable and GiftCard.crossCurrencyRedemptionStrategy to check whether a gift card can be redeemed and how cross-currency conversion is handled.

What to do

1. If you create gift cards using giftCardCreate, replace initialValue with initialAmount before you upgrade to 2026-07.
2. If you offer multi-currency stores, decide whether new gift card products should be pinned to a single issuance currency. Configure issuanceCurrency and crossCurrencyRedeemable when you create the product; you can’t change either field afterward.
3. Update redemption flows to read GiftCard.crossCurrencyRedemptionStrategy so you can surface accurate cross-currency conversion behavior to merchants and buyers.

Related docs

• giftCardProductSet mutation
• GiftCard object
• Product.giftCardSettings
• GiftCardCrossCurrencyRedemptionStrategy enum

Inventory transfer webhooks: new origin and destination fields

Payloads for the following webhook topics now include the source and destination location of the transfer as Location Global IDs:

• inventory_transfers/add_items
• inventory_transfers/update_item_quantities
• inventory_transfers/remove_items
• inventory_transfers/ready_to_ship
• inventory_transfers/cancel
• inventory_transfers/complete

Each payload now includes:

• origin.id: For example, gid://shopify/Location/123
• **destination.id **: For example, gid://shopify/Location/456

You can use these IDs to identify where inventory is moving without making an additional API call to fetch the transfer.

The new fields are scoped to subscriptions whose webhook API version includes this change. The new functionality is available now on the unstable API version and will be in the upcoming public API release 2026-07. See the Inventory transfer webhook reference for details.

If your subscription is on an earlier version, or the transfer's source or destination is not a location (for example, a supplier-fulfilled transfer), the keys are omitted from the payload entirely rather than returned as null.

Clarified documentation for inventoryTransferSetItems

We've updated the description on inventoryTransferSetItems to better describe how it actually behaves. The behavior itself hasn't changed.

• inventoryTransferSetItems sets the quantity for each line item you pass, either adding it if it's not already on the transfer or updating it if it is. Line items you don't pass are unchanged. Each inventoryItemId may appear at most once per call.
• On a READY_TO_SHIP or IN_PROGRESS transfer, the quantity you pass replaces only the processableQuantity; already-shipped or picked quantity is preserved, and the resulting total is the preserved portion plus the provided quantity.
• quantity: 0 is only valid on DRAFT transfers, where it leaves a zero-quantity line item on the transfer. To remove a line item, use inventoryTransferRemoveItems. On READY_TO_SHIP or IN_PROGRESS transfers, 0 returns an INVALID_QUANTITY error.

Clarified documentation for inventoryTransferRemoveItems

We've also updated the description on inventoryTransferRemoveItems to better describe its behavior:

• The mutation can be called on transfers in DRAFT or READY_TO_SHIP status.
• You can remove items from In Transit shipments (using InventoryShipmentRemoveItem) and then remove it from the Transfer if the quantity has been placed on a shipment.
• For each line item you reference, if its full quantity is still unallocated to a shipment, then the line item is removed. Otherwise, the line item remains on the transfer with its quantity reduced to the allocated portion. Quantity allocated to a shipment, such as whether the shipment is still a draft, in transit, or already received, is preserved.
• On READY_TO_SHIP transfers, removing items returns the affected reserved quantity to available inventory at the origin location.
• Passing an omitted or empty transferLineItemIds is now treated as a no-op and returns the transfer unchanged.
• To change the quantity of a line item without removing it, use inventoryTransferSetItems.

Clearer error messages on inventory transfer mutations

Several user errors returned by the inventory transfer mutations now have more descriptive messages so that you can act on them without consulting additional docs:

• READY_TO_SHIP_TRANSFER_REQUIRES_AT_LEAST_ONE_ITEM now explains that you can't remove every line item from a READY_TO_SHIP transfer and that, to empty one, you should cancel it instead.
• ALL_QUANTITY_SHIPPED now clarifies that the check fires when the full quantity of the item is allocated to one or more shipments (including draft shipments where the item has been picked), and that the error name refers to the underlying allocation check rather than physical shipment.
• ITEM_PRESENT_ON_DRAFT_SHIPMENT_WITH_ZERO_QUANTITY now states plainly that the line item appears on a draft shipment with quantity 0.

Error codes themselves are unchanged, so existing handling in your apps continues to work.

The end-to-end review management experience previously launched for new app submissions in the Partner Dashboard now also applies to app audits.

When a published app undergoes a quality check and requires changes, that feedback appears in the Partner Dashboard under App > Distribution. You’ll see the same requirement-level tracking, a structured fix workflow, and direct messaging used for app submissions.

What to do if your app has an active audit

If your published app currently has an open audit with outstanding issues, review and manage all feedback in the Partner Dashboard under App > Distribution. Use your app’s status page there to see required changes, update your app, and respond to the review team, instead of checking your email inbox.

You can now identify cart lines by their view_key when calling the cartLinesUpdate and cartLinesRemove mutations, as an alternative to the cart line id.

What's new

• cartLinesUpdate accepts a viewKey on each CartLineUpdateInput, mutually exclusive with id.
• cartLinesRemove accepts a viewKeys list, mutually exclusive with lineIds.

How to use

Provide exactly one identifier per line. Existing integrations that use id or lineIds keep working with no changes.

mutation RemoveLineByViewKey($cartId: ID!) {
  cartLinesRemove(cartId: $cartId, viewKeys: ["794864053:7c2a9f..."]) {
    cart { id }
    userErrors { field message }
  }
}

App Home UI extensions are available for custom-distribution apps starting in API version 2026-07. They let you build your app's App Home page as a Shopify-hosted Preact UI extension using the admin.app.home.render target, so lightweight apps can ship a primary admin workspace without hosting a separate web app.

The iframe model remains recommended for most apps, especially public apps and apps that need server-side logic. App Home UI extensions give extension-only apps a simpler path when they fit the runtime constraints.

App Home today

Every Shopify app has a main experience inside the Shopify admin called App Home. This is where merchants go to configure settings, view data, and manage workflows in your app.

Historically, apps have built App Home with the developer-hosted iframe model. You scaffold an app with Shopify CLI, build it with your preferred web framework, host the app yourself, and Shopify embeds that app inside the admin.

That model is still the right default for most apps because it gives you the full web platform:

• Use any web framework.
• Host server-side logic and backend routes.
• Use full browser APIs.
• Build multi-page and full-stack app experiences.
• Use App Bridge APIs, App Bridge web components, Polaris web components, and the GraphQL Admin API.
• Ship through public or custom distribution.

For many apps, that flexibility is exactly what App Home needs.

Where the iframe model can be more than you need

Some apps don't need a full developer-hosted web app just to render their primary admin workspace. A custom-distribution app might be mostly extension-based. An internal workflow app might have a simple dashboard, setup flow, or resource manager. An extension-only app might not need server-side rendering, webhooks, or a separate backend at all.

In those cases, the iframe model can add infrastructure that isn't central to the app's workflow. You still need a hosted web surface for App Home, even when the app's main UI could run in the same extension model as the rest of the app.

App Home UI extensions give those apps another option.

Introducing App Home UI extensions

App Home UI extensions are a Shopify-hosted way to build an App Home page. Instead of hosting an iframe-based web app for the primary workspace, you build a Preact UI extension that targets admin.app.home.render.

The extension is configured in shopify.extension.toml:

api_version = "2026-07"

[[extensions]]
name = "t:name"
type = "ui_extension"

  [[extensions.targeting]]
  module = "./src/AppHome.jsx"
  target = "admin.app.home.render"

With this model, your App Home page runs in the admin extension runtime, renders with Polaris web components, and deploys as part of an app version. Shopify hosts the extension, so there's no separate App Home web server to deploy or maintain.

How it works

App Home UI extensions don't replace iframe-based App Home for every app. They give custom-distribution apps a focused path when the extension runtime is enough for the app's main workspace.

1. App Home becomes an extension target: The admin.app.home.render target renders your extension in the App Home area of Shopify admin. Your extension entry module points to a Preact file, such as extensions/app-home/src/AppHome.jsx. The generated template can use client-side routing for simple multi-page flows. For example, a single App Home UI extension can render a home page, a detail page, and a not-found page from the same entry module.

2. Your UI ships with the extension bundle: App Home UI extensions live alongside your other app extensions. Shopify CLI creates an extensions/app-home/ folder that contains the extension configuration and source files. This means your app's primary UI can share the same extension-based workflow as the rest of the app. You can preview it with shopify app dev and deploy it with shopify app deploy as part of an app version.

3. Shopify hosts the App Home surface: Because Shopify hosts the extension, you don't need a separate hosting step for the App Home page. This is useful when your app's main workspace is a lightweight dashboard, configuration page, resource manager, or guided workflow that can run entirely in the extension runtime.

4. The runtime has constraints: App Home UI extensions are intentionally more constrained than the iframe model. Use this model only when those constraints fit your app:

• App Home UI extensions are for custom-distribution apps.

• The runtime uses Preact.

• UI is built with Polaris web components.

• Browser APIs are limited compared to a developer-hosted web app.

• The compressed bundle size limit is 64 KB.

• If you outgrow the runtime, you reauthor the App Home experience as an iframe app.

  If your app needs public distribution, server-side logic, webhooks, unrestricted browser APIs, or the full flexibility of a web framework, continue using the iframe model.

Get started

You can scaffold a new extension-only app with an App Home UI extension using Shopify CLI:

1. Run shopify app init.
2. Select Build an extension-only app when prompted.
3. Open extensions/app-home/shopify.extension.toml and confirm that the extension targets admin.app.home.render.
4. Run shopify app dev and select your development store.
5. Press p to open the preview URL and test the App Home page in Shopify admin.
6. Deploy the extension as part of an app version with shopify app deploy.

You can also add an App Home UI extension to an existing app by running shopify app generate extension and selecting App home when prompted.

Related docs

• Apps in App Home
• App Home UI extensions
• App Home UI extension reference
• Configure app extensions
• Build an extension-only app

Your store includes a default agents.md file accessible at /agents.md. The paths /llms.txt and /llms-full.txt also point to this content by default.

Add any of the following templates under Online Store > Themes > Edit code to serve different content per path:

• templates/agents.md.liquid — controls /agents.md (and the default for the other two paths)
• templates/llms.txt.liquid — controls /llms.txt only
• templates/llms-full.txt.liquid — controls /llms-full.txt only

If no template is present for a given path, it falls back to your agents.md template, then to the Shopify-generated default. See the updated documentation for more details.

Next Generation Events are now available in developer preview. Events give you field-level control over when a subscription fires, what data it carries, and what triggers each delivery, fixing three common friction points faced with traditional webhooks: over-delivery, fixed payloads, and no built-in signal for what changed.

Events are available today on the unstable API version for the Product and Customer topics, with more rolling out through 2026.

Classic webhooks on Shopify

Apps often need to react when merchant data changes in Shopify:

• A product information management app syncing product data to an external catalog.
• A loyalty app updating a customer profile when customer data changes.
• A fulfillment app reacting when an order changes.

Classic webhooks have solved this by giving apps a way to subscribe to a topic and receive a payload when that resource changes. For example, if your app wants to know when products change, you can subscribe to products/update topic:

[webhooks]
api_version = "2026-07"

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products/update"

When a product updates, Shopify sends a delivery to your app. Your app gets a signal that something changed, but the signal is broader than the workflow your app is trying to run. Your handler still needs to read the payload and decide whether the delivery matters. For example, an app syncing prices to an external catalog is only interested when the prices of items change. Since the products/update webhook fires on all product changes, including title, tags, status, and options, the app still needs to determine whether a delivery needs to be acted on or thrown away.

You can use include_fields to reduce the webhook payload to a point, but Shopify still sends a delivery for every qualifying products/update:

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products/update"
include_fields = ["id", "status", "variants.id", "variants.price", "updated_at"]

You can also use filter to suppress deliveries based on the current values from a predetermined payload doesn't describe which field changed, and it doesn't prevent unrelated product updates from being delivered if the current payload still matches the filter:

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products/update"
include_fields = ["id", "status", "variants.id", "variants.price", "updated_at"]
filter = "status:active AND variants.price:>=10.00"

In this example, Shopify sends the webhook for any product update where the product is active and at least one variant currently has a price of 10.00 or more. A title edit, tag update, or option change can still pass the filter if the product already matches those conditions. If your app only wants price changes, then the handler still has work to do:

1. Receive products/update deliveries that pass any configured filter.
2. Compare the current payload against previous state stored by your app.
3. Discard deliveries where the product still matches the filter but the price didn't change.
4. Make a follow-up GraphQL Admin API request if the webhook payload doesn't include all the data needed to respond.
5. Run the sync after the app has proved that the delivery is relevant.

For workflows that care about a specific field changing, detection, state comparison, and follow-up fetching are pushed into the app.

Introducing Events

Events keep the parts of Classic webhooks that make them useful and introduces new configuration to define what is relevant to your app.

Instead of subscribing to a classic webhook topic and figuring out whether a delivery matters afterwards, you define the topic, action, field-level triggers, payload shape, and delivery conditions in shopify.app.toml. Topics map to GraphQL Admin API objects, so a topic covers the entity you want to subscribe to and its owned data. Actions are standardized to create, update, and delete, and they describe the lifecycle event on the root entity. For example, adding a variant to a product is an update action on the Product topic; the action tells you the product changed, while triggers and fields_changed tell you what changed inside it.

For the same price sync workflow, consider the following Events subscription:

[events]
api_version = "unstable"

[[events.subscription]]
handle = "price_sync"
topic = "Product"
actions = ["update"]
triggers = ["product.variants.price", "product.variants.compareAtPrice"]
uri = "/api/events"

query = """
  query priceSync($productId: ID!, $variantsId: ID!) {
    productVariant(id: $variantsId) {
      id
      price
      compareAtPrice
      sku
    }
    product(id: $productId) {
      id
      title
      status
    }
  }
"""

query_filter = "product.status:'ACTIVE'"

This subscription moves the relevance check into Shopify in three places.

1. First, triggers pre-qualify which field changes can fire the update delivery. In this case, a delivery qualifies only when product.variants.price or product.variants.compareAtPrice changes. A product title edit, tag update, or option change doesn't qualify for this subscription. Triggers are optional; omitting them means every trigger that can fire an Event, will fire an Event
2. Second, you can design the payload you receive with query , which is a standard GraphQL Admin API query. Shopify runs the query after the qualifying change and includes the result in the delivery's data field. In this case, your handler receives the changed variant's price, compare-at price, and SKU, plus the product's title and status, without treating the delivery as a signal to make a second request. There's no fixed payload schema to work around; the response is shaped for the use case you configured. If you don't need data in the delivery, the query is optional and Shopify sends a thinner payload with fields_changed and query_variables.
3. Third, query_filter suppresses deliveries that don't match the current query result. In this example, product.status:'ACTIVE' means Shopify sends the delivery only when the product's current status is active. Any field you use in query_filter must also exist in your query. Together, triggers and query_filter help the right deliveries reach your app before your endpoint is called.

When those conditions are met, your app receives a delivery like this:

{
  "topic": "Product",
  "action": "update",
  "handle": "price_sync",
  "data": {
    "productVariant": {
      "id": "gid://shopify/ProductVariant/456",
      "price": "24.99",
      "compareAtPrice": "34.99",
      "sku": "SIGNAL-NOT-NOISE"
    },
    "product": {
      "id": "gid://shopify/Product/123",
      "title": "Peace & Quiet Tee",
      "status": "ACTIVE"
    }
  },
  "fields_changed": [
    "product[id: 'gid://shopify/Product/123'].variants[id: 'gid://shopify/ProductVariant/456'].price"
  ],
  "query_variables": {
    "productId": "gid://shopify/Product/123",
    "variantsId": "gid://shopify/ProductVariant/456"
  }
}

The delivery includes the data returned by your query, the fields_changed paths that explain why the subscription fired, and the query_variables Shopify used to run the GraphQL Admin API query. Your app no longer needs to infer whether price changed by comparing the payload against stored state, discard unrelated product updates that happened to pass a current-state filter, or make a second request just to collect the data needed for the price sync.

Get started

Events is in developer preview and uses the unstable API version. To try Events:

1. Upgrade to Shopify CLI version 3.92 or higher.
2. Add an [events] block to shopify.app.toml.
3. Create a subscription for a supported topic from the Events reference.
4. Add triggers for the field changes that matter to your workflow.
5. Add a GraphQL query and, if needed, a query_filter.
6. Deploy the app configuration and test deliveries in a development store.

Start with the Create an Events subscription tutorial for a working product sync example, or move right into migrating your existing subscriptions into Events.

What's next

Events are available in developer preview while topic coverage expands. For topics that aren't supported yet, keep using webhooks alongside Events in the same shopify.app.toml.

As you test, look for workflows where your app currently receives broad webhook deliveries, compares them against stored state, filters them in your handler, and then calls the GraphQL Admin API to fetch more data. Those workflows are strong candidates for Events subscriptions.

If you want more background on the developer preview, follow the launch thread, watch the Events walkthrough, or join the Developer Community discussion.

Related docs

• Events reference
• About Events
• Create an Events subscription
• Migrate from webhooks

The release of Shopify CLI 4.0 today brings clarity to CLI versioning, the introduction of automatic updates, and the announced removal of the deprecated --force flag from shopify app deploy.

Semantic Versioning

Shopify CLI is now following semantic versioning practices. Releases with new features will be minor versions, and bug fixes will be patch versions. When required, major version releases will be used to communicate breaking changes to CLI command structure or behavior.

For more information, see our announcement of the move to SemVer.

Automatic Upgrades

Starting with Shopify CLI 4.0, Shopify CLI upgrades itself automatically using the package manager you installed it with. Auto-upgrade is skipped in CI, project-local installs, and for major version releases. Automatic upgrades can be disabled with the shopify config autoupgrade off command.

For more information, see Shopify CLI documentation.

Removal of the --force flag for app releases

The --force flag on the app deploy and app release commands didn’t distinguish between low-risk operations (adding or updating extensions) and high-risk ones (deleting them). This flag has been removed in Shopify CLI 4.0. 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.

For more information, see the March 2026 changelog.

Other removed commands and flags

The following deprecated commands and flags have also been removed in Shopify CLI 4.0:

• shopify webhook trigger (use shopify app webhook trigger)
• shopify theme serve (use shopify theme dev)
• shopify app generate schema (use shopify app function schema)
• shopify app webhook trigger --shared-secret (use --client-secret)
• shopify app generate extension --type (use --template)

Customer accounts are getting a visual refresh, featuring improved navigation, layout, and consistency across devices. You can preview these changes now and test your Shopify Extensions within the updated layout.

What's changing:

• Single-column native pages: These are now consistent across both desktop and mobile, with simplified navigation. Inline extensions will render in a narrower page width compared to the previous wider layout. Full-page extensions can either adopt our mobile-first, narrow layout that matches native pages or expand to a wider layout for data-heavy content.
• Increased visibility for order action extensions: Order action extensions are now more visible, and order summary extensions are no longer hidden behind a tap on mobile devices. This change makes it easier for customers to discover and use the features you've built.
• Existing extension targets are mapped to the new layout: Ensuring compatibility with the new design. See extension targets by page.

All current extension targets remain supported. However, this is an ideal time to review them. Testing now gives you a head start on any adjustments needed to ensure your extensions integrate seamlessly before these design updates are released to merchants. The feature preview will be available until June 12, 2026.

Read our documentation to start the preview. You can ask questions and share feedback in the Shopify community.

New Features

Optional Consent

Users can now reject scopes and continue using your Mini. Consent is no longer all-or-nothing — if a user declines a scope, your Mini should gracefully degrade rather than block the experience. If your Mini hard-fails when a scope is rejected, please update it using the new hooks below.

useCheckScopesConsent Hook

Check at runtime which scopes a user has granted. Use this to conditionally render features that depend on a particular scope.

Usage:

import {useCheckScopesConsent} from '@shopify/shop-minis-react'

function MyMini() {
  const {scopes} = useCheckScopesConsent()

  if (scopes.includes('product_lists:write')) {
    return <SaveToListButton />
  }
  return <SignInPrompt />
}

useRequestScopesConsent Hook

Re-request consent after a user has previously declined. The hook must be invoked from a user interaction — you cannot re-prompt automatically. Use this for flows where granting consent unlocks a clear, user-initiated action.

Usage:

import {useRequestScopesConsent} from '@shopify/shop-minis-react'

function GrantAccessButton() {
  const {requestScopesConsent} = useRequestScopesConsent()

  return (
    <button onClick={() => requestScopesConsent(['product_lists:write'])}>
      Enable saving products
    </button>
  )
}

useCheckPermissions Hook

Separate from scopes, useCheckPermissions lets your Mini check OS-level permissions (camera, photo library, and so on) before invoking an action that requires them.

Usage:

import {useCheckPermissions} from '@shopify/shop-minis-react'

function CameraFeature() {
  const {permissions} = useCheckPermissions(['camera'])

  if (permissions.camera === 'granted') {
    return <CameraView />
  }
  return <RequestCameraButton />
}

request_blocked Sentinel

When a user has declined a scope or permission and the platform will not re-prompt, the relevant hooks now return a request_blocked sentinel value instead of null. This lets you distinguish "not asked yet" from "asked and blocked" and tailor your UI accordingly. See the Scopes Consent docs on shopify.dev for the full state machine.

Intents

Intents are a new communication layer between the Shop app and Shop Minis. The Shop app launches your Mini from contextually relevant moments — such as a product detail page — and passes along the context (typically a product). For partners, this opens a new path to distribution: instead of relying on the Explore tab alone, your Mini can be surfaced where buyer intent is highest.

Two intents are supported today:

| Intent | What it's for | | :

We're changing how public apps handle offline access tokens to enhance merchant data protection. Starting January 1, 2027, all public apps must use expiring offline access tokens when calling the Admin API. After that date, public apps still using non-expiring tokens will receive authentication errors.

This extends the April 1, 2026 change, which applied only to newly created public apps, to all public apps, including those created before April 1, 2026.

What apps are affected

Public apps making Admin API requests using non-expiring offline access tokens, including apps created before April 1, 2026

What apps are unaffected

• Custom apps
• Apps created by merchants either in the Dev Dashboard or in the admin

Why we're making this change

Non-expiring tokens, if leaked, remain valid indefinitely. Expiring tokens close that window in 60 minutes and rotate automatically, dramatically reducing the impact of a credential leak. This aligns with modern OAuth best practices, and as a developer it gives your app a predictable refresh flow.

Action required

Existing public apps: Migrate from non-expiring to expiring offline access tokens.

Merchants don't need to reinstall, as your app exchanges existing tokens through code. Follow the migration guide for the step-by-step path. If you use Shopify's app templates and official API libraries, refresh handling is already implemented; you only need to handle the token exchange and storage updates.

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

The checkoutToken field is now available on the GraphQL Admin API's Order object. This field returns the token associated with the checkout that was used to create the order, matching the existing checkout_token field in the REST Admin API.

You no longer need to ask merchants to share function run logs with you. These logs are now automatically available in the Dev Dashboard for any function your app has the necessary access scopes to view.

What's Changed

Function run logs in the Dev Dashboard are now accessible based on the access scopes granted to your app by the merchant. The required scopes to view a log are determined by the function's input query. If your app has the necessary scopes to read these fields via the GraphQL Admin API, you will automatically see the run details without needing any additional action from the merchant.

What You Need to Do

If you expect to see function run details but don't, ensure your app has the scopes required by the input query. Here's how you can check:

1. Request the scopes during your app's installation/authentication process: This is ideal for scopes your app consistently needs. Refer to Access scopes for instructions on declaring and requesting access scopes.

2. Request protected customer data scopes when accessing customer data: Some fields, like customer details and addresses, require additional protected customer data access. Consult Protected customer data for the approval process and necessary data-level scopes.

3. Use optional scopes for temporary or debugging access: If a scope is needed occasionally, such as for debugging, request it as an optional scope. Merchants can grant or revoke it without reinstalling the app.

Once the required scopes are granted, the run details will automatically be visible the next time you access the log.

As of API version 2026-04, the new Checkout And Accounts Configuration API is now available to unlock consistent branding customizations across checkout, customer accounts, and sign-in surfaces. This API is exclusively available to Shopify Plus merchants.

This new API replaces the Checkout Profile API and Checkout Branding API (both are now deprecated). All capabilities to customize settings and branding for checkout, and customer accounts, and sign-in are now consolidated into one single API.

What you can do:

• Shared branding settings: Use shared designTokens and components to set branding once and apply consistently across checkout, customer accounts, and sign-in pages. Section styles (padding, shadows, colors, borders, and border radius) previously available for checkout only can now be applied to customer account pages.

• Surface-specific overrides: Apply targeted overrides under surfaces.checkout, surfaces.customerAccounts, and surfaces.signIn for logos, colors, and section styles.

• Direct color settings: Set color using HEX values or palette colors directly on sections like main, header, and orderSummary — no more mapping through a limited number of color schemes. Save your brand colors to an editable color palette of up to 20 colors and reference anywhere you make a color selection. Update a palette color, and it changes everywhere it is referenced.

• Customize branding per market: Customize your pages for each market with unique branding settings.

View developer documentation for more detail.

We’ve published new migration guides to help you upgrade Checkout and Customer Account UI extensions to the latest API version and Polaris web components.

The new guides include:

• Guidance for moving from React or JavaScript extension APIs to Preact, Polaris web components, and the global shopify object.
• More than 60 component-specific migration pages, covering components such as Button, Checkbox, TextField, Banner and View for Checkout and Customer Account UI extensions.
• Instructions for migrating checkout metafields to cart metafields

If your extension uses an API version earlier than 2025-10, use these guides to adopt Polaris web components, which are the default in API version 2025-10 and later.

Start with:

• Checkout UI extensions migration guide
• Customer Account UI extensions migration guide

Shopify App Pricing supports subscriptions, usage-based charges, or combined models, configured in the Partner Dashboard.

What's new:

Managed Pricing is now Shopify App Pricing Shopify App Pricing replaces Managed Pricing as Shopify’s default billing solution that gets configured during app submission in the Partner Dashboard. Apps previously on Managed Pricing will now see “Shopify App Pricing” as their selected billing solution.

Usage-based billing now possible with App Events API Charge based on merchant usage using the App Events API. Send events from your app, define meters in the Partner Dashboard, and Shopify handles aggregation, calculation, and invoicing. Three pricing structures supported: fixed, graduated, and volume. Supports negative reporting for automatic charge corrections.

New APIs make billing data more accurate Active Subscription API: Real-time subscription status (active, pending, cancelled, frozen) that persists beyond uninstall [Historical API:](https://shopify.dev/docs/apps/launch/billing/shopify-app-pricing#app

The App Events API lets you send any event from your app to Shopify. App event data appears in your Dev Dashboard Logs alongside webhooks, Function executions, and API calls.

How it works:

1. Send app events to a single API endpoint: Define the event_handle and attributes you want to track and send them to the App Events API, including:

• Feature usage: bulk_edit_completed, report_generated, automation_created
• Workflows: onboarding_completed, campaign_sent, export_finished
• Performance: sync_failed, api_timeout, rate_limit_hit
• Conversion signals: limit_hit, premium_viewed, milestone_achieved
• Billable activities: order_processed, email_sent, label_printed

2. View events in Dev Dashboard: All app events flow into Dev Dashboard Logs automatically for monitoring, alongside data Shopify provides about your app, i.e: Webhooks, Functions executions, and API calls.

3. Optional: Turn app events into billing: On Shopify App Pricing, any app event can become a usage-based charge. Define a meter in the Partner Dashboard, match it to an event_handle, and Shopify handles metering and invoicing. No additional code required.

App Events is available now for all apps, regardless of billing method. Learn more

The cartToken field is now available on the GraphQL Admin API's Order object. This field returns the token associated with the cart that was used to create the order, matching the existing cart_token field in the REST Admin API.

We've introduced markets as a new option in DiscountContextInput, enabling you to target discounts to specific regional markets, retail locations, or B2B company locations. This option can be used alongside existing eligibility options such as all, customerSegments, and customers.

You can now set market eligibility for all discount types, including:

• Basic, BXGY, App, and Free Shipping discounts (both automatic and code-based).
• Note that eligibility types are mutually exclusive—you can target either markets OR customer segments, but not both simultaneously.

What you can do:

• Assign market eligibility to a discount by using markets in DiscountContextInput when creating or updating a discount.
• Query the discounts and discountsCount fields on a Market to view the list of discount customizations for that market.
• Filter discounts by any market eligibility using context:market or by specific markets using market_ids in discountNodes.

What you need to know:

• Discounts do not inherit across different market types (e.g., from regional to B2B or retail). When you assign a discount to a regional market, it automatically applies to sub-markets of the same type (e.g., from "North America" to "Canada").
• If you are using API versions prior to 2026-07, discounts with market eligibility will be filtered out, as these versions cannot represent them (both in node queries and specific discounts by ID).

For more information, refer to the Admin GraphQL API documentation.

What's changing

Shopify now applies stricter rate limits to bots and agents that access the Storefront API and Shopify-hosted online store pages. Bots and agents that don't sign their requests are subject to the strictest limits. To qualify for higher rate limits, operators should sign their requests with Web Bot Auth. For more details, see Storefront rate limits.

What you should do

If you operate a bot or agent accessing Shopify storefronts, sign your requests using Web Bot Auth. To get started, review the Web Bot Auth architecture and Cloudflare's implementation guide — for context only, you do not need to enroll with Cloudflare.

Higher access tiers

If you require higher rate limits than those provided to Web Bot Auth traffic, please contact us through this form.

Shopify Merchants

Shopify merchants who want to crawl their own stores can find ready-to-use Web Bot Auth signatures in the Shopify admin.

ProductVariant is now a Publishable. Variants can be published or unpublished per publication (channel or catalog) in API version 2026-07, giving merchants — and your apps — fine-grained control over where each variant is visible without deleting variants, duplicating products, or hiding them via storefront code.

This is a non-breaking, additive change:

• Product-level publishing is unchanged and still takes precedence. A product must be active and published to a channel for any of its variants to render there.
• Variants default to published (opt-out model). Existing apps that publish at the product level continue to work without modification.
• Variants can be created in an unpublished state in order to prevent early exposure to buyers.

What's new in the Admin GraphQL API

• publishablePublish and publishableUnpublish now accept ProductVariant IDs.
• ProductVariant now adheres to the Publishable interface, similar to Product and Collection, which includes resourcePublicationv2 and publishedOnPublication
• Product feed webhooks fire with a product update for variant added and deleted when variants are published to the feed’s channel.
• variant_publication/create/update/delete webhooks are still under development and will be shipped imminently.

What this means for your app

• Channel apps using product feeds should not require any changes to work - the product feed adds and removes variants to the product and an incremental sync webhook is triggered.
• Channels or pseudo channels that do not use product feeds and rely on reading publication state via the admin graphql API should implement support by reading the respective publication state of variants via ProductVariant.resourcePublicationsv2.
• Apps that create variants after product publication occurs: new variants default to published in all of the parent product's publications. If your app plans to create variants in an unpublished state, productSet and productVariantBulkCreate both include a variant.published: false field to create variants as unpublished.
• Apps that publish products: no changes required. Continue calling publishablePublish on products as before. Consider implementing variant publishing support if unpublishing variants is relevant to your apps workflows.

Read the developer guide →

App deployment in CI/CD is now available for all apps through app automation tokens on the Dev Dashboard. These tokens offer app-scoped authentication, allowing you to use the latest Shopify CLI to automate app releases in GitHub Workflows and similar tools. App-scoped authentication ensures that each token is specific to an individual app, enhancing security and control.

To deploy your app using an app automation token, set the token as an environment variable and execute the deployment command:

export SHOPIFY_APP_AUTOMATION_TOKEN="your-app-automation-token"
shopify app deploy --config production --allow-updates

App automation tokens replace the CLI tokens previously generated on the Partner Dashboard. While existing CLI tokens will remain functional until they expire, transitioning to app automation tokens is recommended for enhanced security and functionality. Learn more about migrating to app automation tokens.

For further information on app automation tokens, visit Shopify.dev:

• Managing app automation tokens
• Deploy app components in a CD pipeline

Shopify Plus and Enterprise merchants will soon be able to enable a single checkout experience where customers can choose both shipping and store pickup within the same order. Previously, customers had to place separate orders for each delivery method.

This change impacts how delivery and fulfillment information flows through checkout. If your app reads, calculates, or displays delivery and fulfillment information, the testing window is open now. Enable feature preview and make the necessary updates before this rolls out to merchants.

Apps that have not been updated may cause checkout errors, incorrect calculations, or failed fulfillment routing, impacting the merchant's checkout experience.

What changed When a merchant has both shipping and local pickup enabled, customers can now choose between store pickup or shipping for each item in their cart during checkout. This creates a single order with multiple fulfillment orders: one for shipping, one for pickup.

There are no new API fields or breaking schema changes. However, existing API fields now return data in new combinations:

• Checkouts can have multiple deliveryGroups: each group represents how different items are to be fulfilled.
• Orders can contain fulfillment orders with different delivery methods (SHIPPING and PICK_UP) within the same order.
• Fulfillment orders include a delivery_method field that identifies the fulfillment method for each group.

What you need to do

1. Review the testing guide.
2. Audit your app's assumptions. Identify any logic that assumes a single delivery method per order.
3. Test your app in feature preview
   • Go to "Dev stores" and create a dev store.
   • Make sure to select "Plus" under Shopify Plan and "Ship and pickup" under Test a feature preview on this store.
4. Verify your app handles the order correctly end-to-end.
   • Place a test order with both shipped and pickup items.
   • Ensure your app reads the delivery_method field on fulfillment orders and routes items accordingly.
5. If your app update changes merchant-facing behavior or workflows, communicate those changes to your merchants as soon as possible.

Visit the developer forum for questions and updates.

Seven new Settings intents let apps open editors for notifications, payment capture, gift cards, delivery profiles, and business details. This builds on the initial Settings intents release from March.

With a single API call, your app opens the relevant Settings section as a contextual overlay and scrolls the merchant directly to the field they need to edit.

New intents

Notifications

• edit:settings/NotificationsSenderEmail
• edit:settings/NotificationsStaff

Payments and gift cards

• edit:settings/PaymentCaptureMethod
• edit:settings/GiftCardExpiration

Delivery

• create:shopify/DeliveryProfile
• edit:shopify/DeliveryProfile

Business

• edit:settings/BusinessDetails

Each intent opens the relevant Settings page in a page stack and scrolls the merchant directly to the targeted card, following the pattern established in the initial release.

Resources

• Read up on admin intents
• Learn more about supported Shopify resources
• Leave us feedback in the Shopify Developer Community

We have introduced a new actor field in subscription mutations to help you track who initiated an action - whether it was the customer, the merchant, or the partner app's automated system.

You can now include an actor argument when creating billing attempts or editing subscription contracts. This field accepts the following values:

• customer: The buyer initiated the action (e.g., clicking "pay now" in a customer portal).
• merchant: A merchant or their staff manually initiated the action.
• partner: The partner app's automated system initiated the action (e.g., scheduled billing or retry logic).

This field is available in the following Admin API mutations:

Billing Attempts:

• subscriptionBillingAttemptCreate (via subscriptionBillingAttemptInput.actor)
• subscriptionBillingCycleCharge
• subscriptionBillingCycleBulkCharge

Contract Edits:

• subscriptionContractCreate
• subscriptionContractUpdate
• subscriptionContractAtomicCreate
• subscriptionContractProductChange
• subscriptionBillingCycleContractEdit

Status Updates:

• subscriptionContractActivate
• subscriptionContractPause
• subscriptionContractCancel
• subscriptionContractFail
• subscriptionContractExpire

The default value of appliesOnSubscription has been changed from false to true on the DiscountCodeAppInput and DiscountAutomaticAppInput input types in GraphQL Admin API.

No action is required. This default value change has no effect on how discounts are applied at checkout. If your app explicitly sets appliesOnSubscription when creating or updating app discounts, your behavior is unchanged.

This change applies across all active API versions. The appliesOnOneTimePurchase field already defaults to true and is unchanged.

In version 2026-04 of the GraphQL Admin API, we're introducing support for applying multiple product discounts on a single cart line. This feature will enable merchants to continue migrating Scripts ahead of the June 30th, 2026 sunset date.

To learn more about configuring discount combinations, please refer to the documentation for the GraphQL Admin API.

You can now create and manage metric targets for merchants using four new GraphQL Admin API operations: analyticsTargets, analyticsTargetCreate, analyticsTargetUpdate, and analyticsTargetsDelete.

With targets, merchants can set numeric goals for analytics metrics, such as "achieve $50K in gross sales this quarter," and track their progress with a visual gauge. The API has been available to apps from the start, enabling you to build on the same foundation that supports targets in the Shopify admin.

Whether you're developing a goal-setting tool, a reporting dashboard, or a planning app, you can now read and write the same targets that merchants view in their analytics, using the same API, rules, and validation.

What you can do

• Create: Specify a metric, target amount, time period, and an optional filter (for example, limit to a specific sales channel or product).
• Read: Retrieve targets for a shop using analyticsTargets, with support for pagination.
• Update: Modify the metric, name, amount, time period, or filters.
• Delete: Remove targets using analyticsTargetsDelete. Deleted targets can't be recovered.

Key details

• Scope: Requires read_reports and write_reports permissions.
• Deduplication: The API uniquely identifies each target by its metric, date range, and filters. Attempting to create a duplicate results in a userError with guidance on necessary changes.
• Status computation: The API automatically derives the status field (In progress, Achieved, Not achieved, Upcoming) from the target's date range and current metric value at query time.
• Filters: Each target can have one dimension-based filter in the WHERE statement of ShopifyQL using = or IN operators.

Use cases

• Goal-setting apps: Create targets for merchants based on historical performance or industry benchmarks, providing smart defaults.
• Reporting and BI tools: Access merchant targets and display progress alongside your visualizations, ensuring consistency with Shopify.
• Planning and forecasting apps: Integrate external goals into Shopify Analytics, offering merchants a unified place to track all targets.
• Agency dashboards: Programmatically set and monitor targets across multiple client stores.

Targets created by your app appear alongside merchant-created targets in the Shopify admin, on the Targets index page with their own target gauge, and on merchant dashboards. Merchants can manage them consistently, regardless of their origin.

View the API reference →

Related: new ColumnDataType enum values

API version 2026-04 adds two new enum values to ColumnDataType in ShopifyqlTableDataColumn:

• UNITLESS_SCALAR: Represents a dimensionless numeric score with no associated unit. Applied to web performance metrics: p50_cls, p75_cls, p90_cls, p99_cls (Cumulative Layout Shift percentiles).
• MULTIPLIER: Represents a ratio or multiplier value (for example, 3.2x). Applied to shop_campaign_return_on_ad_spend (Return on ad spend).

These metrics previously returned FLOAT. This change doesn't affect callers on API versions prior to 2026-04.

We have updated the app uninstall reasons in your Partner Dashboard and now require merchants to select a reason before removing an app. These changes provide clearer, more actionable insights into why merchants uninstall apps, helping you enhance your app experience.

When uninstalling, merchants will now see the following options and must choose one to complete the process:

• Testing multiple apps
• Store is closing or pausing
• Not using app now
• Not satisfied with app features
• Not satisfied with customer support
• Too expensive
• Not working properly with store
• Other (please specify)

Starting with POS version 11.5, we are updating the internal calculation method for custom fixed-amount line item discounts. These discounts will now be applied on a per-unit basis rather than across the entire line. Note that this change only affects fixed-amount discounts; percentage discounts remain unchanged.

If your app uses setLineItemDiscount or bulkSetLineItemDiscounts from the Cart API with a FixedAmount discount type, you can continue to pass the total discount amount for the line item as you currently do. The POS system will automatically handle the conversion.

In most cases, the total discount will remain the same. However, for amounts that don't divide evenly by quantity, there might be a rounding difference of up to one cent, the smallest denomination in the local currency. For example, a $5.00 discount applied to 3 items becomes $1.67 per unit, totaling $5.01 instead of $5.00.

No action is required for extensions using API version 2026-04 or earlier. In a future API version, extensions will need to pass per-unit discount amounts directly. We will provide more details as the release approaches.

For more information, refer to the Cart API reference.

The LineItem object in the GraphQL Admin API now includes a [priceAfterAllDiscountsBeforeTaxesSet(https://shopify.dev/docs/api/admin-graphql/2026-07/objects/LineItem#field-LineItem.fields.priceAfterAllDiscountsBeforeTaxesSet) field, which is equivalent to the REST API's current_subtotal_price_set on line items. This field returns the total price of a line item in both shop and presentment currencies after all discounts have been applied, excluding refunded and removed quantities. The value doesn't include taxes.

This is useful for order export workflows where you need the line-level subtotal after discounts but before tax.

As of API version 2026-04, the ability to read and write checkout metafields in checkout and customer account UI extensions has been removed. Instead, checkout metafields have been replaced by cart metafields in checkout UI extensions and order metafields in customer account UI extensions.

Action Required

If you are using checkout metafields in older API versions, it is essential to upgrade to version 2026-04. Follow our guides to ensure a smooth transition:

• Migrate to cart metafields in checkout UI extensions
• Migrate to order metafields in customer account UI extensions

Additionally, order metafield definitions now support a new capability that automatically copies values from cart metafields to order metafields upon order creation. This enhancement streamlines data management between cart and order processes. Learn more

As of POS version 11.5, merchants can generate scannable QR codes for any discount code in the Shopify Admin. These QR codes can be applied by both POS staff at checkout and by customers in online store sessions.

What this means for discount apps

No changes are required with this release. If your app creates discount codes, you can now generate QR codes for them that encode the store's discount URL.

What you should do

Shopify uses the format https://{shop}.myshopify.com/discount/{CODE} with the following encoding caveats:

• Simple discount codes encode directly. For example, the discount code SUMMER20 becomes SUMMER20 in the final QR code URL.
• Special characters are URL-encoded twice. For example, the discount code SAVE 10% becomes SAVE%252010%2525 in the final QR code URL.

If you want to include QR codes as shareable links in your apps, you’ll need to replicate the same URL-encoding used by Shopify for your discount codes.

The totalUnsettledSet field on the OrderTransaction object now correctly calculates the unsettled amount when a capture is in pending status. The affected field is OrderTransaction.totalUnsettledSet.

What's changed

Previously, when a capture was pending, totalUnsettledSet was double-counting by incorrectly returning the authorization amount plus the pending capture amount. Now it correctly returns the actual unsettled amount.

For example, for a $100 authorization with a $50 pending capture:

• Before: Returned $150 (incorrect)
• After: Returns $100 (correct)

What you need to do

Nothing. Your existing queries will continue to work and no changes to your code are required. The returned value will now be correct.

What this affects

This bug only affects multi-capturable orders, which are orders where partial or multiple captures are supported.

According to our API breaking change policy, bug fixes that correct values to match documented behavior are applied immediately across all API versions.

Why we changed it

This update fixes a bug where the calculation double-counted during pending capture states. The totalUnsettledSet field represents the available amount with currency to capture on the gateway, but the previous value didn't reflect this.

This bug was introduced when multi-capturable support was added, and became more visible after Shopify Payments migrated to a flow where captures transition through PENDING status before SUCCESS.

Starting in API version 2026-07, the taxSettings field on the Customer object will be publicly accessible in the Admin GraphQL API.

Apps with the read_customers or read_taxes access scopes can now query a customer's tax ID, such as a VAT number, which is collected and validated during checkout. This update aligns with the CompanyLocation.taxSettings.taxRegistrationId, which has been available since API version 2025-01 for B2B customers.

Example query:

{
  customer(id: "gid://shopify/Customer/customer_id") {
    taxSettings {
      taxId
    }
  }
}

This is a read-only change. The taxId field returns the tax ID as a string or null if the customer hasn't provided one. The taxIdValidation sub-field, which indicates the validation status, is not included in the public API. Apps that need access to this field must have approved protected customer data access.

For more information, refer to the Customer object in the Admin GraphQL API reference.

Shopify is introducing CSS content subsetting for {% stylesheet %} tags to improve storefront performance.

Starting April 20, 2026, Shopify only delivers the CSS from {% stylesheet %} tags that are relevant to the sections, blocks, and snippets rendered on each page, instead of serving all {% stylesheet %} CSS on every page load.

What this means for your theme

If your theme's CSS classes are self-contained – each file's {% stylesheet %} only styles HTML elements within that same file or its direct children (rendered via {% render %}) – no changes are needed. Your theme is already compatible.

However, if a file's {% stylesheet %} defines CSS classes that are used by HTML elements in other, unrelated files, those styles may not be included on pages where the defining file isn't rendered. This is the pattern to watch for and fix.

Please refer to the stylesheet subsetting docs for additional detail and guidance.

What’s changing

The following UCP catalog tools in Storefront Catalog are now available:

- `search_catalog`: Search a store's product catalog with filters, pagination, and buyer context
- `lookup_catalog`: Batch lookup products or variants by identifier with inputs correlation
- `get_product`: Retrieve full product details with interactive variant selection, availability signals, and more

Tool calls can be placed against the https://{storedomain}/api/ucp/mcp endpoint.

What you should do

The previous search and lookup tools are deprecated in favor of the above tool names and endpoint, as well as related updates to their request and response shapes to match UCP. The old versions will be maintained until June 15th, 2026, but all documentation will refer to the latest version.

If you’re building with Storefront MCP tools:

• Update tool names to one of the supported tools above.
• Update endpoints to use https://{storedomain}/api/ucp/mcp.
• Consult the update request and response schemas for all tool calls and update your app to match.

See the documentation for Storefront Catalog MCP for more details.

We updated the app submission experience to help apps get reviewed and published faster. Three changes are live now in the Partner Dashboard:

End-to-end review management in Partner Dashboard Review feedback for app submissions now lives in the Partner Dashboard under App > Distribution. Each requirement now has its own status, reviewer comments, and a way to ask questions directly. You can see exactly what's outstanding and resubmit when everything is resolved.

• Requirement-level tracking: Each requirement that needs attention has its own status tracker. You'll see what failed with associated feedback from the reviewer.
• Structured fix workflow: Address each requirement individually and mark it resolved before resubmitting.
• Blocked resubmission: You can't resubmit until all identified issues are resolved.

AI self-review tool Before you submit your app, you can now run an AI-powered self-review that checks your app against App Store requirements. Run this before you submit, it takes two minutes and catches the obvious stuff that would bounce you back weeks later. This is now available in the Shopify AI toolkit.

Automated pre-submission checks We've expanded automated pre-submission checks so you'll know instantly if something needs fixing before a reviewer picks up your app:

• Theme app extensions requirement
• App Store Listing requirements

What to do if you have an app in review If your app is currently in the ‘Reviewed’ status with outstanding issues, your review continues through the existing email-based process. The new dashboard flow does not apply to this submission.

If your app is currently in the ‘Submitted’ status and waiting for review, no action is needed. When a reviewer evaluates your app, feedback will appear in the new dashboard experience.

As of API version 2026-04, you can pass includeInactive: true when querying the inventoryLevels or inventoryLevel fields on InventoryItem and Location to include inactive inventory levels in the response. By default, only active inventory levels are returned.

Why we made this change

Previously, there was no way to retrieve inactive inventory levels through the API. The includeInactive argument gives apps explicit control over whether inactive levels are included in results.

Impact on your app

• GraphQL: In the 2026-04 and later API versions, the fields InventoryItem.inventoryLevels, InventoryItem.inventoryLevel, Location.inventoryLevels, and Location.inventoryLevel accept a new optional includeInactive boolean argument. The default is false, ensuring existing queries remain unaffected.

What you need to do

• No changes are required for existing queries, as they will continue to return only active inventory levels.
• To access inactive inventory levels, include includeInactive: true in your queries.

As of GraphQL Admin API version 2026-04 the InventoryLevel object now includes an isActive boolean field, which indicates whether an inventory level is currently active. In this version, you can optionally query for inactive inventory levels, and the isActive field will help you distinguish between active and inactive levels.

Why We Made This Change

Previously, deactivating an inventory level would clear its associated quantities, and these inactive levels were not visible through the API. Starting with version 2026-04, deactivating an inventory level no longer clears its quantities. Inactive levels can be adjusted just like active ones, so the API now returns these inactive levels. The isActive field provides visibility into the activation status, allowing apps to differentiate between locations where inventory tracking has never occurred and those where it has been deactivated.

Impact on Your App

From GraphQL Admin API version 2026-04 onwards, queries on InventoryLevel may return inactive inventory levels that were previously excluded. Each inventory level now includes an isActive field, which you can use to filter or display activation status.

What You Need to Do

• No changes are required for existing queries, as they will continue to return only active inventory levels.
• If you choose to include inactive levels in your query, review any logic that assumes all returned inventory levels are active. Use the isActive field to filter results if your app only requires active inventory levels.
• Update any inventory level counts or aggregations to account for the inclusion of inactive levels.

As of API version 2026-04, using the inventoryActivate mutation without specifying an available or onHand argument will no longer default these values to zero. If an item was previously active at a location, any existing active and onHand quantities for the inactive InventoryLevel will be retained.

Why We Made This Change

Previously, inventoryActivate would reset existing inventory quantities to zero, preventing merchants from independently tracking inventory from activation status. This behavior erased quantity history upon activation. The update allows merchants to manage inventory and activation separately, preserving their quantity history.

Impact on Your App

• GraphQL: In the unstable or 2026-04 and later releases, using the inventoryActivate mutation without an available or onHand argument will preserve the pre-activation quantities.
• REST: In the unstable or 2026-04 and later releases, POST requests to inventory_levels/connect.json will retain the pre-activation quantities.

What You Need to Do

• Review any business logic that assumes inventoryActivate resets inventory quantities to zero for specified inventory items and locations.

Starting June 15, 2026, Shopify will renew its mTLS client certificate used by Payments Apps to verify that the client initiating the request is Shopify.

Unless you're using custom checks or validation logic, this update won't impact your live payments apps, as the new certificate is signed by the same Certificate Authority as the current one.

Who's affected

Payments Apps

Reason for the change

The current certificate will expire on July 24, 2026. It must be renewed before this date to ensure uninterrupted service.

What you need to do

Action is required if you use custom certification validation.

If you use custom certificate validation

Action is required before June 15, 2026. If your app checks the Common Name (CN) or other certificate-specific fields, you must update your validation logic to accept the new certificate.

If you use standard mTLS validation

No action is required. The new certificate is signed by the same CA.

For more information, refer to the certificate details.

The MOST_RELEVANT value is now available to the GraphQL Admin API's CollectionSortOrder, available in API version 2026-07 and higher.

Learn more about collection sorting options in the Shopify Help Center.

Mobile primary action now renders as an icon in the title bar

On mobile, the primary and secondary actions defined on your TitleBar are changing how they render:

• The primary action now displays as an icon-only button in the mobile header, rather than in a bottom bar with icon and text.
• Secondary actions now appear in the overflow menu, creating a more consistent mobile interface.
• If you don't pass an icon property with your primary action, it defaults to a + (plus) icon.

Who's affected

All embedded apps that define a primary action or secondary actions on their TitleBar.

When the changes go into effect

Changes go live to all affected apps on April 15th, 2026.

What you should do

If the default + icon fits your use case, no changes are needed. Otherwise:

• Pass an explicit icon with the primary action on your TitleBar to ensure the most contextually appropriate icon displays on mobile.

Starting in version 2026-07 of the GraphQL Admin API, you can query the weight field on the LineItem type in the GraphQL Admin API. This field returns a Weight object with value and unit, making it easy to access line item weights without converting from the REST API's grams field.

New CSS Variable for Mobile Safe Area Insets

A new CSS custom property, --shopify-safe-area-inset-bottom, is now available for embedded apps running on Shopify Mobile. This property provides the exact pixel value of host UI overlays, such as the floating bottom navigation bar, to prevent apps from placing fixed-position content over these overlays.

• The var(--shopify-safe-area-inset-bottom) is automatically set by App Bridge. It defaults to 0px when no overlay is present, and adjusts to the height of the overlay in CSS pixels when the mobile floating bottom bar is active.
• This variable automatically adds bottom padding to the <body>, ensuring most apps function correctly without content being obscured by the floating bar.
• If your app includes custom fixed-bottom elements, such as sticky footers or floating action buttons (FABs), incorporate this variable into your styles:

  .my-floating-button {
    bottom: calc(16px + var(--shopify-safe-area-inset-bottom, 0px));
  }

Who's Affected

All embedded apps running on Shopify Mobile that utilize fixed or sticky elements at the bottom of the viewport.

When the Changes Take Effect

These changes will be implemented for all affected apps on April 15th, 2026.

What You Should Do

For most apps, no action is required as bottom padding is automatically applied. However, if your app has custom fixed-bottom UI elements, use var(--shopify-safe-area-inset-bottom, 0px) in your CSS to ensure these elements are positioned above the native floating bottom bar.

References

• https://shopify.dev/docs/api/app-home/apis/authentication-and-data/environment-api

As of API version 2026-04, Shopify provides an official testing library for UI extensions. @shopify/ui-extensions-tester lets you write unit tests for extensions on any surface — Checkout, Admin, Customer Accounts, and POS — without a running Shopify host.

What it does

The library provides strongly typed mocks of the extension API, so you can render extensions in isolation, simulate user interactions, and verify behaviour against public APIs with full type safety.

Key capabilities

• Render and query: Render your extension in a standard DOM environment and query the output using standard testing patterns.
• Type-safe mocks: The mocked shopify global uses the same types as the real API, catching incorrect API usage at test time.
• Surface-specific defaults: Sensible mock defaults for each target surface (Checkout, Admin, Customer Accounts, POS) so tests work out of the box.
• Event simulation: Trigger user interactions and test async state changes with dispatchEvent() or @testing-library/preact.
• AI-agent friendly: Strongly typed mocks and predictable test patterns make the library well-suited for AI-assisted test-driven development.

Getting started

Read documentation to learn more. Get started with example test suites for every surface.

What's changing

We are removing the grams field from the DraftOrderLineItem object in the Admin GraphQL API, starting with version 2026-07. This field was deprecated over 8 years ago. After the 2026-04 API version becomes unsupported, any queries referencing DraftOrderLineItem.grams will return an error.

What you need to do

Replace any usage of grams with the weight field on DraftOrderLineItem. The weight field returns both a value and a unit, giving you more flexibility than the old grams integer.

Before (deprecated):

query {
    draftOrder(id: "gid://shopify/DraftOrder/1") {
      lineItems(first: 5) {
        nodes {
          grams
        }
      }
    }
  }

After:

query {
    draftOrder(id: "gid://shopify/DraftOrder/1") {
      lineItems(first: 5) {
        nodes {
          weight {
            value
            unit
          }
        }
      }
    }
  }

Why we made this change

The grams field only supported one unit and could overflow for large weights. The weight field uses a WeightInput with both value and unit, which is more flexible and consistent with how weight works elsewhere in the platform.

Need help?

For more details, see the DraftOrderLineItem reference docs. If you have questions about this change, please reach out through the Shopify Partners community.

As of API version 2026-07, several changes have been introduced to the discount fields and amounts in the Storefront API.

What's changed

Deprecated Fields:

• The cart.discountAllocations field is deprecated. Use cart.lines[].discountAllocations(lineLevelOnly: false) and cart.deliveryGroups[].discountAllocations instead.
• The cartDiscountAllocation.discountApplication field is deprecated. Use sourceDiscountApplication instead. Note: the value field on discountApplication incorrectly returns the per-line allocated amount rather than the configured discount amount (for example, a $10 fixed discount allocated as $4 to one line shows value: $4). The new sourceDiscountApplication field returns the correct value.

New Fields:

• cart.discountApplications: Lists all discounts (for example, product, shipping, and order) currently applied to the cart.
• cartDiscountAllocation.sourceDiscountApplication: Returns the discount application with the correct configured discount value and concrete type information. For example, a $10 fixed discount will show value: $10 regardless of how it's allocated across lines. Access type-specific fields using GraphQL fragments, for example sourceDiscountApplication { … on CartCodeDiscountApplication { code } }.
• baseCartDiscountApplication.totalAllocatedAmount: Shows the total discount amount allocated across the entire cart. For instance, if a 10% discount splits as $4 on line A and $6 on line B, both lines will show totalAllocatedAmount: $10.
• cart.deliveryGroups[].discountAllocations: Displays the discounts allocated to the delivery group.

New Argument:

• cart.lines[].discountAllocations(lineLevelOnly: Boolean): The lineLevelOnly argument lets you request either only product-level discounts or all discounts allocated to the cart line. It defaults to true for backward compatibility.

What you need to do

• Update queries to use cart.discountApplications instead of cart.discountAllocations for reading all discount applications on a cart.
• Replace cartDiscountAllocation.discountApplication with sourceDiscountApplication for accurate discount values and type-specific fields.
• Move product allocation queries to cart.lines[].discountAllocations(lineLevelOnly: false).
• Move shipping allocation queries to cart.deliveryGroups[].discountAllocations.
• Test your discount calculations with percentage, fixed amount, and free shipping discounts.

In order for AI coding agents to be useful additions to development workflows, they need to have the right context. When you're building on Shopify, a small platform detail can change the right implementation: the API surface you choose, the fields available in a schema, the extension APIs you import, or the validation steps you need before shipping.

The Shopify AI Toolkit is now available to help bridge that gap. It gives supported AI coding tools access to Shopify developer resources, API schemas, validation, and Shopify CLI workflows, so agents can spend less time rediscovering Shopify context and more time helping with the task in front of them.

What changes with the toolkit

The Toolkit is designed for the moments where generic AI assistance usually needs extra correction. If you're designing an Admin GraphQL operation, your agent can work from Shopify's API schemas instead of guessing at fields or object relationships. If you're editing Liquid or UI extension code, it can validate the generated work against Shopify-specific expectations. If a task needs store context, your agent can use Shopify CLI’s store execute command when you choose to run it.

All this harness brings your agent’s work closer to the right answer, with access to the same Shopify-specific context you would otherwise need to provide manually.

Example: extension migrations

Extension migrations are a good example of where this helps. Checkout and customer account UI extensions on API versions before 2025-10 need to adopt Polaris web components when upgrading to newer API versions. That kind of migration involves repetitive, detail-heavy work:

• Updating the extension API version in shopify.extension.toml.
• Converting React-based extension code to Preact where required.
• Replacing legacy components with Polaris web components.
• Updating extension APIs and target-specific imports.
• Checking the migration guide for required steps.
• Running and testing the migrated extension locally.

With the Toolkit installed, you can ask your coding agent to start that work from Shopify's migration guidance:

Migrate the extensions/my-checkout-extension extension to API version 2026-04.

The Toolkit doesn't remove the need to test the result, review the diff, or validate behavior in your app. It helps automate the repetitive parts of the migration so you can spend more time on the decisions and checks that still need your experience as a developer.

Get started

Install the Shopify AI Toolkit with the plugin for your AI tool. The Toolkit supports Claude Code, Codex, Antigravity CLI, Cursor, Hermes through the plugin, and Visual Studio Code. For setup instructions, refer to the Shopify AI Toolkit documentation.

After installing, try it on a real Shopify workflow: scaffold an app, explore the right API for a use case, review an app against Shopify App Store requirements, or migrate a checkout or customer account UI extension.

Related docs

• Shopify AI Toolkit
• Upgrade checkout UI extensions to the latest API version and Polaris web components
• Upgrade customer account UI extensions to the latest API version and Polaris web components
• Use Polaris with the Shopify dev MCP server

The Hydrogen April 2026 release (v2026.4.0) is out. This release updates the Storefront API and Customer Account API to 2026-04 and includes breaking changes to consent handling and the API proxy.

• Updated Storefront API and Customer Account API to 2026-04 (#3651)
• Breaking: The Storefront API proxy is now always enabled. The proxyStandardRoutes option has been removed from createRequestHandler. If your load context does not include a storefront instance, the request handler will throw an error. (#3649)
• Breaking: Backend consent mode is now on by default, replacing the legacy _tracking_consent JS cookie with server-set cookies via the Storefront API proxy. (#3649)

Check out the full release notes for more details. Review the Storefront API 2026-04 changelog and Customer Account API 2026-04 changelog for other changes that may affect your storefront. And please drop your comments, feedback, and suggestions in GitHub Discussions.

We are enhancing Shopify Functions with new capabilities for discounts, shipping, and payments. These improvements aim to replace the functionalities you previously achieved using Shopify Scripts, allowing you to build custom logic tailored to your unique business needs.

To assist with your migration planning, we recommend using the Shopify Scripts customizations report. This tool will help you identify which of your current customizations can be transitioned to Shopify Functions or public apps.

Here are the key dates to keep in mind as we approach the deprecation of Shopify Scripts:

• April 15, 2026—Editing and publishing new Shopify Scripts will no longer be possible.
• June 30, 2026—All Shopify Scripts will cease to execute entirely.

We strongly encourage you to begin your migration as soon as possible.

For more information on migrating from Shopify Scripts to Shopify Functions, please visit the Shopify Help Center.

As of April 7, 2026, when you replace or delete a file in the Shopify admin, Shopify will no longer proactively purge the file's URL on cdn.shopify.com/.... The previously cached content will continue to be served until the URL's TTL (Time to Live) expires. This change aims to reduce CDN purge volume and improve consistency across our edge providers.

To ensure your customers receive updated content after a file replacement, use Shopify's URL helpers to render file references. This ensures the current versioned URL (?v=...) is always emitted:

• In themes: Use the Liquid filters file_url, image_url, and asset_url.
• In products: Insert images and videos via the native Media uploader rather than pasting <img src="..."> into descriptions.
• In apps and external integrations: Fetch file URLs at request time from the Admin GraphQL API or Storefront API instead of caching them.

Hardcoded cdn.shopify.com/... URLs in product descriptions, blog posts, theme code, or printed materials will continue to return the original content after a file replacement. We recommend migrating to one of the dynamic patterns above to ensure updated content is served.

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 | |

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.

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

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.

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.

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

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.

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.

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, the tax_summaries/create webhook for Tax Partner Apps now includes merchant business entity information. This addition provides details about the legal entity responsible for transactions, which is crucial for accurate tax calculation and cross-shop entity mapping.

What's new

The tax webhook payload now features a new merchant_business_entity field at the root level of the tax summary. This field includes the following details:

• id: The global ID of the business entity (format: gid://shopify/BusinessEntity/{id})
• legal_entity_id: The stable Central Legal Entity ID from the Organizations Platform, enabling consistent identification of the same legal entity across multiple shops and markets
• company_name: The legal name of the business entity
• display_name: The display name of the business entity
• address: The business entity's address, including:
  • country
  • province
  • Address lines (address1, address2)
  • city
  • zip
  • company

This field is optional and will only be present when the merchant has configured a legal business entity for their shop. The legal_entity_id sub-field is also optional and will only be present when the business entity is linked to a Central Legal Entity.

Before (2026-04):

{
  "summary": {
    "idempotent_key": "abc123",
    "shop": { ... },
    "order_details": { ... }
  }
}

After (2026-04):

{
  "summary": {
    "idempotent_key": "abc123",
    "shop": { ... },
    "order_details": { ... },
    "merchant_business_entity": {
      "id": "gid://shopify/BusinessEntity/12345",
      "legal_entity_id": "223432432",
      "company_name": "Acme Corporation",
      "display_name": "Acme Corp",
      "address": {
        "country": "CA",
        "province": "ON",
        "address1": "123 Main St",
        "city": "Toronto",
        "zip": "M5V 2T6",
        "company": "Acme Corporation"
      }
    }
  }
}

As of API version 2026-04, tax calculation requests for Tax Partner Apps can now include cart line item properties. These properties are custom name-value pairs that merchants can add to individual line items.

• Merchants configure properties on individual cart line items (such as token, personalization, or gift_wrap).
• Tax Partner Apps specify which property keys they want to receive across all line items
• Only the requested property keys are included in calculation requests.

Key limits

You can specify a maximum of five keys. The five key limit applies to which property keys the Partner wants to receive, not the number of line items. For example:

• Partner configures: ["token", "personalization"] (2 keys)
• Cart has: 10 line items
• Result: All 10 line items will include their own token and personalization values (if present)

Example payload

Cart line items in the delivery_groups[].cart_lines[] objects now include an optional properties field per line item.

Before (2026-04):

{
  "delivery_groups": [{
    "cart_lines": [{
      "id": "gid://shopify/CartLine/123",
      "quantity": 1,
      "merchandise": {
        "id": "gid://shopify/ProductVariant/456",
        "title": "Custom T-Shirt"
      },
      "cost": {
        "amount_per_quantity": {
          "currency_code": "USD",
          "amount": "25.00"
        }
      }
    }]
  }]
}

(2026-04) & After:

{
  "delivery_groups": [{
    "cart_lines": [
      {
        "id": "gid://shopify/CartLine/7",
        "quantity": 1,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/456",
          "title": "Custom T-Shirt"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "25.00"
          }
        },
        "properties": {
          "token": "abc-123",
          "personalization": "John Smith"
        }
      },
      {
        "id": "gid://shopify/CartLine/6",
        "quantity": 2,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/789",
          "title": "Custom Mug"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "15.00"
          }
        },
        "properties": {
          "token": "def-456",
          "personalization": "Jane Doe"
        }
      }
    ]
  }]
}

The fulfillmentOrderCancel mutation now returns a specific fulfillmentOrderCancelError type instead of the generic userError type.

What's changing:

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

Why we made this change:

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

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"
    }
  }
}

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.

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 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.

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.

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.

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 →

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

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.

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.

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'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.

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'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.

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.

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

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.

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.

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

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'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 | |

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 | | :

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

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 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.

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.

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.

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.

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.

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

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.

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.

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.

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 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"
                          }
                        }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

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.

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.

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.

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.

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.

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.

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.

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.

The Hydrogen January 2026 release (v2026.1.0) is out. This is a quarterly API version bump to Storefront API 2026-01 and Customer Account API 2026-01.

• Updated Storefront API and Customer Account API to 2026-01 (#3434)
• The cartDiscountCodesUpdate mutation now requires the discountCodes argument. If you have custom cart discount code logic, verify your mutations include this field before upgrading.

Check out the full release notes for more details. Review the Storefront API 2026-01 changelog and Customer Account API 2026-01 changelog for other changes that may affect your storefront. And please drop your comments, feedback, and suggestions in GitHub Discussions.

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 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.

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.

The Hydrogen October 2025 release (v2025.10.0) is out. This release updates the Storefront API and Customer Account API to 2025-10 and adds new cart mutations that simplify multi-gift-card and multi-address checkout flows.

• Updated Storefront API and Customer Account API to 2025-10 (#3352)
• Added cart.addGiftCardCodes to append gift card codes without re-submitting existing ones (#3401)
• Added cart.replaceDeliveryAddresses to replace all delivery addresses in a single call (#3406)
• cart.updateDeliveryAddresses([]) now clears all delivery addresses on the cart. Previously this was a no-op. (#3393)
• Added visitorConsent support on the @inContext directive for Storefront API parity (#3408)

Check out the full release notes for more details. And please drop your comments, feedback, and suggestions in GitHub Discussions.

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.

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

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.

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.

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.

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.

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.

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 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.

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.

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.

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"
        }
      ]
    }
  }
}

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

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.

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.

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.

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.

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.

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

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.

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.

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
								}
							}
						}
					}
				}
			}
		}
	}

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.

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-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.

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.

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.

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.

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.

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.

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 };
}

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.

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.

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
    }
  }
}

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.

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 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 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