feat(hydrogen): resolve inbound ?variant=<id> deep links

Shopify's own surfaces — Liquid storefronts, Shopping feeds, email
campaigns, paid ads, and Shop Pay — deep-link to a product with a bare
variant id (`?variant=41565182099480`) rather than one param per option.
Hydrogen's product page only reads option params (`?Color=Red&Size=M`),
so those links silently resolve to the default variant instead of the one
the shopper clicked.

Add `getVariantIdParam` to normalize the param to a ProductVariant GID,
returning null for anything else — including GIDs for other resource
types, so an untrusted param can't reach a `node(id:)` lookup. Built on
the existing `parseGid`, matching how `shop-pay.ts` validates variant ids.

Wire it up in the Next.js example: resolve the variant, then 307 to the
canonical option-param URL, preserving `utm_*` and other campaign params.

This is additive. Option params stay canonical and stay the no-JS
mechanism (F4); no existing URL contract changes.

The redirect lives in `proxy.ts` rather than the page on purpose. Under
Cache Components the shell streams before a page-level `redirect()` can
set a status, so it degrades to a client-side redirect — measured at 53KB
with no add-to-cart, versus 80KB at the canonical URL. That would leave a
no-JS shopper following an ad link on an unusable page. Redirecting ahead
of framework routing keeps it a real HTTP redirect for everyone, and
skips the session-cookie decrypt on the redirect path.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: div-cowboy

.changeset/tidy-moons-repeat.md

@@ -0,0 +1,18 @@
+---
+'@shopify/hydrogen': minor
+---
+
+Add `getVariantIdParam` for inbound `?variant=<id>` deep links.
+
+Shopify's own surfaces — Liquid storefronts, Shopping feeds, email campaigns, paid ads, and Shop Pay links — deep-link to a product with a bare variant id (`/products/shoes?variant=41565182099480`) rather than one search param per option. A storefront that only reads option params (`?Color=Red&Size=M`) silently drops that selection and renders the default variant, so every link a merchant already has in market lands on the wrong variant after migrating to Hydrogen.
+
+`getVariantIdParam` reads that param and normalizes it to a `ProductVariant` GID, returning `null` for anything that isn't one — including GIDs for other resource types, so an untrusted param can't be forwarded into a `node(id:)` lookup for an unrelated object.
+
+```ts
+const variantId = getVariantIdParam({ searchParams });
+if (variantId) {
+  // Resolve the variant's selectedOptions, then redirect to the canonical URL.
+}
+```
+
+This is additive: option params remain the canonical, no-JS URL contract. The Next.js example shows the full pattern in `proxy.ts` — resolve the variant, then issue a real 307 to the equivalent option-param URL, preserving `utm_*` and other campaign params. Redirecting before framework routing matters: under Cache Components the shell streams before a page-level `redirect()` can set a status, so it degrades to a client-side redirect that never runs for a no-JS shopper.

examples/nextjs/lib/product-query.ts

@@ -113,5 +113,28 @@ export const RELATED_PRODUCTS_QUERY = gql(
   [PRODUCT_CARD_FRAGMENT],
 );
 
+/**
+ * Resolves an inbound `?variant=<id>` deep link (Liquid storefronts, Shopping
+ * feeds, email, ads, Shop Pay) to the option params the PDP is built around.
+ * Returns the owning product handle too, so a variant belonging to a different
+ * product in a combined listing redirects to the right page.
+ */
+export const VARIANT_DEEP_LINK_QUERY = gql(`
+  query VariantDeepLink($id: ID!, $country: CountryCode, $language: LanguageCode)
+  @inContext(country: $country, language: $language) {
+    node(id: $id) {
+      ... on ProductVariant {
+        product {
+          handle
+        }
+        selectedOptions {
+          name
+          value
+        }
+      }
+    }
+  }
+`);
+
 /** The typed product data consumed by the React product bindings. */
 export type ProductData = NonNullable<StorefrontApi.ResultOf<typeof PRODUCT_QUERY>["product"]>;

