Add UCP business profile proxy on a generalized proxy interceptor by malewis5 · Pull Request #3976 · Shopify/hydrogen

malewis5 · 2026-08-27T22:28:00Z

WHY are these changes introduced?

Headless storefronts do not currently expose Shopify's managed UCP business profile on their public origin. Agents that begin discovery from a headless domain therefore cannot discover the authoritative UCP services and endpoints hosted on the store's myshopify.com domain.

WHAT is this pull request doing?

This adds GET /.well-known/ucp to handleShopifyRoutes, serving Shopify's managed UCP business profile from the headless storefront origin.

Rather than a bespoke fetch implementation, the UCP route is now built on the existing createProxyInterceptor, which was generalized to support the behavior UCP needs. This keeps a single proxy code path for all Shopify-owned routes.

UCP route behavior

Fetches the profile from the storefront client's myshopify.com origin with accept: application/json, no shopper cookies, and no authorization.
Rewrites the upstream path to /.well-known/ucp and does not forward the request query string.
Forwards only safe validation headers (content-type, etag, last-modified, vary) and drops Set-Cookie and internal upstream headers.
Applies Cache-Control: public, max-age=60, s-maxage=60, stale-while-revalidate=300, stale-if-error=86400 to successful profiles, and Cache-Control: no-store to every error and unpublished profile.
Rejects redirects (3xx) and non-JSON success responses with an uncached 502.
Maps a fetch timeout (5s) to 504 and other network failures to 502, both uncached.

Proxy interceptor generalization

createProxyInterceptor gained opt-in hooks so a single implementation can back UCP and the existing proxies:

forwardSearch to drop the query string from the upstream request.
requestHeaders.applyStorefrontHeaders to skip storefront request-header propagation.
responseHeaders.mode to switch between forwarding all upstream headers and an allowlist.
responseHeaders.inject to set computed response headers (used for the UCP cache policy).
responseHeaders.consumeStorefrontHeaders to skip request-context response-header consumption.
responseValidation to reject an upstream response with a from-scratch body; the factory centrally drains the upstream body so no validator can leak the connection.
mapError to set the error status and headers per phase, preserving the setup→500 / fetch→502 default split.

Documentation

Adds the UCP route and integration guidance to the hydrogen-request-handlers skill.

Developer impact

Includes a patch changeset for @shopify/hydrogen. This is an internal refactor plus a new Shopify-owned route; there is no new public API. Applications that already call handleShopifyRoutes before framework routing serve the discovery profile automatically, and no migration is required.

Risk

The route depends on the configured storefront domain serving a valid Shopify-managed UCP profile.
Successful profiles are cached publicly for 60 seconds with edge stale directives, so profile publication changes may not appear immediately.
Only the exact GET /.well-known/ucp route is intercepted. Other methods and paths continue to framework routing.
The generalized createProxyInterceptor now backs the existing proxies as well, so its new response-validation and error-mapping paths are shared code. Behavior for the existing proxies is unchanged because the new hooks are opt-in.

HOW to test your changes?

Configure a Hydrogen storefront for a Shopify store with a published UCP profile.
Start the storefront over HTTPS.
Run curl -i https://<storefront-origin>/.well-known/ucp.
Confirm the response is 200, uses Content-Type: application/json, and includes Cache-Control: public, max-age=60, s-maxage=60, stale-while-revalidate=300, stale-if-error=86400.
Confirm the profile's service and version URLs use the authoritative myshopify.com origin.
Confirm the response does not include shopper cookies.
Run curl -i -X POST https://<storefront-origin>/.well-known/ucp and confirm the request falls through to the application's normal routing.

Post-merge steps

None.

Checklist

I've read the Contributing Guidelines
I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've added a changeset because this PR contains a user-facing functional change
I've added tests to cover my changes
I've added or updated the documentation

mdamjanic7 · 2026-09-02T15:20:23Z

