DEV Community: no7software

Shopify CLI 4.0 Breaking Changes: Engineering Migration (2026)

no7software — Fri, 22 May 2026 15:26:10 +0000

Shopify CLI 4.0 shipped on 21 May 2026 and the upgrade is not a routine bump. The release removes the --force flag from shopify app deploy, retires five legacy commands, and introduces automatic upgrades that engineering teams running production CI/CD pipelines must reckon with before the next deploy.

What Shopify CLI 4.0 actually ships

Three concrete changes land at once. First, the CLI now follows Semantic Versioning — minor releases ship features, patch releases ship bug fixes, and majors signal breaking changes to command structure or behaviour. Second, starting with 4.0 the CLI upgrades itself automatically through the package manager you installed it with (npm, yarn, pnpm), and the upgrade is explicitly skipped inside CI, in project-local installs, and across major versions. Third, the --force flag that previously short-circuited the safety prompt on shopify app deploy and shopify app release is gone — split into --allow-updates and --allow-deletes so high-risk operations are no longer hidden behind one ambiguous switch. The full release note lives at the Shopify Dev changelog entry.

How the --force flag removal changes your deploy pipeline

If your CI/CD pipeline currently runs shopify app deploy --force on every merge, the next pipeline execution against CLI 4.0 will fail with an unrecognised-flag error and stall mid-deploy. The replacement is granular. --allow-updates covers low-risk operations like adding a new extension or updating an existing one without manual confirmation. --allow-deletes covers the high-risk path: removing an extension that already shipped, which the old --force would have silently approved. The split exists because the CLI team measured that --force hid every category of deploy operation behind the same prompt-bypass switch, and an accidental deletion of a production extension is irreversible.

The migration is mechanical — find every CI/CD script using --force and replace it with the explicit pair of flags appropriate to that pipeline. Most release pipelines we ship for client engagements use --allow-updates alone, and reserve --allow-deletes for a separate, manually-triggered cleanup job that runs against a feature branch before its production cutover.

The five deprecated commands you must replace in 2026

The 4.0 release also drops five legacy command and flag shapes. Each has a 1:1 modern replacement, and pinning to the new form before the upgrade is the safest order of operations.

Shopify CLI 4.0 removed commands and replacements

Removed (pre-4.0)	Replacement (4.0+)
shopify webhook trigger	shopify app webhook trigger
shopify theme serve	shopify theme dev
shopify app generate schema	shopify app function schema
shopify app webhook trigger --shared-secret	--client-secret
shopify app generate extension --type	--template

The shopify theme serve → shopify theme dev rename is the one most likely to silently break legacy npm scripts. We have seen package.json scripts in client repos that still alias "theme:serve": "shopify theme serve" three years after the command was first deprecated. A repo-wide grep for the removed forms before you bump the CLI version saves the panic when a developer hits "start dev" on Monday and the command no longer exists.

How to handle the new auto-upgrade behaviour in CI/CD

The auto-upgrade default deserves a separate look because the consequences differ between local developer machines and CI runners. On a local install, the CLI will detect a newer minor or patch version and upgrade through the original package manager during the next invocation. That is convenient for ad-hoc work but unpredictable in a release window — a developer demoing on Friday afternoon does not want the CLI silently bumping mid-deploy.

