[andguy95]

TL;DR: Adds end-to-end cart attribute support to Hydrogen’s cart primitive, including mutations, optimistic state, scoped errors, examples, and packaged skill guidance.

Dependency: This PR depends on a new Shopify Standard Actions release with cart attribute support. That release must be available before this behavior works end to end.

Before

Hydrogen cart forms supported lines, discount codes, and notes, but did not provide a complete contract for updating cart attributes.

After

Cart forms can submit the complete attribute list:

<input {...register("attributeKey", {value: "gift-message"})} />
<textarea {...register("attributeValue", {defaultValue: message})} />
<button {...register("attributes-update")}>Save message</button>

What this changes

• Adds cartAttributesUpdate queries and server-handler support.
• Parses attribute updates from JSON and form submissions.
• Adds optimistic updates, rollback, pending state, and attribute-scoped errors.
• Includes attributes in the default cart data and Standard Actions types.
• Updates analytics handling while attribute mutations are pending.
• Updates packaged React and Vue cart skill guidance.
• Adds gift-message examples to the Hydrogen and React Router carts.

Developer impact

Adds the public Attribute and CartAttributeInput types, along with CartData.attributes, pending.attributes, errors.attributes, and the attributes-update form contract.

Attribute updates replace the complete attribute list. Consumers editing one attribute must resubmit unrelated attributes or they will be removed.

No changeset is included because this targets the preview release flow, which assigns the preview package version outside individual PRs. This would otherwise be an additive minor change.

UX impact

The Hydrogen and React Router examples now display a gift-message editor with an attribute-specific saving state.

Risk

• The corresponding Shopify Standard Actions release must land before this can be tested or used end to end.
• Incorrectly submitting only one attribute can remove other existing cart attributes.

How to Test

After the Standard Actions release is available:

1. Run pnpm install && pnpm build:pkgs.
2. Run pnpm dev:rr.
3. Open http://localhost:5173, add a product, and open the cart.
4. Enter and save a gift message.
5. Confirm the saving state appears and the message persists after reopening the cart and reloading /cart.

[frandiox]

Forgot to submit this yesterday 🤦

--

Also, @andguy95 you've probably created more storefronts than myself... any idea what's more common to modify cart attributes, forms or imperative fetches?

[frandiox]

Couple of minor things but I think this makes sense. Thank you!

(look at this comment above as well just in case #3897 (comment) )

[frandiox]

We don't use result.cart.attributes because the standard action is not supposed to return it, right? But Hydrogen's /api/cart does?

[andguy95]

Yep thats right. For the cart attributes we decided to follow the notes approach where we don't include it in the cart promise return payload

[andguy95]

@frandiox

Also, @andguy95 you've probably created more storefronts than myself... any idea what's more common to modify cart attributes, forms or imperative fetches?

I would say both! It falls into two categories:

1. Customer facing info -> this would be forms

• This one is for like gift messages, include gift bag, or delivery messags that require a form like experience

2. Hidden meta data added to cart -> user fetches

• This would be like stuffing customer attribution data into cart
• Session info
• Or just any data that needs to be added without customer input