[fredericoo]

TL;DR: Cart handlers can now associate newly created carts with the current Customer Account session, while Customer Account routes expose lifecycle hooks for application-owned synchronization of existing carts.

Before

Cart creation did not include Customer Account buyer identity, and the standard authorization, refresh, and logout routes offered no integration points for related session work.

After

const cartHandlers = createCartServerHandlers({customerSession});

const updateCartBuyerIdentity = async (context, customerAccessToken) => {
  const cartId = await getVerifiedCartId(context.sessionManager);
  if (!cartId) return;

  await context.storefrontClient.graphql(CART_BUYER_IDENTITY_UPDATE, {
    variables: {
      cartId,
      buyerIdentity: {customerAccessToken},
    },
  });
};

const attachCartBuyerIdentity = async (context, accessToken) => {
  await updateCartBuyerIdentity(context, accessToken);
};

const refreshCartBuyerIdentity = async (context, result) => {
  if (result.status === "transient") return;
  await updateCartBuyerIdentity(context, result.accessToken ?? null);
};

const customerAccountHandlers = createCustomerAccountServerHandlers({
  customerSession,
  onAuthenticated: attachCartBuyerIdentity,
  onTokenRefresh: refreshCartBuyerIdentity,
  onLogout: (context) => updateCartBuyerIdentity(context, null),
});

getVerifiedCartId must resolve a cart ID from protected server-side ownership state, not an unsigned client-controlled cookie or request value.

What this changes

• Adds the current usable customer token to new cart buyer identity.
• Marks checkout URLs in authenticated cart GET responses with logged_in=true.
• Adds Customer Account lifecycle hooks that run before session commit. Authentication receives the exact issued token; refresh receives a discriminated authenticated, transient, or unauthenticated result.
• Commits session state and returns a sanitized server error when a lifecycle hook rejects.
• Adds secure cart synchronization guidance based on protected server-side cart ownership.

Developer impact

Includes a minor changeset for @shopify/hydrogen. The new cart option, lifecycle hooks, handler types, and documentation are additive; existing handler configuration remains unchanged. Token-bearing hooks require the session returned by createCustomerSession; custom session implementations can continue using standard routes and onLogout.

Out of scope

• Hydrogen does not automatically associate existing carts during Customer Account lifecycle routes.
• Applications own cart-ID verification, synchronization mutations, and fail-safe logout cleanup.

Risk

• Customer-aware cart reads add one protected session lookup.
• Lifecycle hooks run on the authentication request path, so applications should bound downstream work and honour the request abort signal.
• Existing-cart synchronization must never trust an unsigned client-controlled cart ID.

[fredericoo]

note that we dont do it automatically as the use case is not for every customer.

in addition, we dont want to control how users store the cart id cookie and binding a non httpOnly cookie to a httpOnly session was flagged by security review from one of my subagents

this way we leave the responsibility to the implementer

this may be bad, because there is a lot more wiring up to do, im willing to discuss whether this is the most sane approach or an "auto sync" is a better idea

[graygilmore]

Not entirely sure how to 🎩 this one so I'm leaving the one critical thing that the bots found.

[frandiox]

Thanks for working on this! I like the direction but at the same time I feel we should make things a bit simpler for the most common path? 🤔

What if we provide something like this? (name tbd)

const cartBuyerIdentity = createCartBuyerIdentitySync({
  customerSession,
});

const cartHandlers = createCartServerHandlers({
  cartBuyerIdentity,
  // Or if we want to have top level hooks:
  // onCartCreated: cartBuyerIdentity.onCartCreated,
});

const customerAccountHandlers = createCustomerAccountServerHandlers({
  cartBuyerIdentity
  // Or with hooks:
  // ...cartBuyerIdentity.customerAccountHooks,
});

Hydrogen already writes the cart cookie and receives the trusted cart ID directly from the Storefront API when it creates the cart. The helper would save that same ID in protected session storage and commit it on the response. It would not trust a cart ID sent by the browser.

createCartBuyerIdentitySync would run cartBuyerIdentityUpdate after login and refresh, clear the identity on logout, and own cookie cleanup and request ordering. The helper is opt-in and tree-shakeable.

We could still consider keeping the the lifecycle hooks if we want to be extra flexible as a low-level API and this helper can use it. If not, the helper can keep that lifecycle wiring internal and expose only the cart-specific API.

[fredericoo]

Thanks for working on this! I like the direction but at the same time I feel we should make things a bit simpler for the most common path? 🤔

What if we provide something like this? (name tbd)

const cartBuyerIdentity = createCartBuyerIdentitySync({
  customerSession,
});

const cartHandlers = createCartServerHandlers({
  cartBuyerIdentity,
  // Or if we want to have top level hooks:
  // onCartCreated: cartBuyerIdentity.onCartCreated,
});

const customerAccountHandlers = createCustomerAccountServerHandlers({
  cartBuyerIdentity
  // Or with hooks:
  // ...cartBuyerIdentity.customerAccountHooks,
});

Hydrogen already writes the cart cookie and receives the trusted cart ID directly from the Storefront API when it creates the cart. The helper would save that same ID in protected session storage and commit it on the response. It would not trust a cart ID sent by the browser.

createCartBuyerIdentitySync would run cartBuyerIdentityUpdate after login and refresh, clear the identity on logout, and own cookie cleanup and request ordering. The helper is opt-in and tree-shakeable.

We could still consider keeping the the lifecycle hooks if we want to be extra flexible as a low-level API and this helper can use it. If not, the helper can keep that lifecycle wiring internal and expose only the cart-specific API.

my original idea was on the lines of createCustomerAccountServerHandlers({cartServerHandlers}) this way we call cartServerHandlers.updateBuyerIdentity automatically whenever the user is authorised or logs out

a security subagent flagged that this could mean we attach a non httpOnly cookie that can be fiddled with by the user, to an encrypted user session. to work around that i exposed the hooks that make it possible to do it yourself, but it's now down to the implementer to keep the cart cookie safe however they want

i would now suggest we do it like the initial idea (binding customer account with cart handlers like my code example) and consider either encrypting the cart cookie or just live with it, it's not really a security concern, the cart id cookie is already exposed and does nothing, attaching a modified cart id to your session means nothing at all to us

it felt much simpler to operate in the initial implementatioin than it does not (surely a lot less docs)

[frandiox]

This version is much simpler to use 🙌

[andguy95]

This looks good. I like we are inverting and passing the session in as needed.

Will possibly need this PR to update buyer and their local as well for country / currency switcher.