+    }
+    return null;
+  },
+  mapError: (error) => ({


mapError doesn't look at phase. So if setup fails, like a bad storeDomain making new URL throw, we return a 502 instead of the 500 default. I'd keep the factory's setup-500 / fetch-502 split here too.

mdamjanic7 · 2026-09-02T15:20:23Z

+      "cache-control": upstream.ok ? UCP_CACHE_CONTROL : UCP_NO_CACHE_CONTROL,
+    }),
+  },
+  responseValidation: (upstream) => {


Right now an upstream 404 streams the Online Store's 404 HTML page straight to the agent. They asked for JSON at this path and get Shopify's branded error page instead. Maybe we should return a clean JSON 404 of our own?

mdamjanic7 · 2026-09-02T15:20:23Z

+import { createProxyInterceptor } from "./proxy";
+
+const UCP_CACHE_CONTROL =
+  "public, max-age=60, s-maxage=60, stale-while-revalidate=300, stale-if-error=86400";


The profile contains the store's signing keys. With stale-if-error=86400, an edge can keep serving rotated-out keys for up to a day if the origin has a bad time. I'd shorten this to 300.

mdamjanic7 · 2026-09-02T15:20:23Z

+  forwardSearch: false,
+  rewritePathname: () => UCP_PROFILE_PATH,
+  requestHeaders: {
+    allow: [],


We forward etag and last-modified but strip if-none-match, so clients always download the whole file again on revalidation. I'd allow if-none-match and if-modified-since through and pass an upstream 304 along. The 3xx check would need to skip 304 for that to work.

mdamjanic7 · 2026-09-02T15:20:23Z

+
+export const handleUcpProxy = createProxyInterceptor({
+  match: UCP_RE,
+  methods: ["GET"],


Only GET is handled, so a HEAD request falls through to the app's 404. HEAD is supposed to work wherever GET does, and checkout.ts already accepts both.

Copilot

🟡 Changes recommended

The UCP error mapper incorrectly converts internal setup failures into upstream 502 responses.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds UCP business-profile discovery to Hydrogen’s Shopify route handling using a generalized proxy interceptor.

Changes:

Adds and registers GET /.well-known/ucp.
Extends proxy configuration for header filtering, validation, caching, and error mapping.
Adds tests, documentation, and a patch changeset.

File summaries

File	Description
`.changeset/ucp-business-profile-proxy.md`	Records the patch release.
`packages/hydrogen/skills/hydrogen-request-handlers/SKILL.md`	Documents UCP integration and validation.
`packages/hydrogen/src/core/request-routing/handle-shopify-routes.test.ts`	Tests route-level UCP behavior.
`packages/hydrogen/src/core/request-routing/handle-shopify-routes.ts`	Registers the UCP interceptor.
`packages/hydrogen/src/core/request-routing/interceptors/proxy.test.ts`	Tests generalized proxy behavior.
`packages/hydrogen/src/core/request-routing/interceptors/proxy.ts`	Adds configurable proxy hooks.
`packages/hydrogen/src/core/request-routing/interceptors/ucp.test.ts`	Tests UCP proxy behavior and failures.
`packages/hydrogen/src/core/request-routing/interceptors/ucp.ts`	Implements the UCP profile proxy.
`packages/hydrogen/src/core/url.ts`	Adds the exact UCP route matcher.

Review details

Files reviewed: 9/9 changed files
Comments generated: 1
Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+  mapError: (error) => ({
+    status: error instanceof DOMException && error.name === "TimeoutError" ? 504 : 502,
+    headers: { "cache-control": UCP_NO_CACHE_CONTROL },
+  }),


malewis5 requested a review from a team as a code owner August 27, 2026 22:28

github-actions Bot added the preview label Aug 27, 2026

Add UCP business profile proxy

fd2b5bb

malewis5 force-pushed the mttlws/ucp-business-profile-proxy branch from eeddd11 to fd2b5bb Compare August 27, 2026 22:29

use existing createProxyInterceptor instead of new ucp flavor

1413f6a

malewis5 changed the title ~~Add UCP business profile proxy~~ Add UCP business profile proxy on a generalized proxy interceptor Aug 27, 2026

mdamjanic7 reviewed Sep 2, 2026

View reviewed changes

mdamjanic7 requested a balanced review from Copilot September 2, 2026 15:21

Copilot started reviewing on behalf of mdamjanic7 September 2, 2026 15:21 View session

Copilot AI reviewed Sep 2, 2026

View reviewed changes

Comment thread packages/hydrogen/src/core/request-routing/interceptors/ucp.ts

Comment on lines +49 to +52

mapError: (error) => ({

status: error instanceof DOMException && error.name === "TimeoutError" ? 504 : 502,

headers: { "cache-control": UCP_NO_CACHE_CONTROL },

}),

Navigation Menu

Uh oh!

Add UCP business profile proxy on a generalized proxy interceptor - #3976

Add UCP business profile proxy on a generalized proxy interceptor#3976
malewis5 wants to merge 2 commits into
Shopify:previewfrom
malewis5:mttlws/ucp-business-profile-proxy

malewis5 commented Aug 27, 2026 •

edited

Loading

Uh oh!

mdamjanic7 Sep 2, 2026

Uh oh!

mdamjanic7 Sep 2, 2026

Uh oh!

mdamjanic7 Sep 2, 2026

Uh oh!

mdamjanic7 Sep 2, 2026

Uh oh!

mdamjanic7 Sep 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

malewis5 commented Aug 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

UCP route behavior

Proxy interceptor generalization

Documentation

Developer impact

Risk

HOW to test your changes?

Post-merge steps

Checklist

Uh oh!

mdamjanic7 Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mdamjanic7 Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mdamjanic7 Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mdamjanic7 Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

mdamjanic7 Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

malewis5 commented Aug 27, 2026 •

edited

Loading