Inside CI, auto-upgrade is skipped by default; CI containers respect their pinned shopify-cli version. Project-local installs (where the CLI lives inside the repo's node_modules) also skip auto-upgrade because the project manifest is the source of truth. Major version upgrades are skipped everywhere — the 4.0 → 5.0 jump will require an explicit opt-in. If you want to disable auto-upgrade outright on a developer machine, the Shopify CLI documentation documents shopify config autoupgrade off as the off switch.

SemVer: what it means for future minor and major upgrades

The CLI moving to SemVer is the quietly important change. Until 4.0, version numbers carried no contract — a "minor" bump could break commands and a "patch" could ship a feature. Going forward, a 4.x → 4.y bump (minor) ships features without breaking changes, a 4.x.y → 4.x.z bump (patch) ships bug fixes only, and any breaking change waits for a 5.0 release with explicit migration notes. For engineering teams running production deploys behind a CLI version constraint, this is the green light to pin to ^4.0.0 in package.json and trust that minor-version bumps will not break the pipeline.

How should engineering teams sequence the CLI 4.0 migration?

The right order minimises blast radius. Step one: audit every CI/CD pipeline and every developer's local package.json for the five removed commands and the --force flag. Step two: replace them with the modern equivalents while still on CLI 3.x — every replacement is back-compatible with the older CLI. Step three: bump to CLI 4.0 in a feature branch, run a full deploy dry-run against a development store, and confirm the --allow-updates/--allow-deletes behaviour matches the operational intent. Step four: pin ^4.0.0 in your engineering repo manifest and roll the update out to production CI runners. We typically see a full agency-grade migration land inside one engineering day for a single-app team, and 2-3 days when the rollout spans multiple Shopify Plus stores with different CI pipelines.

What to do next

If your CI/CD pipelines deploy Shopify apps weekly or more often, the --force removal is the change that warrants action this week — the next pipeline execution against CLI 4.0 will fail without it. If your team is on the Shopify AI Toolkit + Claude Code path covered in our production guide, audit the AI agent's CLI invocations as well: agentic deploy workflows that learned the pre-4.0 command shapes will hit the same deprecation wall. For teams running custom MCP integrations, our MCP server implementation guide covers the adjacent CLI flow most often paired with custom apps.

Anchor Loyalty is Live on the Shopify App Store (2026)

no7software — Fri, 22 May 2026 10:03:50 +0000

Anchor Loyalty & Rewards is live on the Shopify App Store. The Shopify App Store launch ships a Shopify loyalty app with points, VIP tiers, two-sided referrals, and a signed API for Hydrogen and other headless storefronts. Free plan included, paid tiers from around 14.99 USD per month, and the same loyalty data renders identically across admin, theme block, checkout extension, and customer account block.

What ships in the Shopify App Store launch

The listing at apps.shopify.com/anchor-loyalty ships four loyalty primitives merchants asked for. Points for purchases, referrals, signups, and spending milestones. VIP tiers with per-tier point multipliers and exclusive rewards. Two-sided referrals that reward both the inviter and the new customer in the same flow. Welcome bonus on signup. The Shopify App Store listing copy describes Anchor as "a complete loyalty system" — that is the surface we built, not a placeholder.

Anchor renders loyalty state inside the embedded admin, on the storefront via a native theme block, on the cart and checkout via a Shopify Checkout UI extension, and inside the customer account via the customer account block. Every surface reads from the same source of truth so the points balance on a product page matches the points balance on the order confirmation — no race conditions, no stale cache. Available in 32 languages out of the box (Arabic, German, Spanish, French, Hebrew, Hindi, Japanese, Korean, Polish, Portuguese (Brazil), Portuguese (Portugal), Russian, Thai, Turkish, Vietnamese, Simplified and Traditional Chinese, and more) — the same translation surface we use across our agency work powers the merchant-facing strings here.

Why we built it on Hydrogen and headless from day one

Our agency work is heavily Hydrogen and custom-storefront. We typically see a third of incoming Shopify Plus migrations land on a headless stack inside the first 18 months, and every loyalty app we have integrated has been the friction point: most apps ship a Liquid widget and a REST endpoint, neither of which compose cleanly with a React Server Components storefront. Anchor was architected the other way around. The data layer is a signed-token API; the native theme block and checkout extension are consumers of that API, not the source. Hydrogen and other headless storefronts read the same data through the same signed API as the native storefront block.

The practical consequence is concrete. A merchant running a Hydrogen storefront on Oxygen can render the points balance in a Server Component without proxying through a Liquid include. A customer account block on a native Online Store theme reads identical data. There is no fork between "native" and "headless" — the API surface is the canonical contract, and every UI block is a thin consumer.

How does Anchor pricing compare to the other Shopify loyalty apps?

Three plans, billed in USD per the App Store listing.

Anchor Loyalty plans

Free: up to 200 orders / month, up to 3 active rewards, customisable storefront widget, welcome bonus on signup, 32 languages.
Growth — around 14.99 USD / month (around 143.90 USD / year, saving 20%): up to 1,000 orders / month, up to 10 active rewards, up to 3 VIP tiers, referral program. 14-day free trial.
Pro — around 39.99 USD / month (around 383.90 USD / year, saving 20%): unlimited orders, rewards, and tiers; spending milestones; Checkout UI Extension (Shopify Plus only); the headless and Hydrogen JavaScript SDK; "Powered by" branding removed; priority support. 14-day free trial.

The free tier covers a real merchant — 200 orders a month with three active rewards is enough for a brand validating loyalty before committing to a paid plan. Growth is the typical first paid tier; Pro unlocks the headless SDK and the checkout extension, which is where most Shopify Plus stores will land.

What does Anchor do that the dominant loyalty apps do not?

The honest answer: we are entering a category with established incumbents (Smile.io, Recharge Loyalty,, the LoyaltyLion line), and the loyalty mechanic itself — points for purchases, tier multipliers, referrals — is mature. We did not invent a new loyalty primitive. We rebuilt the engineering surface around three constraints most loyalty apps ignore.

First, performance. Our December 2025 reflection on the science of retention measured 200-400 ms of JavaScript page-load weight from popular loyalty widgets — a measurable conversion drag on every visit, not just loyalty-engaged sessions. Anchor's storefront widget loads asynchronously and does not block the critical render path; the points balance hydrates after the buy button is interactive.

Second, headless parity. Most loyalty apps ship a Liquid block and an unsigned REST endpoint. We ship a signed-token API as the canonical contract and consume it from every surface — admin, theme block, checkout extension, customer account, Hydrogen. No fork.

Third, theme block depth. A loyalty surface buried three clicks deep in the customer account is invisible; a loyalty surface on the product page below the buy button is read. The native theme block is positioned for the latter pattern, and the customer account block is positioned for visible engagement rather than archival lookup.

How merchants install and configure Anchor

Installation is the standard Shopify OAuth flow. Hit Install on the App Store listing, approve the requested scopes, and the embedded admin loads in around 5-10 seconds. The first-run flow walks through three steps: set the point-earning rate (default 1 point per 1 currency unit spent, adjustable per merchant), enable or skip VIP tiers, and enable or skip referrals. Every step has a sensible default — a brand-new merchant can install Anchor and ship the storefront block in well under 30 minutes.

Anchor inherits the platform's compliance posture out of the box. Loyalty data is scoped to the merchant's tenant; we never touch cross-store data; the API tokens are signed per merchant and rotate on the same cadence Shopify's own session tokens do. Merchants on regulated stacks ask us this — the answer is the same one we publish in our ecommerce security headers guide: defaults that fail closed, not open.

What is on the immediate roadmap

The launch surface is the floor, not the ceiling. The next three engineering quarters concentrate on four things. First, the headless JavaScript SDK that ships in the Pro tier — currently in alpha, generally available shortly after launch. Second, Shopify Flow triggers and actions so merchants can fire loyalty rewards from Flow workflows alongside the rest of their automation. Third, deeper segmentation that lets merchants run "dormant member re-engagement" campaigns from Anchor without exporting to a separate CRM. Fourth, a metafield-backed merchant API extension that exposes loyalty tier as a customer attribute so theme and Hydrogen code can branch on it natively.

What to do next

If your store is on Shopify or Shopify Plus, hit Install on apps.shopify.com/anchor-loyalty and take the Free plan for a spin. Two hundred orders a month and three active rewards is enough to validate whether loyalty moves your numbers before you commit to a paid tier. If you are running Hydrogen or a custom storefront and you want the headless SDK preview, the Pro plan unlocks it; reach out to our team and we will walk you through the integration patterns we ship in our agency engagements.

If you are still evaluating the loyalty category, the December 2025 reflection on how Anchor is redefining Shopify growth walks through what we learned about loyalty apps before we shipped — performance, integration depth, and the mechanics that actually move retention. It pairs with this launch announcement; one is the "why we built it" essay, this one is the "we built it; here is where to find it" page.

GitHub VS Code Extension Breach 2026: Engineering Response

no7software — Thu, 21 May 2026 10:48:37 +0000

GitHub's 20 May 2026 incident — around 3,800 internal repositories exfiltrated after a single poisoned VS Code extension compromised one employee device — confirms the github vs code extension breach pattern most security teams had ignored. The editor itself is now a supply-chain surface. The container, not the code, was the entry point.

What happened in the GitHub VS Code extension breach on 20 May 2026

GitHub's incident response thread on 20 May 2026 stated that a single employee device was compromised through a poisoned VS Code extension. The attacker reached around 3,800 GitHub-internal repositories before the endpoint was isolated. Critical secrets were rotated overnight, with the highest-impact credentials prioritised first.

The blast radius was confined to internal repositories. GitHub stated there is no evidence of impact to customer information stored outside its internal estate — meaning the enterprises, organisations, and repositories owned by customers were not touched in the breach window. The published timeline shows the malicious extension version was removed, the endpoint was isolated, and incident response began on the same day the activity was detected. We typically see public companies take 4-7 days to acknowledge a breach of this size; GitHub's containment-to-disclosure window was roughly 24 hours.

How a poisoned VS Code extension exfiltrates internal repositories

The VS Code Marketplace hosts more than 60,000 published extensions and Microsoft's own extension marketplace documentation notes that extensions run with the same operating-system privileges as the editor itself. There is no per-extension sandbox. An extension that ships a benign 1.0.0 release can quietly push 1.0.1 with a malicious payload, and every developer with auto-update enabled receives it on the next editor restart.

The exfiltration chain is concrete. The poisoned extension reads files inside the user's workspace, scans the developer's shell history for tokens, and accesses any credentials cached by GitHub CLI (gh auth token), Git Credential Manager, or the official GitHub Pull Requests and Issues extension. From there, the attacker has the same git push and API authority as the compromised engineer. If that engineer is part of an internal org with broad repo scope, the attacker walks the org's repository graph and clones whatever the token can read.

In our work with Shopify Plus and BigCommerce engineering teams, this is the model we see most teams completely underestimate. The token that lives inside ~/.config/gh/hosts.yml usually has scopes for every private app repo, every CI runner, and the build artefacts behind them. A single poisoned extension does not need malware, root access, or a network exploit — it just needs read access to a few well-known files in the developer's home directory.

Why this is a supply-chain attack, not a credential leak

The framing matters because the remediation is different. A credential leak — a single token posted in a Slack thread — gets fixed by rotating that one token. A supply-chain compromise inside the developer's editor means every credential, environment variable, or session token the engineer touches during the compromise window is potentially exposed.

GitHub's response confirms this. The thread explicitly says "critical secrets were rotated yesterday and overnight with the highest-impact credentials prioritised first." That phrasing is not the language of single-token rotation. That is the language of a credential-rotation programme covering every secret the compromised engineer could plausibly have touched, prioritised by blast radius.

How should engineering teams audit their VS Code extension policy?

Most engineering teams we audit have zero policy around VS Code extensions. The IDE is treated as a personal-productivity tool rather than a production-adjacent attack surface. After the GitHub breach, that posture is indefensible. There are four concrete questions every engineering lead should answer this week.

VS Code extension audit checklist (post-GitHub breach)

Which extensions are installed? Run code --list-extensions --show-versions on every developer workstation. Diff against an approved list. Unknown extensions become approved-or-removed within 48 hours.
Who publishes each approved extension? Pin to publishers you trust (Microsoft, ESLint, Prettier, established vendors). A 12,000-install extension from an anonymous publisher is a higher-risk surface than a 50-million-install extension from Microsoft.
Are extensions allowed to auto-update? Default behaviour is yes. Disable extensions.autoUpdate and pin specific versions in workspace-level .vscode/extensions.json for client work so a poisoned 1.0.1 push cannot land without review.
Where are GitHub tokens cached? Audit ~/.config/gh/, ~/.gitconfig, ~/.git-credentials, and any local .env files. The attacker did not need root to read them.

Detection patterns: what GitHub did right that most teams cannot replicate

GitHub's response window — detection, containment, public disclosure within 24 hours — is exceptional. It is also unrepeatable for the vast majority of engineering teams. GitHub operates a dedicated security operations team with real-time endpoint telemetry, deep audit logs on every internal repository clone, and the institutional muscle memory to rotate thousands of secrets overnight.

Your engineering team almost certainly cannot do any of that in under a week. The lesson is not "be more like GitHub" — it is "build the prevention layer because the response layer is unaffordable." Preventing the extension from running in the first place is roughly 100x cheaper than detecting that it ran and reconstructing what it touched.

Practical hardening steps for Shopify and BigCommerce engineering teams

The threat model maps directly onto eCommerce engineering work. If your team builds custom Shopify apps, Hydrogen storefronts, or BigCommerce headless integrations, the developer workstation holds API keys with deep access to client stores. A compromised workstation does not just leak a single token — it can rewrite published apps, push malicious storefront commits, or exfiltrate customer data via API calls that look entirely legitimate to the platform.

The remediation is procedural, not technical. Most of it costs around £0 to implement and takes a single sprint.

Allowlist extensions per repository. Commit a .vscode/extensions.json with the recommended list, and disable auto-update for the workspace. New extensions require a PR.
Use scoped tokens, never personal access tokens. Generate fine-grained tokens per repository with the minimum required scopes — contents:read only for read paths, contents:write only where push is genuinely needed. Personal access tokens with repo scope are an unbounded liability.
Rotate the GitHub CLI auth token monthly. Run gh auth refresh on a scheduled job. A token that lives for six months has six months of exposure if a single extension goes bad.
Separate the workstation from the production-token environment. Production deployment credentials should live in CI runners with short-lived OIDC-issued tokens, not on the engineer's laptop. We cover the pattern in our Shopify AI Toolkit production guide — the same separation applies to any agent-driven workflow.

How does this affect AI-assistant integrations like Claude Code and Copilot?

The GitHub incident reframes a question we get often: is it safe to give an AI assistant — Claude Code, GitHub Copilot, Cursor, the Shopify Dev MCP server — access to your engineering workstation? The answer is not "no". The answer is "only with the same hardening you would apply to any other extension."

AI-assistant extensions are software extensions. They run with the editor's privileges. They have read access to your workspace, your environment variables, and the same shell history any other extension can see. GitHub's own secret-scanning documentation already warns that any cached credential is a target. The arrival of mainstream agentic-coding extensions raises the value of compromising a developer workstation by an order of magnitude — the attacker no longer needs to wait for the engineer to push code; the agent will push it for them if the attacker can plant a prompt in the project repo.

What to do next

If you operate a small engineering team without a dedicated security function, three actions matter more than the rest. Run an extension audit today across every developer workstation. Replace personal access tokens with fine-grained tokens scoped to specific repositories. Disable extension auto-update for any workspace that holds production credentials.

If you operate a larger team or run client engagements where a compromise would have legal weight, treat the GitHub breach as the catalyst for a formal IDE policy. Specify the approved extension list, the token-rotation cadence, the credential-storage rules, and the incident-response runbook for the case where a workstation does get compromised. The cost of writing that policy is around 2-3 days of senior engineering time. The cost of replaying GitHub's 20 May 2026 response without GitHub's team is significantly higher.

Hydrogen MCP UCP Migration: Production Cutover Before June 15

no7software — Fri, 15 May 2026 08:28:14 +0000

Shopify flipped the Storefront Catalog MCP server to the Universal Commerce Protocol on April 22, 2026, per the official Shopify developer changelog. The old /api/mcp endpoint and the previous search_shop_catalog and lookup tool names are deprecated. Both stay live until June 15, 2026 — then they go away. Any Hydrogen storefront, custom AI agent, or third-party integration that still calls the old endpoint after the sunset will fail.

In our experience, this is one of those changes that reads as a footnote on the changelog and lands as a production incident two weeks before the deadline. The work itself is small: an endpoint rename, two tool renames, and a response-schema check against the new UCP catalog spec. The risk is that it is easy to defer until something visible breaks. For Shopify Plus engineering teams running Hydrogen, this is also not the only change in motion. The Hydrogen Winter 26 release made every Hydrogen storefront on Oxygen an MCP-ready endpoint by default, and the Storefront API proxy that exposes the new /api/ucp/mcp path is now expected to be in place. Sequencing matters — UCP assumes the proxy is already wrapping your storefront routes.

The 90-Second Engineering Action List

What changed, in six lines

Endpoint: /api/mcp deprecated; new endpoint /api/ucp/mcp.
Hard sunset: June 15, 2026 — after that, the legacy endpoint and the previous tool names stop responding.
Tool renames: the previous search_shop_catalog maps to search_catalog; the previous lookup tool maps to lookup_catalog; get_product is the new full-product retrieval tool with interactive variant selection and availability signals.
Request and response shapes: updated to match the UCP catalog spec — re-run your client-side schema validation against the published UCP catalog reference.
Hydrogen Winter 26: Storefront MCP is supported on every Hydrogen storefront on Oxygen out of the box. UCP assumes the Storefront API proxy is in place.
Action sequence: grep /api/mcp in your codebase, rename the endpoint, rename the tool calls, validate the response shape against the UCP spec, run a parallel test suite, ship before June 15.

What the Rename Actually Breaks

In our experience, three things tend to break in a half-finished UCP migration. The first is the endpoint. The line is short and easy to find, but easy to miss in a team where MCP calls live in two or three different services — replace https://{storeDomain}/api/mcp with https://{storeDomain}/api/ucp/mcp wherever it appears.

The second is the tool names. We have seen merchants update the endpoint, deploy, and then stare at JSON-RPC errors for an hour because their agent still sends name: "search_shop_catalog" instead of name: "search_catalog". The renames are deterministic — Shopify's changelog is explicit that the previous search and lookup tools are deprecated in favour of search_catalog, lookup_catalog, and get_product, and that the request and response shapes are updated to match UCP.

The third is the response shape itself. UCP is a layered protocol with capability declarations alongside the commerce payload. The shape of a get_product response now follows the UCP catalog specification — pricing, availability, options, and variant data have moved to UCP-aligned fields. Treat the Storefront Catalog MCP documentation as the authoritative reference for the new schemas; client code that hard-coded the legacy field paths will silently produce wrong data, not a hard error, which is the worst kind of regression.

UCP Capability Negotiation Explained

The reason this migration looks small in the changelog and matters more than that in practice is that UCP is not an evolution of MCP — it is a layered protocol with a different mental model. UCP is the Universal Commerce Protocol, co-developed by Shopify and Google and published openly at NRF 2026. The Shopify engineering team describes it as a layered design that separates commerce surface area into three concerns: a shopping service layer that defines core primitives (checkout sessions, line items, totals), capabilities that group functional areas (Catalog, Checkout, Orders) each independently versioned, and extensions that augment capabilities with domain-specific schemas via composition.

What this means for engineering teams is that the response payload now tells you what the merchant supports. If a merchant has a loyalty-vendor extension active, your agent can negotiate reward redemption. If it does not, you get the core checkout schema and your agent should gracefully degrade. UCP uses reverse-domain naming (dev.ucp.shopping.* for the official spec, com.merchantvendor.* for vendor extensions), which means there is no central registry — capabilities can be added by merchants, payment providers, or loyalty vendors without waiting for protocol committees.

The architectural shift this implies for client code: your agent should stop assuming a fixed product schema and start branching on the merchant-declared capabilities. We have found this is the single most common source of latent bugs after the rename — code that worked because the old MCP returned exactly one schema now silently misses fields when capabilities are negotiated differently per merchant. For deeper context on how UCP relates to ACP and the older MCP-only patterns, see our breakdown of agentic commerce protocols.

Hydrogen Winter 26 and the Storefront API Proxy

Per the Hydrogen Winter 26 update, every Hydrogen storefront on Oxygen now supports Storefront MCP, with custom AI agents able to give customers personalised recommendations, manage carts, and walk buyers through checkout — all powered by real-time data through the Storefront API. UCP runs on the same proxy layer that exposes the storefront to AI agents.

For teams already on the latest Hydrogen release, this is a non-event for UCP — the proxy layer is in place and the only work is the endpoint and tool rename. For teams on older Hydrogen releases, there is an extra migration to sequence. The proxy migration must happen first because UCP assumes the proxy is wrapping all storefront routes; without it, the new /api/ucp/mcp endpoint will not be exposed correctly.

Hydrogen Winter 26 also exposes the Dev MCP server for AI coding tools like Cursor and Claude, giving them access to comprehensive Hydrogen documentation, Storefront API references, and the Hydrogen Cookbook. We have found that pulling the Dev MCP into your IDE during the UCP migration significantly reduces the time spent looking up new schema field paths. If your team is sequencing the broader changes alongside UCP, the order is: confirm the Storefront API proxy is wrapping your routes, audit consent-mode handling on that proxy layer, then ship the UCP endpoint and tool rename. For broader Hydrogen production context, see our Hydrogen 2.0 production-readiness guide.

Step-by-Step Migration Diff

We typically execute UCP migrations as a six-step sequence. The work is small, but auditable steps make rollback cheap.

Update the endpoint constant. Replace the literal /api/mcp path with /api/ucp/mcp wherever your code constructs the MCP URL. Include environment variables, deployment manifests, and any shared SDK constants in the search.
Rename tool calls. Wherever your agent invokes search_shop_catalog, swap to search_catalog. Wherever it invokes the previous lookup tool, swap to lookup_catalog. get_product is the new full-product retrieval tool — expect the UCP-aligned response shape rather than the legacy Storefront MCP fields.
Update request shapes against the UCP spec. The core argument keys (query, context) carry over conceptually, but Shopify's changelog explicitly states that the request schemas are updated to match UCP. Treat the Storefront Catalog MCP documentation as the authoritative reference for the new request shape and validate against it before shipping.
Verify response field locations. The legacy Storefront MCP returned a flat structure with product_name, price, variant_id, and image_url at the top level. Under UCP the product, pricing, availability, and option data follow the UCP catalog spec, which structures them differently. Re-run your client-side schema validation rather than assuming the legacy field paths still resolve.
Run integration tests in parallel. Keep one suite hitting /api/mcp and a duplicate hitting /api/ucp/mcp. Both should pass during the transition window, then drop the legacy suite once the new endpoint is canonical in production and the old endpoint is no longer in use.
Ship before June 15. Aim for at least 14 days of canary traffic in production before the sunset, so any latent regression has time to surface under realistic load.

Decision Framework: UCP, Direct Storefront API, or Custom MCP

When to use each pattern

Three commerce-data access patterns now coexist on a Hydrogen storefront. Use this matrix to pick the right one for the job.

Requirement	UCP via /api/ucp/mcp	Direct Storefront API	Custom MCP server
Latency	Medium (proxy + UCP wrap)	Low (direct GraphQL)	Medium-high
Auth	Storefront access token	Storefront/Admin token	Custom (your stack)
Schema versioning	Capability-negotiated	Storefront API version	You own it
AI agent compatibility	Native (MCP binding)	Requires wrapper	Native
Best for	Public agentic search and cart	Frontend rendering	Bespoke enterprise tools

In our experience, the right default for AI-agent-facing surface area is UCP via the Hydrogen proxy. Direct Storefront API calls remain the right choice for your own frontend rendering — there is no reason to pay the UCP wrapping overhead for code you control. Custom MCP servers make sense only when you have bespoke commerce capabilities (custom B2B pricing tiers, ERP-driven inventory rules) that the standard UCP catalog capability cannot model, and even then, we recommend implementing them as UCP extensions under your own reverse-domain namespace rather than as a parallel protocol. The architectural patterns for scaling a custom MCP layer in production are covered separately in our scaling patterns post.

Testing the Cutover Before June 15

The migration is only as safe as the test suite that verifies it. We typically build a parallel suite that hits both endpoints with the same set of fixtures, asserts the response shapes, and gates the legacy suite removal on a clean canary in production.

The first pattern is fixture parity. Capture a set of representative agent requests from production logs, replay them against both /api/mcp and /api/ucp/mcp, and diff the response shapes. The legacy endpoint should still match the old schema; the UCP endpoint should match the new one. Any drift is a sign that your client code is making assumptions that one or the other endpoint does not satisfy.

The second is canary traffic gating. We have found that 1% of agent traffic to the new endpoint for 48 hours is enough to surface most schema-coupling bugs. If you do not have feature-flag infrastructure for agent traffic, a header-based router ahead of the storefront works — branch on a custom header like X-UCP-Migration: enabled for internal testing accounts before cutting over the full agent population.

The third is the sunset rehearsal. Before June 15, point your test suite at a Pilot or staging storefront where the legacy endpoint is already disabled. This forces every code path that quietly depends on the old endpoint to fail loudly, in test, where you can fix it. Sunset rehearsals are how you catch the half-migrated dependency that nobody remembered was still on the old tool name. For teams already running Shopify Functions in production, the same fixture-from-production pattern applies — the broader testing strategy is covered in our post on Shopify Functions in production.

What to do next

If you run a Hydrogen storefront with any custom AI agent integration, the migration is on a fixed clock. We recommend the following sequence over the next 30 days:

Audit your codebase. Run grep -r "/api/mcp" across every service that talks to your Hydrogen storefront — including custom agents, Slack integrations, ERP middleware, and any internal tooling. The endpoint is also commonly referenced in environment variables, so include .env, wrangler.toml, and any deployment manifests.
Confirm your Hydrogen version. If you are on 2026.3.x or earlier, schedule the proxy and consent-mode migration first. UCP will not work cleanly without the proxy in place, and consent state desync is a quiet failure mode that is expensive to debug after the fact.
Update the endpoint and tool names. The two-line fix is as small as it reads. Keep the legacy endpoint operational in your codebase until the parallel test suite is green.
Validate response shapes. Map every property your client code reads from MCP responses to its UCP equivalent. Treat the Storefront Catalog MCP documentation as the authoritative schema reference rather than relying on the legacy Storefront MCP field paths.
Plan the canary cutover. Aim to land the new endpoint in production with at least two weeks of parallel running, and complete the cutover well ahead of the June 15 sunset rather than racing it.

For most teams, this is a one-day engineering exercise. The hard part is not the rename — it is making sure the migration is sequenced correctly with the proxy and consent changes that landed alongside it. If your storefront is on Hydrogen and you have not yet looked at this, the cost of acting now is much lower than the cost of acting on June 14.

For broader headless context, see our Catalyst vs Hydrogen comparison and our breakdown of Shopify's four native MCP servers. If you are running a Shopify Plus migration alongside the UCP cutover, our Shopify Plus migration service covers the architecture and risk-register work that keeps both threads from colliding mid-cutover.

Shopify Quietly Auto-Shipped /llms.txt, /agents.md and /.well-known/ucp — Engineering Override Guide (2026)

no7software — Thu, 14 May 2026 12:31:27 +0000

Some time in the first week of May 2026, Shopify quietly turned on four agent-facing endpoints across the platform — no changelog post, no email, no banner in the admin. Open any Shopify store's /llms.txt, /agents.md, /.well-known/ucp, or /sitemap_agentic_discovery.xml in a browser and a generated file loads. Nobody on the merchant's team made them. Shopify is serving them. Live probe across a sample of UK and US Plus stores on 13 May 2026 confirms the rollout: Allbirds, Allbirds UK, and Kylie Cosmetics all return 200 on the full set; some smaller and headless stores still 404, which suggests the rollout is store-by-store rather than instantaneous.

The infrastructure side of the Universal Commerce Protocol rollout has now landed in production for most merchants. The interesting engineering work is no longer "do we have agentic endpoints"; it is "do the defaults fit our store, and if not, how do we override them safely". This post is the engineering view of that decision — what auto-shipped, what the defaults actually contain, when to leave them alone, when to override via theme Liquid, the multi-region Shopify Markets trap that catches most multi-storefront merchants today, and how to wire the new commerce-readiness.shopify.io scanner into CI.

What auto-shipped, verified

Four endpoints now resolve on a default Shopify storefront without any merchant work. The shapes are stable enough to write integrations against:

The four default agent-facing endpoints

Path	Content	Editable
/llms.txt	Markdown manifest pointing agents at search, agents.md, UCP discovery, MCP endpoint, sitemap	Yes — templates/llms.txt.liquid
/agents.md	Long-form agent operating manual: UCP discovery flow, supported versions, checkout rules, rate-limit guidance	Yes — templates/agents.md.liquid
/.well-known/ucp	JSON UCP merchant profile: supported versions, transports, services, capabilities, payment handlers	No — generated from store config
/sitemap_agentic_discovery.xml	Discovery index listing /llms.txt, /llms-full.txt, /agents.md with weekly changefreq	No — generated from storefront state

What an agent gets when it hits these endpoints out of the box, on a real store today (Allbirds UK, abbreviated):

The default llms.txt opens with the store name and one-line description from the storefront settings, then lists the canonical browse URLs (/collections/all and a /search?q={'{'}query{'}'} template), basic store metadata (currency, contact email, phone), and a "For Agents & Developers" block that points at agents.md, the UCP discovery endpoint, and the MCP endpoint at /api/ucp/mcp — note the new UCP path, not the legacy /api/mcp we covered in the Hydrogen MCP→UCP migration guide. The default closes with a Shopify-branded footer linking to shopify.com/start; we will come back to that.

The default agents.md is the more interesting file — it reads like an operator's manual aimed squarely at AI agents. It declares the supported UCP versions (currently 2026-04-08 stable and 2026-01-23), spells out the six-step agent flow (Discover → Search → Cart → Checkout → Fulfill → Complete), and includes hard rules every agent must respect: checkout requires explicit human approval, the MCP endpoint is per-IP rate-limited, and buyer context (country, currency) must be passed for correct pricing.

When to leave the defaults alone

The defaults are good for the median store. If you sell in one currency, on one domain, in one language, with a healthy /pages/about, /pages/contact, /pages/faq, and /pages/shipping, the auto-shipped llms.txt and agents.md point agents at the right places and represent your store accurately. Leave them alone. Override is configuration debt you do not need to take on.

The defaults stop being good in three situations: multi-region or multi-language stores running Shopify Markets, high-AOV or regulated stores that need to declare agent constraints the default does not cover (age verification, prescription gating, B2B-only catalogues), and brands that do not want the Shopify-branded promotional footer appearing in their agent-facing files. Each of these wants a Liquid template override.

Override pattern: templates/llms.txt.liquid

Shopify uses the same theme-asset pattern as robots.txt.liquid. Drop a file at templates/llms.txt.liquid and Shopify renders it in place of the default for every request to /llms.txt. A minimal override that removes the Shopify-branded footer and adds your brand-specific guidance might look like:

The file is plain Liquid with the same objects you use in a normal theme — shop, request, localization, collections — so you can interpolate live store data. A practical override starts from a copy of the rendered default, removes what does not apply, and adds the sections your category needs. For example, a regulated category (alcohol, supplements, age-restricted goods) should add a header line declaring the constraint so the agent does not try to complete a checkout it cannot legally close:

The pattern works identically for templates/agents.md.liquid. The longer agent operating manual is where most of the per-store nuance belongs — checkout-state preconditions for B2B-only catalogues, returns and exchange policies referenced as URLs the agent can fetch, fulfilment-method constraints for cold-chain or hazmat products, and any market-specific currency or shipping notes the default cannot infer from shop.metafields.

The Shopify Markets multi-region trap

This is the single biggest gotcha for engineering teams running international storefronts in May 2026. The default /llms.txt sits at the root of each domain — example.com/llms.txt, example.de/llms.txt, example.fr/llms.txt — but it does not currently translate the link metadata, currency, or language attribution across markets. An agent landing on the wrong domain reads the canonical catalogue at the wrong locale and pulls a price the buyer would not actually see at checkout.

In practice we see two symptom classes. First, an agent fetches /llms.txt on a country domain and follows the collections/all link, but the products it surfaces are described in the store's default language rather than the locale the user is shopping in. Second, currency-divergent storefronts (a GBP UK domain and a USD US domain on the same Markets setup) show consistent llms.txt currency metadata while the actual cart pricing applies a market-specific override at checkout — the agent's quote and the buyer's checkout disagree by 8-12% depending on the currency pair and shipping origin.

The fix until Shopify ships native Markets-aware llms.txt is to override the template per market. In templates/llms.txt.liquid branch on localization.country.iso_code and shop.currency, emit the canonical URLs that route through Shopify Markets' per-market routing, and explicitly tag the currency in the Store Information block. The same logic applies to templates/agents.md.liquid for the agent operating manual itself, where you also want to advertise which UCP versions and capabilities your specific market negotiates — they can drift from the platform default for storefronts running custom checkout extensions.

What /.well-known/ucp actually declares

The UCP discovery endpoint at /.well-known/ucp is the JSON manifest an agent reads first. It is generated by Shopify from your store configuration — there is no Liquid template override for this file, and you should not want one. Hand-editing it would invite drift between what your store actually supports and what your discovery document claims, which is exactly the failure mode the protocol exists to prevent.

What you get is a JSON document declaring the negotiated UCP version (2026-04-08 at the time of writing, with 2026-01-23 still supported for fallback), the transports the store accepts (mcp over HTTP and embedded for in-conversation surfaces), the services advertised — dev.ucp.shopping currently — and the capabilities each service exposes. For a default Shopify storefront in May 2026 the capabilities array includes checkout, fulfillment (extending checkout and cart), and discount (also extending checkout). Each capability declares its protocol minimum and its config — for example, allows_multi_destination.shipping: false on default Shopify, which is one of the constraints an agent must respect when building a cart for a buyer.

If your store needs to advertise a different capability set — a custom subscription handler, a non-default fulfilment provider, a payment method outside Shopify Payments — the path is Shopify Functions and app extensions, not a Liquid override. The discovery JSON regenerates from your active app graph.

Wire the readiness scanner into CI

Shopify also shipped a public agentic-readiness scanner at commerce-readiness.shopify.io. It runs 31 checks across five categories — Agent Discovery, Product Intelligence, Transaction Readiness, Store Quality, and Operational Readiness — and the failures it surfaces are deterministic enough to wire into CI rather than treating as a one-off audit.

What it actually probes is unromantic. Does /llms.txt, /agents.md, and /.well-known/ucp return 200. Does /products/{'{'}handle{'}'}.json resolve for every product in the catalogue. Are sitemaps reachable, including locale variants. Do /pages/about, /pages/contact, /pages/faq, /pages/shipping contain real HTML rather than redirects, modal overlays, or Notion embeds. If you have been doing product-data hygiene already, the score is high; if you haven't, this is the first time anyone is putting a number on it.

For an engineering team the value is not running the scanner once and screenshotting the score. The value is running it on every theme deploy, parsing the per-category JSON output, and failing the pipeline if any of the four Agent Discovery checks regress. We typically wire this in as a post-deploy job in GitHub Actions or the Shopify CLI deploy script — request the scan, poll for completion, fail loudly if any category drops below threshold. The scanner does not require auth and is rate-limited at a level that comfortably handles a deploy-time call per store.

Decision matrix: what to override, what to leave alone

Override decisions for the four endpoints

Situation	llms.txt	agents.md	.well-known/ucp
Single-region, single-currency, single-language store	Leave default	Leave default	Read-only
Shopify Markets multi-region	Override	Override	Read-only
Age-restricted / regulated category	Override (declare gate)	Override (declare rules)	Read-only
B2B-only catalogue	Override (auth note)	Override (declare rules)	Read-only
Premium brand wants no Shopify footer	Override (trim footer)	Leave default	Read-only

How this connects to the wider AI visibility audit

The agentic endpoints are the new floor. Every Shopify store has them now, so they are no longer a differentiator on their own. The differentiation lives in the layer above — the technical signals AI search engines (ChatGPT Search, Perplexity, Claude Web, Google AI Overviews) use to decide whether your domain is citation-worthy at all, separate from whether an agent can transact on your store. Speakable spec on long-form content, AI crawler allow-list in robots.txt, structured-data depth on every page, llms-full.txt corpus quality, and entity authority via sameAs links to Crunchbase, LinkedIn, GitHub are the signals that move citation share. Our free AI visibility tool scores all eight of those signals on any domain in 5-10 seconds and emails a remediation plan — it is broader than the Shopify-specific scanner, and we recommend running both: commerce-readiness.shopify.io for the agentic-transaction floor, the visibility audit for the discovery-and-citation ceiling.

If you want help shipping the overrides — multi-region llms.txt work, custom agents.md rules for regulated categories, CI-wired readiness scans on every theme deploy — that is fixed-scope engineering work we quote on. The faster path is to talk to engineering with the store URL and the override scope, and we will come back with a quote inside one working day.

Shopify AI Toolkit in Production: 19 Skills and Safe Execution (2026)

no7software — Wed, 13 May 2026 06:41:43 +0000

The April 2026 release of the open-source Shopify AI Toolkit gives Claude Code 19 dedicated skills to manipulate Shopify environments directly, but running shopify store execute with the --allow-mutations flag introduces severe live-store risks. For agency teams, adopting this Apache 2.0 toolkit requires strict multi-store credential scoping, domain pinning, and a Git-backed rollback strategy before it touches production.

The 19-skill architecture and forced validation loop

The repository at github.com/Shopify/shopify-ai-toolkit fundamentally changes how autonomous agents interact with Shopify codebases. Instead of relying on an LLM's static training data—which often hallucinates deprecated REST endpoints or obsolete Storefront API structures—the toolkit exposes 19 discrete skills to Claude Code. These cover the entire stack: shopify-admin for Admin GraphQL design, shopify-liquid for theme architecture, shopify-hydrogen for headless builds, and shopify-functions for backend extensibility.

The critical engineering pattern here is the forced validation loop. Every skill directory ships with two executable scripts: scripts/search_docs.mjs and scripts/validate.mjs. The system prompt defining each skill strictly mandates that Claude Code must execute these scripts to verify syntax and schema compatibility before returning a response to the developer.

In our experience, this validation step reduces API hallucination rates to near zero. However, it shifts the engineering bottleneck. You are no longer debugging bad code generation; you are managing the risk of an agent successfully executing highly destructive, perfectly formatted commands against your store infrastructure.

The danger of use-shopify-cli and the mutation gate

The most volatile component of the toolkit is the use-shopify-cli skill. This acts as the primary execution engine. When Claude Code determines it needs to read store state or apply a structural change, it uses this skill to invoke shopify store execute under the hood.

By default, the CLI restricts these agent-driven commands to read-only queries. This is safe for auditing catalogue data, verifying webhook subscriptions, or pulling metafield definitions. The danger arises when the --allow-mutations flag is appended. This flag acts as the gatekeeper, authorising the agent to fire state-changing Admin GraphQL mutations directly at the connected store.

There is no draft mode in the Admin API, and there is no undo button for a bulk execution. If Claude Code hallucinates the business logic—perhaps misunderstanding a prompt and deleting all product variants instead of updating their pricing tier—the data is instantly gone. We typically see teams leave this flag enabled during local testing out of convenience, which inevitably leads to accidental production data loss when the CLI context is misconfigured or points to the wrong environment.

How to scope multi-store credentials for safe execution

To use the use-shopify-cli skill safely, you must isolate the execution environment. Relying on developer discipline to verify the active CLI context before approving a Claude Code prompt is a failing strategy. Here is how to configure your environment to prevent catastrophic agent actions.

Pin the target store domain via environment variables. Do not allow the CLI to infer the store from the current directory's configuration file. Explicitly export SHOPIFY_SHOP=your-staging-store.myshopify.com in your shell profile before launching Claude Code to force the context to a safe environment.
Provision a restricted, task-specific access token. Never authenticate the agent using your primary Partner account credentials. Generate a custom app token in the Shopify Admin with the absolute minimum scopes required (for example, strictly write_products and nothing else) and feed this specific token to the CLI.
Enforce a pre-mutation Git-backed state export. Before you append the --allow-mutations flag to any agent prompt, run a read-only query to dump the target objects into a local JSON file. Commit this file to Git. If the agent corrupts the data, you have a structured payload ready for a restoration script.
Audit the validation script outputs manually. Intercept the output of scripts/validate.mjs. Review the exact GraphQL payload the agent intends to send in your terminal before you authorise the final execution step.

Decision Matrix: AI Toolkit vs Custom MCP Server

When deciding how to connect LLMs to your Shopify infrastructure, compare the built-in AI Toolkit against custom implementations.

Shopify AI Toolkit (19 Skills): Best for general app development, theme building, and standard Admin API tasks. It requires zero infrastructure setup but limits you to Shopify's official documentation and CLI capabilities.
Hand-built MCP Server: Best when you need to expose proprietary agency logic, external PIM data, or custom ERP endpoints to the agent. Building this typically costs £15,000-£30,000 in agency time, but provides absolute control over the execution context and authentication scoping.
Raw Admin API via Scripts: Best for deterministic, high-volume data migrations where agent autonomy is a liability, not an asset. Do not use LLMs for bulk data insertion.

If you are leaning towards the custom route to integrate external systems or proprietary logic, read our Shopify MCP Server implementation guide to understand the authentication requirements and latency targets required for production deployment.

Compiling WebAssembly via the shopify-functions skill

The toolkit also addresses backend extensibility through the shopify-functions skill. Shopify Functions cap each invocation at roughly 11 million WebAssembly instructions, making code efficiency critical. When Claude Code writes a custom discount or delivery configuration in Rust, the validation script ensures the code compiles to a valid .wasm binary before attempting deployment.

This prevents the agent from deploying syntactically correct Rust that fails Shopify’s strict memory and instruction limits during the build phase. However, the agent cannot inherently profile the WebAssembly execution cost. You must still pull the compiled function and run it through the CLI's replay tool to verify it executes within the allowed instruction bounds. Relying solely on the toolkit’s validation loop for performance metrics will result in production timeouts.

Handling Polaris variants and UI extensions

The toolkit is not limited to backend logic. It includes specific skill variants tailored for frontend surfaces, particularly Polaris. There are distinct skills for admin, app-home, checkout, and customer-account extensions.

This granularity is crucial. A checkout UI extension has entirely different component constraints and network access rules compared to an admin block. By routing Claude Code through the specific shopify-pos-ui or checkout skill, the agent is forced to validate its code against the correct subset of the Polaris library.

The recent update to the Shopify.dev MCP server, which now explicitly supports Polaris web components, directly complements these toolkit skills. The agent can pull the latest component specifications dynamically, ensuring that the React code it generates relies on current, non-deprecated props rather than hallucinated legacy components.

Integrating with the Storefront and UCP ecosystem

Beyond the Admin environment, the toolkit includes shopify-storefront-graphql and shopify-hydrogen skills. These are designed to navigate the complexities of headless commerce, where query optimisation directly impacts user experience metrics.

We typically target an INP (Interaction to Next Paint) under 200ms for category pages. When Claude Code generates Storefront API queries, the scripts/validate.mjs loop ensures the query adheres to pagination best practices and does not request overly nested, expensive fields that would degrade edge-cached performance.

Furthermore, these skills integrate cleanly with the wider Model Context Protocol ecosystem. With the Storefront Catalog MCP now implementing the Universal Commerce Protocol (UCP), the agent can reason about product taxonomy across different platforms. For teams scaling these architectures, managing context windows becomes the primary challenge, as detailed in our analysis of Shopify Storefront MCP scaling patterns.

What to do next

Adopting the Shopify AI Toolkit changes how your engineering team interacts with the platform, but it requires immediate governance. Do not simply install the toolkit and grant Claude Code unrestricted access to your CLI.

First, pull the repository from github.com/Shopify/shopify-ai-toolkit and inspect the scripts/validate.mjs logic for the skills your team uses most frequently. Understand exactly what the script checks and what it ignores. Second, audit your local environment variables. Ensure that multi-store credentials are strictly isolated and that developers cannot accidentally execute a mutation against a production store. Finally, run a dry-run exercise. Prompt Claude Code to perform a complex catalogue update without the --allow-mutations flag, and manually verify the generated GraphQL payload before considering it safe for live execution.

Catalyst vs Hydrogen: Engineering Decision Guide (2026)

no7software — Tue, 12 May 2026 06:41:01 +0000

The debate surrounding headless ecommerce has shifted from 'whether' to 'how'. In 2026, the primary point of friction for engineering teams is no longer the underlying API, but the reference architecture used to orchestrate it. For teams operating at scale, the choice usually narrows down to BigCommerce Catalyst and Shopify Hydrogen. Both frameworks have matured significantly, moving away from simple starter kits toward opinionated, enterprise-ready architectures.

We have found that the decision often hinges on your team's existing proficiency with specific React meta-frameworks and your requirement for complex data modelling. While Hydrogen is deeply integrated into the Shopify ecosystem via Remix, Catalyst represents BigCommerce's bet on the Next.js ecosystem. In our experience, neither is a default winner; the superior choice depends on how you intend to handle state, caching, and multi-storefront logic.

The Framework Foundations: Remix vs Next.js

Hydrogen is built on Remix. This architectural choice dictates a specific approach to data loading and mutations. Remix's focus on web standards and server-side execution means that Hydrogen applications typically see excellent performance in high-concurrency environments, such as flash sales. We have found that the loader and action patterns in Remix simplify the mental model for developers who prefer a clear separation between server-side data fetching and client-side rendering.

Catalyst, conversely, is built on the Next.js App Router. It leverages React Server Components (RSC) to minimize the JavaScript bundle sent to the browser. For teams already embedded in the Vercel ecosystem, Catalyst feels familiar. The use of Suspense boundaries and incremental static regeneration (ISR) allows for a highly granular caching strategy. In our experience, Catalyst often provides a faster path to a high Lighthouse score for content-heavy sites, whereas Hydrogen excels in dynamic, checkout-heavy workflows.

Developer Experience and the Rise of MCP

A significant trend we are observing is the integration of Model Context Protocol (MCP) servers into the development workflow. Shopify has recently introduced support for the Shopify.dev MCP server, which allows AI-assisted development tools to deeply understand the storefront schema and Polaris web components. We have found that this significantly reduces the time spent looking up GraphQL fragments or component props.

While BigCommerce Catalyst does not yet have an equivalent first-party MCP server, its reliance on standard Next.js patterns means it benefits from general-purpose AI coding assistants. However, for teams that value a tightly coupled development environment, Shopify's recent updates to the Dev Assistant and the inclusion of Shopify Functions support within these tools provide a more cohesive experience. If your team is looking to automate repetitive boilerplate, the Shopify MCP implementation currently offers a more specialised toolset for ecommerce-specific tasks.

Data Modelling and Metaobject Access

Historically, BigCommerce was the preferred choice for complex data requirements due to its flexible custom fields and native multi-storefront capabilities. However, Shopify has closed this gap with Metaobjects. Recent updates now allow for Metaobject access directly within Shopify Functions, enabling logic that was previously difficult to implement without a third-party middleware.

In Catalyst, data fetching is managed through a GraphQL client that is highly optimized for the BigCommerce Storefront API. We typically see teams using Catalyst when they need to aggregate data from multiple sources—such as an external PIM or a legacy ERP—directly within the Next.js layer. Because Catalyst is unopinionated about where it is hosted, you have more freedom to architect your middleware. Hydrogen is more opinionated, nudging developers toward Oxygen, Shopify's global hosting platform. While Oxygen is highly performant, it does impose certain constraints on the runtime environment that we have found some enterprise teams find restrictive.

Decision Framework: Catalyst vs Hydrogen

Use this checklist to determine which framework aligns with your current technical requirements.

Requirement	Hydrogen (Shopify)	Catalyst (BigCommerce)
Primary Framework	Remix (React)	Next.js App Router
Hosting Preference	Oxygen (Optimised)	Vercel / Netlify / AWS
Multi-Storefront	Via Shopify Markets	Native Multi-Storefront
AI Tooling	First-party MCP Support	Standard Next.js Patterns
B2B Complexity	Strong via B2B APIs	Deep native B2B features

Performance and Caching Strategies

Performance in a headless environment is largely a function of how you manage sub-requests. Hydrogen uses a sub-request caching mechanism that is built into the Remix fetch wrapper. This allows you to cache individual GraphQL queries at the edge. We have found that this is particularly effective for reducing the load on the Shopify API during peak traffic periods.

Catalyst leverages Next.js's native fetch cache and tag-based revalidation. This allows for more granular control over when specific parts of a page are updated. For example, you can revalidate product descriptions less frequently than inventory levels. In our experience, Catalyst's caching model is slightly more intuitive for teams that have previously built high-performance SaaS applications, whereas Hydrogen's model requires a deeper understanding of the Remix request-response lifecycle. For a deeper dive into these patterns, see our guide on headless commerce implementation.

Multi-Storefront and Internationalisation

BigCommerce Catalyst has a distinct advantage for merchants who need to run completely different storefronts (different domains, different catalogues, different currencies) from a single backend. BigCommerce's native Multi-Storefront (MSF) architecture is deeply baked into Catalyst. We typically see this as a deciding factor for large European merchants who need to manage distinct regional entities with separate P&L requirements.

Shopify Hydrogen handles internationalisation primarily through Shopify Markets. While this is highly effective for most merchants, it can sometimes feel like an abstraction layer on top of a single-store architecture. However, for teams that want a 'single source of truth' with minimal configuration, Hydrogen's tight integration with Markets makes it easier to deploy localized versions of a site quickly. We have found that Hydrogen is often the faster path to market for brands expanding from the US into the UK and EU, while Catalyst is better suited for complex, multi-brand conglomerates.

Extensibility: Functions and Middleware

The ability to inject custom logic into the commerce engine is critical. Shopify Functions have become the standard for this on the Shopify side. With the recent addition of functionHandle and enhanced discount support, the level of customisation available without a custom app is significant. We have found that Hydrogen developers can often offload complex logic to the Shopify backend, reducing the work the headless frontend needs to do.

Catalyst relies more on the BigCommerce 'Open SaaS' philosophy. This means you are more likely to implement custom logic in a Next.js API route or a separate microservice. This provides more flexibility but increases the maintenance burden on your engineering team. If you require highly non-standard checkout logic, BigCommerce's checkout extensibility is often cited as being more flexible than Shopify's, though Shopify's checkout extensions have largely closed this gap for the majority of use cases.

What to Do Next

Choosing between Catalyst and Hydrogen should not be a matter of platform loyalty, but of architectural fit. We suggest taking the following steps to validate your choice:

Audit your team's skills: If your developers are Next.js experts, Catalyst will feel more natural. If they prefer the web-standards approach of Remix, Hydrogen is the better fit.
Benchmark your data requirements: Map out your product attributes. If you have thousands of custom fields or complex B2B price lists, test how each framework handles the GraphQL payload size.
Prototype a core feature: Don't just look at the demo stores. Build a custom product configurator or a complex filtering system in both frameworks to see where the friction lies.
Evaluate your hosting: Decide if you want a managed environment like Oxygen or the flexibility of Vercel. This will often dictate which framework is more viable for your DevOps team.

If you are still undecided, we recommend starting with a technical discovery phase to map your specific requirements against the latest feature sets of both frameworks. In the rapidly evolving landscape of 2026, the 'best' framework is the one that your team can maintain and iterate on with the least resistance.

Going deeper into headless: Hydrogen 2.0 production-readiness, multi-storefront on BigCommerce, composable commerce reality check, and why most Shopify stores are slow. For platform-vs-platform reasoning, see our BigCommerce vs Shopify decision guide. Frontend builders should also factor in European Accessibility Act compliance (now in force across both stacks) and the search and filtering layer that actually converts.

Shopify Flow and AI Agent Triggers: Architecture and Patterns

no7software — Mon, 11 May 2026 18:26:14 +0000

Shopify Flow has traditionally been viewed as a closed-loop automation tool for internal store operations, such as tagging high-value customers or sending inventory alerts. However, the recent introduction of the Model Context Protocol (MCP) and the expansion of the Shopify Dev Assistant have fundamentally changed the utility of Flow within the engineering stack. We are seeing a shift where Flow is no longer just a recipient of platform events, but a critical execution layer for AI agents.

The challenge for technical teams is no longer just writing the automation logic, but designing the interface between unstructured AI intent and structured commerce execution. By leveraging shopify flow ai agent triggers, developers can provide LLMs with a safe, governed environment to perform complex operations without granting direct, unmitigated access to the Admin API. This architecture reduces the risk of non-deterministic AI behaviour causing havoc in the production environment.

The Architecture of Agentic Triggers

In our experience, the most robust way to connect an AI agent to Shopify Flow is through the flowTriggerReceive Admin GraphQL mutation. The agent's middleware calls the mutation with a custom trigger handle and a JSON payload, and Shopify Flow runs any workflow that begins with that trigger. The reverse direction is also supported: a Flow workflow can call back into your app through a custom action, and your handler verifies the request with authenticate.flow() before deciding what to do. Either direction acts as a functional bridge, where the AI determines 'what' needs to happen and Flow determines 'how' it happens within the Shopify ecosystem.

We have found that using Flow as a middleware layer provides several advantages over direct API calls from an agent. Firstly, it offers a visual audit trail that is accessible to non-technical stakeholders. Secondly, it allows for native integration with other Shopify apps without writing custom wrapper code for every integration point. When an agent triggers a Flow workflow, it can pass variables that the workflow then uses to look up metaobjects, update customer records, or adjust discount logic.

The recent support for Metaobject access in Shopify Functions further enhances this. An agent can now query store configuration stored in Metaobjects and use that context to decide which Flow trigger to invoke. This creates a feedback loop where the store's data informs the agent's logic, and the agent's logic drives the store's automation.

Implementing the Model Context Protocol (MCP)

The Model Context Protocol is becoming the standard for how AI agents interact with external data sources. For Shopify merchants, implementing an MCP server allows an AI assistant to 'see' the store's schema and available actions. We typically see engineering teams building thin MCP wrappers around their existing Shopify infrastructure to expose specific Flow triggers as 'tools' that the agent can call.

For a detailed breakdown of how these protocols interact, you may find our guide on agentic commerce protocols useful. By exposing a Flow trigger as an MCP tool, you provide the agent with a typed interface. The agent knows it needs to provide a customer_id and a reason_code, and Flow handles the heavy lifting of the actual database mutation. This separation of concerns is vital for maintaining a stable codebase as your AI implementation grows.

Leveraging Shopify Functions for Context

While Flow handles the asynchronous automation, Shopify Functions provide the synchronous logic required for complex commerce rules. We have observed that the most effective agentic implementations use a combination of both. For instance, a Function might determine the eligibility of a discount based on real-time cart data, while a Flow trigger—invoked by an agent—handles the post-purchase loyalty adjustments.

The introduction of functionHandle and binary testing for Shopify Functions has made it easier to deploy these complex logic gates. When an AI agent triggers a workflow, that workflow can interact with the results of these Functions. This is particularly relevant for merchants using Shopify Functions in production to manage bespoke pricing or shipping rules. The agent acts as the orchestrator, calling the right triggers at the right time based on the customer's conversational context.

Decision Framework: Direct API vs. Flow Agent Triggers

Use this framework to decide how your AI agent should interact with Shopify data.

Requirement	Direct Admin API Call	Shopify Flow Trigger
Latency	Low (Synchronous)	Medium (Asynchronous)
Complexity	High (Requires custom code)	Low (Low-code builder)
Observability	Logs only	Visual execution history
Security	Full Scopes required	Scoped to specific workflow
Best For	Real-time data retrieval	Multi-step operations

Security and Governance in Agentic Workflows

One of the primary concerns we hear from CTOs is the risk of an LLM 'hallucinating' an API call and deleting product data or issuing thousands of unauthorised refunds. Using Flow as the execution layer provides a natural sandbox. An agent cannot perform any action that you have not explicitly defined within a Flow workflow.

When setting up shopify flow ai agent triggers, we recommend the following security practices:

Payload Validation: Use Flow's internal logic to validate that the data sent by the agent falls within expected ranges (e.g., a discount percentage cannot exceed 20%).
Request Verification: External-to-Flow calls authenticate against your Admin GraphQL session, so guard the API token rather than building separate webhook HMAC checks. For the reverse direction (Flow calling a custom action your app exposes), use authenticate.flow() — it handles signature verification for you.
Rate Limiting: While Shopify manages Flow's scale, your own agentic middleware should implement rate limiting to prevent the LLM from triggering thousands of workflows in a loop.
Human-in-the-loop: For high-stakes actions, such as bulk price changes, the Flow workflow should include a 'Wait' step or send an approval request to a Slack channel before proceeding.

For more on maintaining a secure Shopify environment, see our guide on ecommerce security headers and general platform hardening.

The Role of Metaobjects as Agent Memory

A significant bottleneck in agentic commerce is state management. AI agents are typically stateless, meaning they don't 'remember' previous interactions unless that context is passed in the prompt. Shopify Metaobjects can serve as a persistent memory store for your agents. By using Flow to write to Metaobjects, an agent can record customer preferences, previous troubleshooting steps, or bespoke configuration data.

We have found that this approach is much more scalable than trying to manage state within the LLM's context window. Since Shopify recently added Metaobject access to Functions, these 'memories' can now influence the checkout experience in real-time. For example, an agent might trigger a Flow to update a 'Customer Style Profile' metaobject, which a Shopify Function then uses to reorder search results or apply specific upsell logic. This is a primary example of how advanced automation in Shopify Flow is moving toward a more dynamic, personalised model.

What to do next

To begin integrating AI agents with your Shopify Flow environment, we suggest taking the following technical steps:

Audit your manual processes: Identify workflows that currently require human intervention but follow a predictable logic. These are your primary candidates for agentic triggers.
Build a prototype MCP server: Use the Shopify Storefront or Admin API to create a bridge that exposes one or two specific Flow custom triggers — invoked from your agent via the flowTriggerReceive Admin GraphQL mutation — to your AI assistant.
Define your data contract: Clearly document the JSON schema required for each Flow trigger. This ensures that your agent provides the correct parameters every time.
Implement observability: Set up monitoring for your Flow execution logs to identify where the agent might be providing malformed data or triggering unnecessary workflows.

If you are exploring how to scale these patterns across multiple storefronts or complex enterprise environments, our team can provide an architectural review of your current automation strategy to ensure it is ready for the shift toward agentic commerce.

Companion code: the reference action handler that verifies a Flow request via authenticate.flow(), the Zod schema, and the decision matrix in plain Markdown live in our open-source engineering-notes repository at github.com/no7software/engineering-notes (Apache 2.0).