examples/nextjs/lib/variant-deep-link.ts

@@ -0,0 +1,68 @@
+import { getVariantIdParam, type StorefrontClient } from "@shopify/hydrogen";
+import { NextResponse, type NextRequest } from "next/server";
+
+import { VARIANT_DEEP_LINK_QUERY } from "./product-query";
+
+/** Matches `getVariantIdParam`'s param — kept here to strip it on the way out. */
+const VARIANT_PARAM = "variant";
+const PRODUCT_PATHNAME = /^\/products\/[^/]+$/;
+
+/** Shopify's sentinel option for single-variant products — not a real choice. */
+const DEFAULT_OPTION_NAME = "Title";
+const DEFAULT_OPTION_VALUE = "Default Title";
+
+/**
+ * Normalizes `?variant=<id>` deep links to the option-param URL the PDP reads.
+ *
+ * Shopify's own surfaces — Liquid storefronts, Shopping feeds, email campaigns,
+ * paid ads, and Shop Pay — link to a product with a bare variant id. The PDP is
+ * built around option params (`?Size=Large`), so without this those links land
+ * on the default variant instead of the one the shopper clicked.
+ *
+ * This runs in `proxy.ts` rather than the page on purpose. Under Cache
+ * Components the shell streams before a page-level `redirect()` can set a
+ * status, so it degrades to a client-side redirect — which never runs for a
+ * no-JS shopper, leaving them on a shell with no add-to-cart (F4). Redirecting
+ * before framework routing keeps it a real HTTP redirect for everyone.
+ *
+ * Costs nothing on ordinary requests: the Storefront lookup only happens on a
+ * `/products/*` URL that actually carries a well-formed `variant` param.
+ * Anything unresolvable falls through and renders the default variant (F8) —
+ * a stale id in an old feed should not 404.
+ */
+export async function variantDeepLinkRedirect(
+  request: NextRequest,
+  storefrontClient: StorefrontClient,
+): Promise<NextResponse | null> {
+  const { pathname, searchParams } = request.nextUrl;
+  if (!PRODUCT_PATHNAME.test(pathname)) return null;
+
+  const variantId = getVariantIdParam({ searchParams });
+  if (!variantId) return null;
+
+  const { data, errors } = await storefrontClient.graphql(VARIANT_DEEP_LINK_QUERY, {
+    variables: { id: variantId },
+  });
+
+  if (errors) {
+    console.error("[hydrogen] Variant deep link query failed", errors);
+  }
+
+  const node = data?.node;
+  if (!node || !("selectedOptions" in node)) return null;
+
+  // Clone so unrelated params (`utm_*`, `ref`) survive — a redirect must not
+  // cost the merchant their campaign attribution.
+  const url = request.nextUrl.clone();
+  // A combined listing can point at a variant on a different product.
+  url.pathname = `/products/${node.product.handle}`;
+  url.searchParams.delete(VARIANT_PARAM);
+  for (const option of node.selectedOptions) {
+    if (option.name === DEFAULT_OPTION_NAME && option.value === DEFAULT_OPTION_VALUE) continue;
+    url.searchParams.set(option.name, option.value);
+  }
+
+  // 307, not 308: option values are merchant-editable, so this mapping must not
+  // be cached in shoppers' browsers forever.
+  return NextResponse.redirect(url, 307);
+}

examples/nextjs/proxy.ts

@@ -12,6 +12,7 @@ import { createCustomerSessionManager } from "@/lib/customer-account";
 import { customerSessionHandlers } from "@/lib/customer-session-handlers";
 import { predictiveSearchHandlers } from "@/lib/predictive-search-handlers";
 import { MOCK_SHOP_DOMAIN, resolveStorefrontConfig } from "@/lib/storefront-config";
