fix(checkout): forward ad-attribution URL params to checkout

[paul-phan]

Summary

Forward ad-attribution URL params (gclid, fbclid, utm_*, …) from the storefront onto the outbound Shopify checkout URL so Shopify's built-in tracking on the checkout subdomain sees consistent last-click identifiers.

The problem

Hydrogen storefronts live on one origin (mystore.com) and Shopify checkout lives on another (checkout.mystore.com or mystore.myshopify.com). When a buyer arrives via a paid ad and the landing URL carries identifiers like ?gclid=..., ?fbclid=..., or ?utm_source=..., those identifiers stay on the storefront's URL only — they do NOT automatically propagate to the checkout subdomain.

Shopify's built-in tracking running on the checkout origin (Customer Events, GA4, Meta Pixel) then sees the checkout-page URL with no attribution params, and reports every paid-ad order as organic / direct. Last-click attribution silently breaks for every paid order — the kind of bug that's invisible in acceptance tests and only surfaces weeks later when ad-platform reports stop matching reality.

Two cart → checkout transition points are affected:

1. Regular cart: "Continue to Checkout" <a href={cart.checkoutUrl}> link in app/components/cart/cart-summary.tsx.
2. Buy-now / cart-permalink flow: app/routes/cart/lines.tsx loader for /cart/<variantId>:<qty>?checkout URLs that cart.create() + redirect() straight to checkout.

Both currently hand off the raw cart.checkoutUrl with no attribution forwarding.

The fix

A small, self-contained helper:

// app/utils/checkout-attribution.ts
export function appendForwardedAttribution(
  checkoutUrl: string,
  searchString: string,
): string;

…wired into both transition points. The helper:

• Forwards gclid, gbraid, wbraid, fbclid, ttclid, msclkid, and the five utm_* params (deliberately scoped to widely-recognised standard params; affiliate / vendor-specific click IDs usually live in first-party cookies scoped to the apex domain and don't need this URL round-trip).
• First-write-wins — never overwrites params already on the checkout URL.
• Falls back to the original checkoutUrl unchanged on parse failure so a malformed input never breaks the checkout redirect.

lines.tsx (Buy-now)

Pure server-side — reads request.url's search and forwards before the redirect(). No client step.

cart-summary.tsx (Continue to Checkout link)

Reads window.location.search after hydration via useEffect and swaps the link's href to the enhanced URL. First render uses the raw checkoutUrl so SSR + client first-paint stay consistent (no hydration mismatch warning).

Verification

1. Visit https://yourstore.com/?utm_source=test&gclid=GCL_TEST_001.
2. Add an item to cart → "Continue to Checkout".
3. The outbound link now points to …?…&utm_source=test&gclid=GCL_TEST_001.
4. Shopify checkout's Customer Events / GA4 / Meta Pixel pick up the params.

For the Buy-now path, use a "Buy now" button on a PDP (any Pilot derivative that wires the showBuyNowButton schema option) and confirm the redirect destination carries the params.

What this does NOT do

• Doesn't add server-side conversion forwarders (Meta CAPI, GA4 Measurement Protocol, Google Ads Enhanced Conversions). Those need a separate cart-attribute-stash pattern to bridge the cookie-less webhook hop — that's a much bigger contribution. This PR fixes only the checkout-side tracking that Shopify gives you out of the box.
• Doesn't introduce any new cookie. Pure URL → URL pass-through.
• Doesn't require opt-in — every Pilot user with paid traffic benefits immediately.

Out of scope / future work

Storefronts capturing affiliate or vendor-specific click IDs (Traffic Junky tj_clickid, Awin awc, Impact Radius irclickid, etc.) usually round-trip them through a first-party attribution cookie scoped to the apex domain — a separate concern from this URL-only pass-through. Users can extend FORWARDED_ATTRIBUTION_KEYS in user-space if needed.

Files

• ➕ app/utils/checkout-attribution.ts (new, ~90 lines incl. JSDoc)
• ✏️ app/routes/cart/lines.tsx (+10 LOC)
• ✏️ app/components/cart/cart-summary.tsx (+20 LOC)

Net diff: ~124 insertions, 3 deletions. No new dependencies.