Shopify UCP 2026-08-25: Migration Checks for Builders

Updated September 7, 2026: Shopify storefronts now advertise UCP 2026-08-25 at /.well-known/ucp. Shopify's September 4 announcement says the supported capability set is unchanged and existing integrations need no changes just for this rollout.[1]

That is not the same as saying an older client can adopt the new protocol version by changing one date. The upstream release changes payment-extension names, profile keys, and schemas. Its version rules can also exclude individual entries while leaving the rest of a negotiation usable.[2][3]

This update separates that builder work from the earlier Storefront MCP catalog and cart migrations. It replaces the expired deadline-led advice with what to check now.

The 90-Second Version

Shopify-managed storefront configuration: no change required just because Shopify added 2026-08-25 compatibility.[1]
Existing UCP integrations: the rollout is not a forced upgrade. The profiles we checked still advertise older version-specific profiles.[1][4][7]
Clients adopting 2026-08-25: update the relevant schemas and identifiers together, then verify the capabilities actually negotiated.[2][3]
Two easy-to-miss failures: an old payment-extension name may no longer match; a dev.ucp.* entry carrying the wrong version must be treated as absent by a conforming platform.[2][3]
Discovery is not proof of a working purchase flow: inspect the profile, but also test the operations your integration needs.[8]

September 2026: What Shopify Changed, and What It Did Not

Shopify added support for a protocol release, not every feature in that release. Its changelog explicitly says: "The set of capabilities that Shopify supports is unchanged."[1]

Our read-only checks on September 7, 2026, at 01:53 UTC found ucp.version: "2026-08-25" on Allbirds, Gymshark, and Rothy's.[4][5][6]

Each profile advertised these capability names: dev.ucp.shopping.checkout, dev.ucp.shopping.fulfillment, dev.ucp.shopping.discount, dev.ucp.shopping.cart, dev.ucp.shopping.order, dev.ucp.shopping.catalog.search, dev.ucp.shopping.catalog.lookup, and dev.shopify.catalog.[4][5][6]

That is a dated observation of advertised capabilities, not proof of every operation working or an adoption percentage across Shopify. In particular, do not infer support for upstream payment extensions merely from the top-level version.

Read the discovery profile, not a hardcoded version

This is an excerpt from the Allbirds discovery document, not a complete profile and not a get_product response:[4]

{
  "ucp": {
    "version": "2026-08-25",
    "supported_versions": {
      "2026-04-08": "https://weareallbirds.myshopify.com/.well-known/ucp/2026-04-08",
      "2026-01-23": "https://weareallbirds.myshopify.com/.well-known/ucp/2026-01-23"
    }
  }
}

json

The April leaf URL returned its own ucp.version: "2026-04-08" document without supported_versions.[7] That matches the protocol's leaf-profile rule: each leaf describes one release and must not contain another supported_versions map.[3]

Choose a version your client implements and negotiate against that version's profile. Do not combine capabilities from the April leaf with the August root in the same negotiation. The specification says platforms should not mix profiles that way.[3]

Two Ways a Feature Can Disappear Without a Whole-Request Failure

"Silent" here means an entry or extension can be excluded while other compatible capabilities remain. It does not mean UCP never returns errors. Unsupported protocol versions and operations with no compatible required capability have explicit error paths.[3][8]

1. Old payment-extension names no longer match

The upstream 2026-08-25 release moved payment extensions from dev.ucp.shopping.* to dev.ucp.common.payment.*, including split payments, payment terms, and AP2 mandates. This is a payment-extension migration, not a blanket rename of shopping capabilities such as cart and checkout.[2][10]

UCP capability intersection first matches names, then exact shared versions, and prunes extensions whose parents did not survive negotiation.[3] If one side still advertises an old payment-extension name and the other advertises the new one, that extension does not match. A compatible base capability can remain active without it.

For builders: update the affected identifiers, schema references, and expectations together. Test that the extension you require is present in the negotiated result, not merely that discovery returned JSON. A validator that accepts the document's shape is not proof that its names intersect with the other party's profile.

These are upstream client-migration rules. The three Shopify profiles above did not advertise those payment extensions, so this is not a claim that Shopify enabled them or that a named merchant's payment flow is failing.[4][5][6]

2. A mixed-version core entry must be rejected

For a profile declaring ucp.version = D, the specification requires every dev.ucp.* service, capability, and extension entry to declare version D.[3]

A platform encountering a mismatched core entry must reject that entry, treat it as absent, and never activate it. It may continue with the remaining entries.[3] Updating only the top-level version can therefore leave a profile that advertises the new release but loses a feature your client expected.

This rule is scoped to UCP-defined entries. It does not require blindly rewriting every vendor extension or payment-handler version; those authors control their own versions.[3]

There is a concrete detail worth watching in our September 7 snapshot: all three Shopify profiles paired an MCP dev.ucp.shopping service at 2026-08-25 with an embedded service entry at 2026-04-08, under an August root.[4][5][6] Under the rule above, a conforming platform would exclude that older service entry from that root profile.[3] We did not exercise embedded checkout or observe a shopper-facing failure. This is a dated profile observation, not an outage claim.

For builders: validate the versions of individual entries, record which ones are excluded, and assert the services and capabilities your flow requires. Test older releases separately through their advertised leaf profiles.