+import { variantDeepLinkRedirect } from "@/lib/variant-deep-link";
 
 /**
  * Next.js request lifecycle (`hydrogen-request-handlers` /
@@ -20,6 +21,13 @@ import { MOCK_SHOP_DOMAIN, resolveStorefrontConfig } from "@/lib/storefront-conf
  * `/api/{ver}/graphql.json`, `/admin`, …) short-circuit here. Storefront URL
  * redirects run in `app/not-found.tsx` (post-404), never here.
  *
+ * `?variant=<id>` deep links (Liquid storefronts, Shopping feeds, email, ads,
+ * Shop Pay) are normalized to the PDP's option-param URL here too — distinct
+ * from the admin-configured Storefront URL redirects above, and placed before
+ * framework routing so it stays a real HTTP redirect for no-JS shoppers (F4)
+ * rather than the client-side one a page-level `redirect()` degrades to under
+ * Cache Components.
+ *
  * The original request URL is forwarded to Server Components via
  * `requestContext.getForwardedRequestHeaders()` (carries `x-storefront-url` for
  * `not-found.tsx` and `getMarketFromHeaders`). SFAPI response headers are merged
@@ -37,8 +45,6 @@ export async function proxy(request: NextRequest) {
     buyerIp,
   });
 
-  const sessionManager = await createCustomerSessionManager(request);
-
   const { storeDomain, privateStorefrontToken } = resolveStorefrontConfig();
 
   const storefrontClient = createStorefrontClient({
@@ -51,6 +57,17 @@ export async function proxy(request: NextRequest) {
     },
   });
 
+  // Normalize `?variant=<id>` deep links to the PDP's option-param URL. Runs
+  // ahead of the session manager: a redirected request never reads the session,
+  // so there's no reason to pay its cookie decrypt first.
+  const variantRedirect = await variantDeepLinkRedirect(request, storefrontClient);
+  if (variantRedirect) {
+    requestContext.applyResponseHeaders(variantRedirect.headers);
+    return variantRedirect;
+  }
+
+  const sessionManager = await createCustomerSessionManager(request);
+
   // Customer Accounts are only available on a real store (mock.shop has no
   // Customer Account API). Inline the resolved `storeDomain` check rather than
   // calling `isCustomerAccountsAvailable()` to avoid a second config read.

packages/hydrogen/src/core/index.ts

@@ -178,7 +178,7 @@ export type {
   ValidProductSelectionResult,
   VariantSelectionResult,
 } from "./product";
-export { getSelectedProductOptions } from "./product";
+export { getSelectedProductOptions, getVariantIdParam } from "./product";
 export type {
   ProductInput,
   ProductAddToCartProps,

packages/hydrogen/src/core/product/index.ts

@@ -13,7 +13,7 @@ export type {
   ValidProductSelectionResult,
   VariantSelectionResult,
 } from "./product-form";
-export { getSelectedProductOptions } from "./options";
+export { getSelectedProductOptions, getVariantIdParam } from "./options";
 export { createProductFormRegister } from "./form";
 export type {
   ProductAddToCartProps,

packages/hydrogen/src/core/product/options.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { getSelectedProductOptions } from "./options";
+import { getSelectedProductOptions, getVariantIdParam } from "./options";
 
 describe("getSelectedProductOptions", () => {
   it("decodes special characters in option names and values", () => {
@@ -31,3 +31,48 @@ describe("getSelectedProductOptions", () => {
     expect(getSelectedProductOptions({ searchParams: params, allowedOptionNames: [] })).toEqual([]);
   });
 });
+
+describe("getVariantIdParam", () => {
+  const gid = "gid://shopify/ProductVariant/41565182099480";
+
+  it("normalizes the bare legacy id Liquid storefronts emit", () => {
+    const params = new URLSearchParams("variant=41565182099480");
+
+    expect(getVariantIdParam({ searchParams: params })).toBe(gid);
+  });
+
+  it("accepts a full Storefront API GID", () => {
+    const params = new URLSearchParams();
+    params.set("variant", gid);
+
+    expect(getVariantIdParam({ searchParams: params })).toBe(gid);
+  });
+
+  it("returns null when the param is absent or empty", () => {
+    expect(getVariantIdParam({ searchParams: new URLSearchParams() })).toBeNull();
+    expect(getVariantIdParam({ searchParams: new URLSearchParams("variant=") })).toBeNull();
+    expect(getVariantIdParam({ searchParams: new URLSearchParams("variant=%20") })).toBeNull();
+  });
+
+  it("rejects GIDs for other resource types so they can't reach node(id:)", () => {
+    const params = new URLSearchParams();
+    params.set("variant", "gid://shopify/Customer/1");
+
+    expect(getVariantIdParam({ searchParams: params })).toBeNull();
+  });
+
+  it("rejects non-numeric and decorated ids", () => {
+    for (const value of ["not-an-id", "41565182099480 OR 1=1", `${gid}?namespace=x`, "-1", "1.5"]) {
+      const params = new URLSearchParams();
+      params.set("variant", value);
+
+      expect(getVariantIdParam({ searchParams: params })).toBeNull();
+    }
+  });
+
+  it("uses the first value when the param repeats", () => {
+    const params = new URLSearchParams("variant=41565182099480&variant=99999999999999");
+
+    expect(getVariantIdParam({ searchParams: params })).toBe(gid);
+  });
+});

packages/hydrogen/src/core/product/options.ts

@@ -1,3 +1,4 @@
+import { parseGid } from "../utils/parse-gid";
 import type {
   ProductInput,
   ProductOptionValueFrom,
@@ -62,6 +63,52 @@ export function getSelectedProductOptions({
   return selectedOptions;
 }
 
+const VARIANT_ID_PARAM = "variant";
+const PRODUCT_VARIANT_GID_PREFIX = "gid://shopify/ProductVariant/";
+
+/**
+ * Reads an inbound `?variant=<id>` search param and normalizes it to a
+ * `ProductVariant` GID.
+ *
+ * Shopify's own surfaces — Liquid storefronts, Shopping feeds, email campaigns,
+ * paid ads, and Shop Pay links — deep-link to a product with a bare variant id
+ * (`/products/shoes?variant=41565182099480`) rather than one param per option.
+ * A storefront that only understands option params (`?Color=Red&Size=M`)
+ * silently drops that selection and renders the default variant, so every link
+ * a merchant already has in market lands on the wrong variant.
+ *
+ * Use this to detect such a link, resolve the variant, and redirect to your
+ * canonical option-param URL. Existing marketing links keep working without
+ * changing the URL contract the product page is built around.
+ *
+ * Returns `null` when the param is absent, empty, or is not a product variant
+ * id — including GIDs for other resource types, so an untrusted param can't be
+ * forwarded into a `node(id:)` lookup for an unrelated object.
+ *
+ * @example
+ * ```ts
+ * const variantId = getVariantIdParam({ searchParams });
+ * if (variantId) {
+ *   // Resolve the variant's selectedOptions, then redirect to the canonical URL.
+ * }
+ * ```
+ */
+export function getVariantIdParam({
+  searchParams,
+}: {
+  searchParams: URLSearchParams;
+}): string | null {
+  const raw = searchParams.get(VARIANT_ID_PARAM)?.trim();
+  if (!raw) return null;
+
+  // Accept both the bare legacy id Liquid emits and a full Storefront API GID.
+  const parsed = parseGid(raw);
+  if (parsed.resource && parsed.resource !== "ProductVariant") return null;
+
+  const bareId = parsed.id || raw;
+  return /^\d+$/.test(bareId) ? `${PRODUCT_VARIANT_GID_PREFIX}${bareId}` : null;
+}
+
 export function getAdjacentAndFirstSelectableVariants<TProduct extends ProductInput>(
   product: TProduct,
 ): ProductVariantFrom<TProduct>[] {