Signing Keys: a Field Change, Not a Merchant Alarm

The release removed signing_keys[] from the profile schema and made top-level keys[] the canonical signing-key field. This was removal, not merely a deprecation notice.[2]

The specification says profiles may include public verification keys; when they publish signing keys, those keys must be in top-level keys[].[3][9] A client adopting this release must read the correct field, but it should not treat the mere absence of keys as proof that every profile is defective.

At 01:53 UTC on September 7, none of the Allbirds, Gymshark, or Rothy's discovery documents we fetched contained keys or signing_keys, either at the root or under ucp.[4][5][6] That observation alone establishes neither a Shopify vulnerability nor a failed agent integration. Verification requirements depend on the operation and signing flow. If your flow requires signature verification, missing verification material is not permission to bypass it.[3]

Who Actually Has Work to Do?

Merchants relying on Shopify-managed profiles: this advertised-version update is not a request to hand-edit your storefront's discovery JSON. Shopify says existing storefront configuration and UCP integrations do not need changes just for the rollout.[1]

Agent and platform builders adopting the new release: review your profile generator, validator, schema bundle, capability matching, and response parser. Dashboards and analytics pipelines that hardcode version strings or extension identifiers need the same compatibility review. The release includes structural changes beyond these two negotiation traps, so consult its breaking-change list for the parts your client implements.[2]

Teams still calling the legacy Storefront MCP catalog or cart tools: that is a separate, older migration. Do not confuse continued support for an April UCP profile with continued support for /api/mcp.

The Catalog and Cart Legacy Windows Have Passed

Shopify announced the catalog migration on April 22, with old versions maintained until June 15, 2026.[12] Its June 24 cart announcement set August 31, 2026 as the maintenance cutoff for the deprecated Storefront MCP cart tools.[13]

Both dates are now in the past. These are Shopify's published support windows, not a claim that we tested every legacy endpoint and proved it has stopped responding.

For integrations still using the old tools, the documented destination is /api/ucp/mcp on the merchant domain. Catalog tools are search_catalog, lookup_catalog, and get_product; Cart MCP exposes create_cart, get_cart, update_cart, and cancel_cart.[14][15]

The shared names get_cart and update_cart can hide the migration: a familiar tool name at a new endpoint does not mean the request and response contracts stayed the same.

Keep the migration checks, not the expired countdown

Inventory direct legacy callers. Search custom agents, SDK wrappers, and server routes for /api/mcp. Inspect what each caller does instead of blindly replacing every string.
Move catalog and cart calls to the documented UCP endpoint and tool set. Re-check the current tool schemas for your negotiated profile.[14][15]
Include the agent profile metadata. Catalog and cart calls require a profile URL at params.arguments.meta["ucp-agent"].profile. Use a profile your agent actually implements, not a date copied from an unrelated example.[14][15]
Preserve cart state deliberately. update_cart uses PUT-style replacement, not a server-side merge. Send the complete desired line_items array and resend context and attribution if you need to preserve them.[15]
Make cancellation retry-safe. cancel_cart also requires meta["idempotency-key"] containing a UUID.[15]
Parse the right response layer. Cart data is returned in result.structuredContent; inspect business outcomes as well as JSON-RPC errors.[15]
Test distinct lifecycle paths. Exercise multi-turn updates and cancellation separately from the successful checkout handoff. For conversion with create_checkout, Shopify's guide requires both cart and checkout capabilities to be negotiated.[11][15]

Do this with your own test store and test agent. The read-only public discovery checks in this article do not exercise cart mutations, payment, or checkout.

Hydrogen and Weaverse: Verify the Deployed Forwarding Path

A Storefront API proxy or legacy MCP proxy is not proof that a custom domain serves UCP discovery and the UCP MCP endpoint.

In the Pilot source snapshot reviewed for this update, the app uses Hydrogen's request handler and locks Hydrogen to 2026.4.5.[16][18] The inspected dependency handles an exact /api/mcp match and forwards that request to Shopify's /api/mcp. That path is not a UCP schema adapter or evidence of forwarding /.well-known/ucp and /api/ucp/mcp.[19][20][21]

This corrects the earlier version of this article, which described Pilot's proxy as automatic UCP readiness. Check the actual version and forwarding configuration deployed for your store, then verify its public profile and authorized agent flows. A repository snapshot cannot prove what every customized or older merchant deployment serves.

What to Check Today

Fetch the actual storefront profile and record the observation time, ucp.version, services, capabilities, and supported-version leaf URLs.
Separate a missed legacy /api/mcp migration from an optional upgrade of an already-working UCP client. They are different jobs.
If adopting 2026-08-25, review the relevant upstream breaking changes. Update affected payment-extension names, schema references, and key-field readers together.[2]
Validate all dev.ucp.* entry versions against the selected profile version. Keep each older-version negotiation within its own leaf profile.[3]
Assert the capabilities required by your flow in the negotiated result. Make missing extensions and rejected entries visible in tests and diagnostics, even if another operation succeeds.
Re-test full-state cart updates, retry-safe cancellation, and checkout handoff on an authorized test store. Do not count an HTTP 200 discovery response as completion.

The takeaway: Shopify's rollout does not require merchants to rebuild their storefronts. For agent builders, the important contract is the selected profile plus its negotiated capabilities, not the newest date copied into a JSON file.