From 5f7db60cd105f1ed79e5e6075aa4d0fb507b5f78 Mon Sep 17 00:00:00 2001
From: Andrew Nguyen <andrew.nguyen@shopify.com>
Date: Fri, 31 Jul 2026 13:18:47 -0700
Subject: [PATCH 1/5] feat: initial cart attributes addition

---
 .../src/core/analytics/cart-tracker.test.ts   |  1 +
 .../src/core/analytics/cart-tracker.ts        |  2 +-
 .../hydrogen/src/core/cart/actions.test.ts    | 62 ++++++++++++++++++-
 packages/hydrogen/src/core/cart/actions.ts    | 50 ++++++++++++++-
 packages/hydrogen/src/core/cart/form.test.ts  | 18 ++++++
 packages/hydrogen/src/core/cart/form.ts       |  9 +++
 packages/hydrogen/src/core/cart/index.ts      |  7 ++-
 .../hydrogen/src/core/cart/queries.test.ts    |  8 +++
 .../src/core/cart/queries.type-test.ts        | 11 ++++
 packages/hydrogen/src/core/cart/route.test.ts | 28 ++++++++-
 .../hydrogen/src/core/cart/server-handlers.ts |  7 +++
 packages/hydrogen/src/core/cart/state.ts      |  9 ++-
 packages/hydrogen/src/core/index.ts           |  3 +-
 packages/hydrogen/src/react/cart-ssr.test.tsx |  1 +
 packages/hydrogen/src/react/cart.test.tsx     | 24 ++++++-
 packages/hydrogen/src/vue/cart.test.ts        |  2 +
 .../hydrogen/vendor/standard-actions.d.ts     | 10 ++-
 17 files changed, 238 insertions(+), 14 deletions(-)

diff --git a/packages/hydrogen/src/core/analytics/cart-tracker.test.ts b/packages/hydrogen/src/core/analytics/cart-tracker.test.ts
index 52d4e5013b..b31304b6a5 100644
--- a/packages/hydrogen/src/core/analytics/cart-tracker.test.ts
+++ b/packages/hydrogen/src/core/analytics/cart-tracker.test.ts
@@ -142,6 +142,7 @@ function createCartDataFromAnalyticsCart(cart: AnalyticsCart): CartData {
     totalQuantity: lines.reduce((total, line) => total + line.quantity, 0),
     updatedAt: cart.updatedAt,
     note: "",
+    attributes: [],
     discountCodes: [],
     cost: {
       subtotalAmount: {
diff --git a/packages/hydrogen/src/core/analytics/cart-tracker.ts b/packages/hydrogen/src/core/analytics/cart-tracker.ts
index 1b822fc2e5..7fb16667b5 100644
--- a/packages/hydrogen/src/core/analytics/cart-tracker.ts
+++ b/packages/hydrogen/src/core/analytics/cart-tracker.ts
@@ -183,7 +183,7 @@ function toAnalyticsCart(state: CartState): AnalyticsCart | null {
 
 function hasPendingCartWork({ pending, revalidating }: CartState): boolean {
   const hasPendingCost = pending.cost ?? (pending.lines.size > 0 || pending.discountCodes.size > 0);
-  return revalidating === true || hasPendingCost || pending.note;
+  return revalidating === true || hasPendingCost || pending.note || pending.attributes;
 }
 
 function getCartUpdatedAt(cart: CartData): string {
diff --git a/packages/hydrogen/src/core/cart/actions.test.ts b/packages/hydrogen/src/core/cart/actions.test.ts
index 0fea534d4c..f11bad0d08 100644
--- a/packages/hydrogen/src/core/cart/actions.test.ts
+++ b/packages/hydrogen/src/core/cart/actions.test.ts
@@ -149,7 +149,7 @@ describe("parseCartRequest", () => {
     });
   });
 
-  describe("JSON — discount and note payloads", () => {
+  describe("JSON — cart metadata payloads", () => {
     it("parses discountCodes array as discount-update", async () => {
       const { action } = await parseCartRequest(jsonRequest({ discountCodes: ["SAVE10", "BOGO"] }));
       expect(action).toEqual({
@@ -170,6 +170,27 @@ describe("parseCartRequest", () => {
       const { action } = await parseCartRequest(jsonRequest({ note: "" }));
       expect(action).toEqual({ intent: "note-update", note: "" });
     });
+
+    it("parses attributes as a full attributes-update", async () => {
+      const { action } = await parseCartRequest(
+        jsonRequest({ attributes: [{ key: "gift-message", value: "Happy birthday!" }] }),
+      );
+      expect(action).toEqual({
+        intent: "attributes-update",
+        attributes: [{ key: "gift-message", value: "Happy birthday!" }],
+      });
+    });
+
+    it("allows an empty attributes array to clear cart attributes", async () => {
+      const { action } = await parseCartRequest(jsonRequest({ attributes: [] }));
+      expect(action).toEqual({ intent: "attributes-update", attributes: [] });
+    });
+
+    it("rejects invalid attribute entries", async () => {
+      await expect(
+        parseCartRequest(jsonRequest({ attributes: [{ key: "gift-message", value: null }] })),
+      ).rejects.toThrow('Expected "attributes[0].value" to be a string.');
+    });
   });
 
   describe("JSON — cartId metadata", () => {
@@ -552,6 +573,45 @@ describe("parseCartRequest", () => {
     });
   });
 
+  describe("FormData — attributes intent", () => {
+    it("pairs repeated attribute keys and values", async () => {
+      const body = new URLSearchParams([
+        ["intent", "attributes-update"],
+        ["attributeKey", "gift-message"],
+        ["attributeValue", "Happy birthday!"],
+        ["attributeKey", "delivery-date"],
+        ["attributeValue", "Friday"],
+      ]);
+      const request = new Request("http://localhost/api/cart", {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body,
+      });
+
+      const { action } = await parseCartRequest(request);
+      expect(action).toEqual({
+        intent: "attributes-update",
+        attributes: [
+          { key: "gift-message", value: "Happy birthday!" },
+          { key: "delivery-date", value: "Friday" },
+        ],
+      });
+    });
+
+    it("allows no fields to clear all attributes", async () => {
+      const { action } = await parseCartRequest(formRequest({ intent: "attributes-update" }));
+      expect(action).toEqual({ intent: "attributes-update", attributes: [] });
+    });
+
+    it("rejects mismatched attribute fields", async () => {
+      await expect(
+        parseCartRequest(
+          formRequest({ intent: "attributes-update", attributeKey: "gift-message" }),
+        ),
+      ).rejects.toThrow(/one "attributeValue"/);
+    });
+  });
+
   describe("FormData — validation errors", () => {
     it("rejects missing lineId with increase intent", async () => {
       await expect(
diff --git a/packages/hydrogen/src/core/cart/actions.ts b/packages/hydrogen/src/core/cart/actions.ts
index 0efe4e7353..45aa13c391 100644
--- a/packages/hydrogen/src/core/cart/actions.ts
+++ b/packages/hydrogen/src/core/cart/actions.ts
@@ -14,6 +14,8 @@ export type CartLineUpdateInput = {
   sellingPlanId?: string;
 };
 
+export type CartAttributeInput = { key: string; value: string };
+
 export type CartAction =
   | { intent: "add"; lines: CartLineAddInput[] }
   | { intent: "update"; lines: CartLineUpdateInput[] }
@@ -21,6 +23,7 @@ export type CartAction =
   | { intent: "discount-update"; discountCodes: string[] }
   | { intent: "discount-apply"; code: string }
   | { intent: "discount-remove"; code: string }
+  | { intent: "attributes-update"; attributes: CartAttributeInput[] }
   | { intent: "note-update"; note: string };
 
 type ParsedCartRequest = {
@@ -74,8 +77,17 @@ function parseJsonBody(body: unknown): ParsedCartRequest {
     };
   }
 
+  if ("attributes" in body && Array.isArray(body.attributes)) {
+    return {
+      action: { intent: "attributes-update", attributes: parseAttributes(body.attributes) },
+      cartId,
+    };
+  }
+
   if (!("lines" in body) || !Array.isArray(body.lines)) {
-    throw new CartActionError('Request body must contain "lines", "discountCodes", or "note".');
+    throw new CartActionError(
+      'Request body must contain "lines", "discountCodes", "attributes", or "note".',
+    );
   }
 
   const lines = body.lines as unknown[];
@@ -171,7 +183,7 @@ function extractOptionalLineFields(
 //   Update qty:     server does the math — form sends current qty, server increments/decrements
 //   Remove line:    explicit intent field (can't express "quantity=0 means remove" implicitly)
 //   Discount bulk:  no FormData equivalent — forms handle one code at a time
-//   Attributes:     not supported in FormData (nested objects can't be expressed in flat fields)
+//   Cart attributes: parallel attributeKey/attributeValue fields preserve the ordered list
 //   Selling plan:   add only — no way to change selling plan on existing line via form
 //
 // Design decisions:
@@ -216,8 +228,12 @@ function parseFormData(form: FormData): CartAction {
     return parseNoteIntent(form);
   }
 
+  if (intent === "attributes-update") {
+    return parseAttributesIntent(form);
+  }
+
   throw new CartActionError(
-    `Unknown intent "${intent}". Expected one of: add, increase, decrease, remove, set, discount-apply, discount-remove, note-update.`,
+    `Unknown intent "${intent}". Expected one of: add, increase, decrease, remove, set, discount-apply, discount-remove, attributes-update, note-update.`,
   );
 }
 
@@ -283,6 +299,34 @@ function parseNoteIntent(form: FormData): CartAction {
   return { intent: "note-update", note: String(noteValue) };
 }
 
+function parseAttributesIntent(form: FormData): CartAction {
+  const keys = form.getAll("attributeKey");
+  const values = form.getAll("attributeValue");
+
+  if (keys.length !== values.length) {
+    throw new CartActionError(
+      'Intent "attributes-update" requires one "attributeValue" field for every "attributeKey" field.',
+    );
+  }
+
+  return {
+    intent: "attributes-update",
+    attributes: parseAttributes(keys.map((key, index) => ({ key, value: values[index] }))),
+  };
+}
+
+function parseAttributes(values: unknown[]): CartAttributeInput[] {
+  return values.map((value, index) => {
+    assertObject(value);
+    assertString(value.key, `attributes[${index}].key`);
+    assertString(value.value, `attributes[${index}].value`);
+    if (!value.key) {
+      throw new CartActionError(`Expected "attributes[${index}].key" not to be empty.`);
+    }
+    return { key: value.key, value: value.value };
+  });
+}
+
 // --- Assertion helpers ---
 
 function assertObject(value: unknown): asserts value is Record<string, unknown> {
diff --git a/packages/hydrogen/src/core/cart/form.test.ts b/packages/hydrogen/src/core/cart/form.test.ts
index 722b3d54e4..dc588347ca 100644
--- a/packages/hydrogen/src/core/cart/form.test.ts
+++ b/packages/hydrogen/src/core/cart/form.test.ts
@@ -60,6 +60,17 @@ describe("createCartFormRegister", () => {
       expect(result).toEqual({ name: "note", defaultValue: "gift wrap" });
     });
 
+    it("attribute fields return repeatable key and value names", () => {
+      expect(register("attributeKey", { value: "gift-message" })).toEqual({
+        name: "attributeKey",
+        value: "gift-message",
+      });
+      expect(register("attributeValue", { defaultValue: "Happy birthday!" })).toEqual({
+        name: "attributeValue",
+        defaultValue: "Happy birthday!",
+      });
+    });
+
     it("sellingPlanId returns name and value", () => {
       const result = register("sellingPlanId", {
         value: "gid://shopify/SellingPlan/1",
@@ -106,6 +117,13 @@ describe("createCartFormRegister", () => {
       });
     });
 
+    it("attributes-update returns intent", () => {
+      expect(register("attributes-update")).toEqual({
+        name: "intent",
+        value: "attributes-update",
+      });
+    });
+
     it("set returns hidden submit button attributes with data marker", () => {
       expect(register("set")).toEqual({
         name: "intent",
diff --git a/packages/hydrogen/src/core/cart/form.ts b/packages/hydrogen/src/core/cart/form.ts
index ee4aa5d6c6..38dd66a2e5 100644
--- a/packages/hydrogen/src/core/cart/form.ts
+++ b/packages/hydrogen/src/core/cart/form.ts
@@ -31,6 +31,12 @@ export type CartFormRegister = {
   (field: "merchandiseId", opts: { value: string }): { name: "merchandiseId"; value: string };
   (field: "note", opts: { value: string }): { name: "note"; value: string };
   (field: "note", opts: { defaultValue: string }): { name: "note"; defaultValue: string };
+  (field: "attributeKey", opts: { value: string }): { name: "attributeKey"; value: string };
+  (field: "attributeValue", opts: { value: string }): { name: "attributeValue"; value: string };
+  (
+    field: "attributeValue",
+    opts: { defaultValue: string },
+  ): { name: "attributeValue"; defaultValue: string };
   (field: "sellingPlanId", opts: { value: string }): { name: "sellingPlanId"; value: string };
   (action: "add"): { name: "intent"; value: "add" };
   (action: "increase"): { name: "intent"; value: "increase" };
@@ -40,6 +46,7 @@ export type CartFormRegister = {
   (action: "discount-apply"): { name: "intent"; value: "discount-apply" };
   (action: "discount-remove"): { name: "intent"; value: "discount-remove" };
   (action: "note-update"): { name: "intent"; value: "note-update" };
+  (action: "attributes-update"): { name: "intent"; value: "attributes-update" };
 };
 
 const FIELD_REGISTERS = new Set([
@@ -48,6 +55,8 @@ const FIELD_REGISTERS = new Set([
   "discountCode",
   "merchandiseId",
   "note",
+  "attributeKey",
+  "attributeValue",
   "sellingPlanId",
 ]);
 
diff --git a/packages/hydrogen/src/core/cart/index.ts b/packages/hydrogen/src/core/cart/index.ts
index bf93fd1600..c2f55e280b 100644
--- a/packages/hydrogen/src/core/cart/index.ts
+++ b/packages/hydrogen/src/core/cart/index.ts
@@ -9,7 +9,12 @@ export { createCartFormRegister } from "./form";
 export type { CartFormRegister, QuantityInputAttributes, SetButtonAttributes } from "./form";
 export { attachQuantityInput } from "./attach-quantity-input";
 export { parseCartRequest } from "./actions";
-export type { CartAction, CartLineAddInput, CartLineUpdateInput } from "./actions";
+export type {
+  CartAction,
+  CartAttributeInput,
+  CartLineAddInput,
+  CartLineUpdateInput,
+} from "./actions";
 export { cartQueries } from "./queries";
 export { createCartCookie } from "./cookie";
 export type {
diff --git a/packages/hydrogen/src/core/cart/queries.test.ts b/packages/hydrogen/src/core/cart/queries.test.ts
index abd873af8f..069a2b83c9 100644
--- a/packages/hydrogen/src/core/cart/queries.test.ts
+++ b/packages/hydrogen/src/core/cart/queries.test.ts
@@ -44,6 +44,14 @@ describe("cartQueries", () => {
     }
   });
 
+  it("includes cart attributes in the minimum payload and exposes their mutation", () => {
+    for (const query of Object.values(cartQueries)) {
+      expect(query).toContain("attributes");
+    }
+    expect(cartQueries.cartAttributesUpdate).toContain("cartAttributesUpdate");
+    expect(cartQueries.cartAttributesUpdate).toContain("$attributes: [AttributeInput!]!");
+  });
+
   it("adds custom cart fields to every cart document without removing the minimum payload", () => {
     const customQueries = makeCartQueries({ fragment: customCartFragment });
 
diff --git a/packages/hydrogen/src/core/cart/queries.type-test.ts b/packages/hydrogen/src/core/cart/queries.type-test.ts
index f84323abef..51e3f14e6f 100644
--- a/packages/hydrogen/src/core/cart/queries.type-test.ts
+++ b/packages/hydrogen/src/core/cart/queries.type-test.ts
@@ -118,6 +118,11 @@ describe("cart query result types", () => {
     type R = ResultOf<typeof cartQueries.cartNoteUpdate>;
     expectTypeOf<R>().toHaveProperty("cartNoteUpdate");
   });
+
+  it("cartAttributesUpdate returns cartAttributesUpdate", () => {
+    type R = ResultOf<typeof cartQueries.cartAttributesUpdate>;
+    expectTypeOf<R>().toHaveProperty("cartAttributesUpdate");
+  });
 });
 
 describe("cart query variable types", () => {
@@ -163,6 +168,12 @@ describe("cart query variable types", () => {
     expectTypeOf<V>().toHaveProperty("cartId");
     expectTypeOf<V>().toHaveProperty("note");
   });
+
+  it("cartAttributesUpdate requires cartId and attributes", () => {
+    type V = VariablesOf<typeof cartQueries.cartAttributesUpdate>;
+    expectTypeOf<V>().toHaveProperty("cartId");
+    expectTypeOf<V>().toHaveProperty("attributes");
+  });
 });
 
 describe("storefront client result type inference", () => {
diff --git a/packages/hydrogen/src/core/cart/route.test.ts b/packages/hydrogen/src/core/cart/route.test.ts
index a2252dff5b..3ec342ec7b 100644
--- a/packages/hydrogen/src/core/cart/route.test.ts
+++ b/packages/hydrogen/src/core/cart/route.test.ts
@@ -207,7 +207,7 @@ describe("createCartServerHandlers", () => {
       if (result.type !== "error") throw new Error("expected error result");
       expect(result.error).toEqual({
         code: "invalid_cart_request",
-        message: 'Request body must contain "lines", "discountCodes", or "note".',
+        message: 'Request body must contain "lines", "discountCodes", "attributes", or "note".',
       });
       expect("status" in result).toBe(false);
     });
@@ -645,6 +645,30 @@ describe("createCartServerHandlers", () => {
     });
   });
 
+  describe("POST — JSON attributes", () => {
+    it("calls cartAttributesUpdate for attributes-update", async () => {
+      mockFetch.mockResolvedValueOnce(
+        mockGqlResponse({ cartAttributesUpdate: { cart: MOCK_CART, userErrors: [] } }),
+      );
+
+      const result = await handleCartRequest(
+        createJsonPostRequest(
+          { attributes: [{ key: "gift-message", value: "Happy birthday!" }] },
+          "cart=123",
+        ),
+        defaultConfig,
+      );
+
+      assert(result, "expected a response");
+      const body = await result.json();
+      expect(body.userErrors).toEqual([]);
+      const [, init] = mockFetch.mock.calls[0];
+      expect(JSON.parse(init.body).variables.attributes).toEqual([
+        { key: "gift-message", value: "Happy birthday!" },
+      ]);
+    });
+  });
+
   describe("POST — JSON error handling", () => {
     it("returns 400 for invalid request body", async () => {
       const result = await handleCartRequest(createJsonPostRequest({}), defaultConfig);
@@ -653,7 +677,7 @@ describe("createCartServerHandlers", () => {
       const body = await result.json();
       expect(body.error).toEqual({
         code: "invalid_cart_request",
-        message: 'Request body must contain "lines", "discountCodes", or "note".',
+        message: 'Request body must contain "lines", "discountCodes", "attributes", or "note".',
       });
     });
 
diff --git a/packages/hydrogen/src/core/cart/server-handlers.ts b/packages/hydrogen/src/core/cart/server-handlers.ts
index 5a23667e98..488a1015fa 100644
--- a/packages/hydrogen/src/core/cart/server-handlers.ts
+++ b/packages/hydrogen/src/core/cart/server-handlers.ts
@@ -303,6 +303,13 @@ async function executeMutation(
       const { cart, userErrors, warnings } = assertMutationData(result, "cartNoteUpdate");
       return createMutationResult(cart, userErrors, warnings, result.headers);
     }
+    case "attributes-update": {
+      const result = await storefront.graphql(queries.cartAttributesUpdate, {
+        variables: { cartId, attributes: action.attributes },
+      });
+      const { cart, userErrors, warnings } = assertMutationData(result, "cartAttributesUpdate");
+      return createMutationResult(cart, userErrors, warnings, result.headers);
+    }
     default: {
       const _exhaustive: never = action;
       throw new Error(`Unhandled cart action intent: ${(_exhaustive as CartAction).intent}`);
diff --git a/packages/hydrogen/src/core/cart/state.ts b/packages/hydrogen/src/core/cart/state.ts
index 675d0c3dea..3138b600a2 100644
--- a/packages/hydrogen/src/core/cart/state.ts
+++ b/packages/hydrogen/src/core/cart/state.ts
@@ -89,6 +89,7 @@ export interface Attribute {
 export interface CartPending {
   lines: Set<string>;
   note: boolean;
+  attributes: boolean;
   discountCodes: Set<string>;
   cost?: boolean;
 }
@@ -97,12 +98,14 @@ export interface CartErrorState {
   cart: CartErrorGroup;
   lines: Map<string, CartErrorGroup>;
   note: CartErrorGroup;
+  attributes: Map<string, CartErrorGroup>;
   discountCodes: Map<string, CartErrorGroup>;
   network: CartNetworkEntry[];
   lastUpdatedAt: number;
   cartUpdatedAt: number;
   linesUpdatedAt: number;
   noteUpdatedAt: number;
+  attributesUpdatedAt: number;
   discountCodesUpdatedAt: number;
   networkUpdatedAt: number;
 }
@@ -113,6 +116,7 @@ export interface CartData {
   totalQuantity: number;
   cost: CartCost;
   note?: string | null;
+  attributes: Attribute[];
   lines: CartLineConnection;
   discountCodes: DiscountCode[];
   [key: string]: unknown;
@@ -129,7 +133,7 @@ export interface CartState<TData extends CartData = CartData> {
 }
 
 export function createEmptyPending(): CartPending {
-  return { lines: new Set(), note: false, discountCodes: new Set(), cost: false };
+  return { lines: new Set(), note: false, attributes: false, discountCodes: new Set(), cost: false };
 }
 
 export function createEmptyErrorGroup(): CartErrorGroup {
@@ -141,12 +145,14 @@ export function createEmptyCartErrors(): CartErrorState {
     cart: createEmptyErrorGroup(),
     lines: new Map(),
     note: createEmptyErrorGroup(),
+    attributes: new Map(),
     discountCodes: new Map(),
     network: [],
     lastUpdatedAt: 0,
     cartUpdatedAt: 0,
     linesUpdatedAt: 0,
     noteUpdatedAt: 0,
+    attributesUpdatedAt: 0,
     discountCodesUpdatedAt: 0,
     networkUpdatedAt: 0,
   };
@@ -162,6 +168,7 @@ export const EMPTY_CART_DATA: CartData = Object.freeze({
     checkoutChargeAmount: Object.freeze({ amount: "0", currencyCode: "" }),
   }),
   note: "",
+  attributes: [] as Attribute[],
   lines: Object.freeze({ nodes: [] as CartLine[] }),
   discountCodes: [] as DiscountCode[],
 });
diff --git a/packages/hydrogen/src/core/index.ts b/packages/hydrogen/src/core/index.ts
index 081bc771d8..c9b9b5d5cc 100644
--- a/packages/hydrogen/src/core/index.ts
+++ b/packages/hydrogen/src/core/index.ts
@@ -82,7 +82,7 @@ export { createCartFormRegister } from "./cart";
 export type { CartFormRegister, QuantityInputAttributes, SetButtonAttributes } from "./cart";
 export { attachQuantityInput } from "./cart";
 export { parseCartRequest } from "./cart";
-export type { CartAction, CartLineAddInput, CartLineUpdateInput } from "./cart";
+export type { CartAction, CartAttributeInput, CartLineAddInput, CartLineUpdateInput } from "./cart";
 export { cartQueries, createCartCookie } from "./cart";
 export { getCartId, getCart, createCartServerHandlers } from "./cart";
 export type {
@@ -113,6 +113,7 @@ export type {
   CartLineMerchandise,
   CartCost,
   DiscountCode,
+  Attribute,
 } from "./cart";
 export {
   EMPTY_CART_DATA,
diff --git a/packages/hydrogen/src/react/cart-ssr.test.tsx b/packages/hydrogen/src/react/cart-ssr.test.tsx
index bfd9c7fb6c..3d446871bf 100644
--- a/packages/hydrogen/src/react/cart-ssr.test.tsx
+++ b/packages/hydrogen/src/react/cart-ssr.test.tsx
@@ -41,6 +41,7 @@ const MOCK_CART: CartData = {
     checkoutChargeAmount: { amount: "30.00", currencyCode: "USD" },
   },
   note: "",
+  attributes: [],
   lines: {
     nodes: [
       {
diff --git a/packages/hydrogen/src/react/cart.test.tsx b/packages/hydrogen/src/react/cart.test.tsx
index c8fcc61045..edf60999be 100644
--- a/packages/hydrogen/src/react/cart.test.tsx
+++ b/packages/hydrogen/src/react/cart.test.tsx
@@ -642,7 +642,13 @@ describe("useCart pending state", () => {
     const mockStore = createMockStore();
     mockStore.setState(
       makeCartState({
-        pending: { lines: new Set(["line-1"]), note: false, discountCodes: new Set(), cost: true },
+        pending: {
+          lines: new Set(["line-1"]),
+          note: false,
+          attributes: false,
+          discountCodes: new Set(),
+          cost: true,
+        },
       }),
     );
     vi.mocked(createCartStore).mockImplementation(() => mockStore);
@@ -664,7 +670,13 @@ describe("useCart pending state", () => {
     const mockStore = createMockStore();
     mockStore.setState(
       makeCartState({
-        pending: { lines: new Set(), note: true, discountCodes: new Set(), cost: false },
+        pending: {
+          lines: new Set(),
+          note: true,
+          attributes: false,
+          discountCodes: new Set(),
+          cost: false,
+        },
       }),
     );
     vi.mocked(createCartStore).mockImplementation(() => mockStore);
@@ -682,7 +694,13 @@ describe("useCart pending state", () => {
     const mockStore = createMockStore();
     mockStore.setState(
       makeCartState({
-        pending: { lines: new Set(), note: false, discountCodes: new Set(["SAVE10"]), cost: true },
+        pending: {
+          lines: new Set(),
+          note: false,
+          attributes: false,
+          discountCodes: new Set(["SAVE10"]),
+          cost: true,
+        },
       }),
     );
     vi.mocked(createCartStore).mockImplementation(() => mockStore);
diff --git a/packages/hydrogen/src/vue/cart.test.ts b/packages/hydrogen/src/vue/cart.test.ts
index 6b3a852108..aa7a8af5a2 100644
--- a/packages/hydrogen/src/vue/cart.test.ts
+++ b/packages/hydrogen/src/vue/cart.test.ts
@@ -522,6 +522,7 @@ describe("useCartForm", () => {
           pending: {
             lines: new Set(["line-1"]),
             note: false,
+            attributes: false,
             discountCodes: new Set(),
             cost: true,
           },
@@ -553,6 +554,7 @@ describe("useCartForm", () => {
           pending: {
             lines: new Set(["line-1"]),
             note: false,
+            attributes: false,
             discountCodes: new Set(),
             cost: true,
           },
diff --git a/packages/hydrogen/vendor/standard-actions.d.ts b/packages/hydrogen/vendor/standard-actions.d.ts
index b090cd23a1..59d7a74727 100644
--- a/packages/hydrogen/vendor/standard-actions.d.ts
+++ b/packages/hydrogen/vendor/standard-actions.d.ts
@@ -75,12 +75,16 @@ export interface StorefrontCartSummary {
 	cost: CartCost;
 	lines: StorefrontCartLinesConnection;
 	discountCodes: CartDiscountCode[];
+	attributes?: Array<{
+		key: string;
+		value: string;
+	}>;
 }
 export type UpdateCartEventTargetMeta = {
 	type: "shopify:cart:lines-update";
 	action: CartUpdateAction;
 } | {
-	type: "shopify:cart:note-update" | "shopify:cart:discount-update" | "shopify:cart:error";
+	type: "shopify:cart:note-update" | "shopify:cart:attributes-update" | "shopify:cart:discount-update" | "shopify:cart:error";
 };
 export interface EventTargetConfigurationMeta {
 	/**
@@ -115,6 +119,10 @@ export interface UpdateCartPayload {
 	lines?: CartLineInput[];
 	note?: string;
 	discountCodes?: string[];
+	attributes?: Array<{
+		key: string;
+		value: string;
+	}>;
 }
 export interface UpdateCartResult {
 	cart: StorefrontCartSummary;

From 006f155fd29dba09d227959d3a8da58cd0077314 Mon Sep 17 00:00:00 2001
From: Andrew Nguyen <andrew.nguyen@shopify.com>
Date: Fri, 31 Jul 2026 13:49:34 -0700
Subject: [PATCH 2/5] feat: update skills and examples

---
 .../hydrogen/app/components/CartSummary.tsx   | 40 +++++++++++++-
 examples/hydrogen/app/lib/analytics.tsx       |  2 +-
 examples/hydrogen/app/styles/app.css          | 14 ++++-
 .../skills/hydrogen-cart-drawer/SKILL.md      |  4 +-
 .../hydrogen/skills/hydrogen-cart-ui/SKILL.md | 54 +++++++++++++------
 .../hydrogen-cart-ui/references/react.md      | 33 +++++++++++-
 .../skills/hydrogen-cart-ui/references/vue.md |  3 ++
 .../skills/hydrogen-smoke-test/SKILL.md       |  6 ++-
 templates/nextjs/lib/content.ts               |  6 +++
 9 files changed, 137 insertions(+), 25 deletions(-)

diff --git a/examples/hydrogen/app/components/CartSummary.tsx b/examples/hydrogen/app/components/CartSummary.tsx
index ca9cef24e7..0c5440a300 100644
--- a/examples/hydrogen/app/components/CartSummary.tsx
+++ b/examples/hydrogen/app/components/CartSummary.tsx
@@ -2,7 +2,7 @@ import type { CartData, MoneyV2 } from "@shopify/hydrogen";
 import { useId } from "react";
 
 import type { CartLayout } from "~/components/CartMain";
-import { useCartForm } from "~/lib/cart";
+import { useCart, useCartForm } from "~/lib/cart";
 import { formatMoney } from "~/lib/money";
 
 type CartSummaryProps = {
@@ -32,11 +32,49 @@ export function CartSummary({ cart, layout, totalsPending }: CartSummaryProps) {
         discountsHeadingId={discountsHeadingId}
         discountCodeInputId={discountCodeInputId}
       />
+      <CartGiftMessage attributes={cart.attributes} />
       <CartCheckoutActions checkoutUrl={cart.checkoutUrl} />
     </div>
   );
 }
 
+const GIFT_MESSAGE_ATTRIBUTE = "gift-message";
+
+function CartGiftMessage({ attributes }: { attributes: CartData["attributes"] }) {
+  const { formProps, register } = useCartForm();
+  const attributesPending = useCart((state) => state.pending.attributes);
+  const giftMessageId = useId();
+  const giftMessage = attributes.find(({ key }) => key === GIFT_MESSAGE_ATTRIBUTE)?.value ?? "";
+  const preservedAttributes = attributes.filter(({ key }) => key !== GIFT_MESSAGE_ATTRIBUTE);
+
+  return (
+    <form {...formProps()} className="cart-attribute">
+      {preservedAttributes.map(({ key, value }) => (
+        <div key={key}>
+          <input type="hidden" {...register("attributeKey", { value: key })} />
+          <input type="hidden" {...register("attributeValue", { value: value ?? "" })} />
+        </div>
+      ))}
+      <input type="hidden" {...register("attributeKey", { value: GIFT_MESSAGE_ATTRIBUTE })} />
+      <label htmlFor={giftMessageId}>Gift message</label>
+      <textarea
+        id={giftMessageId}
+        rows={3}
+        {...register("attributeValue", { defaultValue: giftMessage })}
+        placeholder="Add a message for the recipient"
+      />
+      <button
+        type="submit"
+        {...register("attributes-update")}
+        disabled={attributesPending}
+        aria-busy={attributesPending}
+      >
+        {attributesPending ? "Saving…" : "Save message"}
+      </button>
+    </form>
+  );
+}
+
 function toHydrogenMoney(value: CartData["cost"]["subtotalAmount"]): MoneyV2 | null {
   if (!value.amount || !value.currencyCode) return null;
   return { amount: value.amount, currencyCode: value.currencyCode };
diff --git a/examples/hydrogen/app/lib/analytics.tsx b/examples/hydrogen/app/lib/analytics.tsx
index 762fc9c1f0..36e8fd4e09 100644
--- a/examples/hydrogen/app/lib/analytics.tsx
+++ b/examples/hydrogen/app/lib/analytics.tsx
@@ -199,5 +199,5 @@ function hasPendingCartWork(cart: AnalyticsCartInput) {
   if (!cart.pending) return false;
   const hasPendingCost =
     cart.pending.cost ?? (cart.pending.lines.size > 0 || cart.pending.discountCodes.size > 0);
-  return hasPendingCost || cart.pending.note;
+  return hasPendingCost || cart.pending.note || cart.pending.attributes;
 }
diff --git a/examples/hydrogen/app/styles/app.css b/examples/hydrogen/app/styles/app.css
index 3be08d316a..6b5e5591b4 100644
--- a/examples/hydrogen/app/styles/app.css
+++ b/examples/hydrogen/app/styles/app.css
@@ -1,7 +1,7 @@
 :root {
   --aside-width: 400px;
-  --cart-aside-summary-height-with-discount: 300px;
-  --cart-aside-summary-height: 250px;
+  --cart-aside-summary-height-with-discount: 450px;
+  --cart-aside-summary-height: 400px;
   --grid-item-width: 355px;
   --header-height: 64px;
   --color-dark: #000;
@@ -354,6 +354,16 @@ button.reset:hover:not(:has(> *)) {
   margin-top: 0.25rem;
 }
 
+.cart-attribute {
+  display: grid;
+  gap: 0.5rem;
+  margin-top: 1rem;
+}
+
+.cart-attribute textarea {
+  resize: vertical;
+}
+
 .cart-subtotal {
   align-items: center;
   display: flex;
diff --git a/packages/hydrogen/skills/hydrogen-cart-drawer/SKILL.md b/packages/hydrogen/skills/hydrogen-cart-drawer/SKILL.md
index 0f1dfd2d41..02992eaab1 100644
--- a/packages/hydrogen/skills/hydrogen-cart-drawer/SKILL.md
+++ b/packages/hydrogen/skills/hydrogen-cart-drawer/SKILL.md
@@ -28,13 +28,13 @@ The drawer has three layout zones (header / body / footer):
 
 1. **Header** — title, close button, and error banner (if any cart errors exist). Always visible, never scrolls.
 2. **Body** — line items only. This is the only zone that scrolls when content overflows.
-3. **Footer** — discount codes, order note, totals, and checkout button. Always visible (pinned to bottom), never scrolls.
+3. **Footer** — discount codes, order note and/or cart attribute editors, totals, and checkout button. Always visible (pinned to bottom), never scrolls.
 
 **Empty state**: When the cart has no items, the body shows an empty message ("Your cart is empty") and the footer is hidden entirely — no totals, no discounts, no notes, no checkout button.
 
 The drawer is a `<dialog>` (or primitive library equivalent) rendered once in the root layout. The storefront must also have a `/cart` route that renders a full cart page — this is the fallback route when the drawer is unavailable. The drawer is the progressively-enhanced experience that layers on top after hydration.
 
-The full `/cart` page shares the same content components (line items, discounts, note, totals, checkout) but uses a page layout instead of the fixed header/body/footer zones.
+The full `/cart` page shares the same content components (line items, discounts, note, attributes, totals, checkout) but uses a page layout instead of the fixed header/body/footer zones.
 
 The drawer's line item forms must use the same Hydrogen line-item form contract as the `/cart` page — see `hydrogen-cart-ui` ("Form structure"). The layout may differ by framework and design system; the form contract must not.
 
diff --git a/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md b/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md
index f1178255e7..dfae19ecec 100644
--- a/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md
+++ b/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md
@@ -2,9 +2,10 @@
 name: hydrogen-cart-ui
 description: >
   Behavioral guide for building cart UI with @shopify/hydrogen: line items,
-  quantity and remove controls, optimistic updates, discount and note inputs,
-  and the full-page /cart fallback. Use when writing, modifying, or reviewing cart
-  line-item UI, quantity/remove controls, or cart mutation forms. Framework agnostic.
+  quantity and remove controls, optimistic updates, discount, note, and cart
+  attribute inputs, and the full-page /cart fallback. Use when writing,
+  modifying, or reviewing cart line-item UI, quantity/remove controls, or cart
+  mutation forms. Framework agnostic.
 ---
 
 # Cart Primitive
@@ -29,17 +30,18 @@ When creating a full cart page, use the app's existing route convention when pre
 
 ## How the store works
 
-The store holds a `CartState` and notifies subscribers when it changes. `state.readyPromise` is present while an applicable full-cart load is pending and resolves after the resulting state is published. Mutations flow through Shopify Standard Actions — the store listens for `shopify:cart:lines-update`, `shopify:cart:discount-update`, and `shopify:cart:note-update` DOM events. Each event carries a `promise` that resolves with the server response.
+The store holds a `CartState` and notifies subscribers when it changes. `state.readyPromise` is present while an applicable full-cart load is pending and resolves after the resulting state is published. Mutations flow through Shopify Standard Actions — the store listens for `shopify:cart:lines-update`, `shopify:cart:discount-update`, `shopify:cart:note-update`, and `shopify:cart:attributes-update` DOM events. Each event carries a `promise` that resolves with the server response.
 
 On mutation:
+
 1. The store applies an **optimistic projection** over its settled state, so the UI-visible state changes immediately.
-2. The affected entity is added to `pending` — a set of in-flight line IDs, discount codes, or a note boolean.
+2. The affected entity is added to `pending` — a set of in-flight line IDs or discount codes, or a note/attributes boolean.
 3. When the promise resolves, the store folds that transaction into settled state and reapplies remaining projections. Overlapping mutations discard ambiguous response snapshots, then coalesce one authoritative cart refresh after the burst settles.
 4. On failure, the store removes only the failed projection, preserves unrelated work, and clears the matching pending entry.
 
 When overlapping mutations make response snapshots ambiguous, the store sets `state.revalidating` to `true`. It starts one authoritative refresh after those mutations settle and clears the flag when the refresh completes or fails. Until then, server-derived values such as costs remain at their last trustworthy value. A refresh failure preserves the locally reconciled cart and appears in `errors.network`.
 
-The store supersedes keyed mutations for the same line, discount batch, or note. Relative additions remain independent so every submitted quantity reaches the server; their projections are reconciled together without disabling controls.
+The store supersedes keyed mutations for the same line, discount batch, note, or complete attribute list. Relative additions remain independent so every submitted quantity reaches the server; their projections are reconciled together without disabling controls.
 
 ## Stable selectors
 
@@ -74,6 +76,7 @@ const messages = deriveFromErrors(errors, () => {
 - `pending.discountCodes` — `Set<string>` of discount codes being applied or removed.
 - `pending.cost` — `true` when pending line or discount mutations can leave totals stale.
 - `pending.note` — `boolean` indicating whether a note save is in flight.
+- `pending.attributes` — `boolean` indicating whether a complete attribute-list update is in flight.
 
 Any value whose entity is in a pending set is **optimistic and unconfirmed**. The UI must treat it differently from confirmed values.
 
@@ -86,9 +89,10 @@ Any value whose entity is in a pending set is **optimistic and unconfirmed**. Th
 - `errors.lines` — `Map<string, CartErrorGroup>` keyed by line ID.
 - `errors.discountCodes` — `Map<string, CartErrorGroup>` keyed by discount code string.
 - `errors.note` — `CartErrorGroup` for note-related errors.
+- `errors.attributes` — `Map<string, CartErrorGroup>` keyed by attribute key.
 - `errors.cart` — `CartErrorGroup` for cart-level errors not attributable to a specific entity.
 - `errors.network` — `CartNetworkEntry[]` for transport failures (timeouts, HTTP errors).
-- `errors.lastUpdatedAt` — timestamp of the most recent error update across any scope. Per-scope timestamps also exist (`linesUpdatedAt`, `discountCodesUpdatedAt`, etc.).
+- `errors.lastUpdatedAt` — timestamp of the most recent error update across any scope. Per-scope timestamps also exist (`linesUpdatedAt`, `discountCodesUpdatedAt`, `attributesUpdatedAt`, etc.).
 
 Each `CartErrorGroup` contains `{ userErrors: CartUserError[], warnings: CartWarning[] }`.
 
@@ -105,7 +109,7 @@ Errors survive unrelated cart work and clear when a new mutation begins for the
 
 ### Optimistic interactions
 
-- **NEVER disable interactive controls during pending state.** Increase, decrease, remove, apply, and remove-discount controls must always be interactive. The store's abort-controller pattern makes concurrent mutations safe — a new click supersedes the in-flight request. Disabling for a non-pending reason is fine — for example, the decrease control may be disabled when the quantity is already `<= 1`.
+- **Keep rapid-action controls interactive during pending state.** Increase, decrease, remove, apply, and remove-discount controls must remain interactive. The store's abort-controller pattern makes concurrent mutations safe — a new click supersedes the in-flight request. A save-style editor, such as a gift-message attribute form, may disable its own submit button while its scoped mutation is pending when duplicate saves provide no value. Disabling for a non-pending reason is also fine — for example, the decrease control may be disabled when the quantity is already `<= 1`.
 - **Inventory-aware set-quantity clamping is opt-in.** The default cart query does not request `ProductVariant.quantityAvailable` because that field requires the `unauthenticated_read_product_inventory` Storefront API scope. If a cart UI needs the entered quantity to clamp to sellable inventory before submission, add `quantityAvailable` to the app's custom cart fragment and enable the Hydrogen channel's product inventory permission (`unauthenticated_read_product_inventory`). Without that field, let Shopify validate inventory and surface the returned line error.
 - **NEVER show a spinner or skeleton where a stale value would do.** The user already sees a quantity and a price. Replacing confirmed-looking content with a loading state is a regression. Show the previous value with a visual indicator that it's unconfirmed.
 - **ALWAYS visually indicate unconfirmed data.** Any value whose entity is in a `pending` set must look visually distinct from confirmed values. Reduced opacity is the reference pattern — the stale text acts as a spatial placeholder (like a skeleton), not as readable content. Rules of contrast can be disregarded because the pending value is a signal, not content the user needs to read.
@@ -125,12 +129,21 @@ Errors survive unrelated cart work and clear when a new mutation begins for the
 - **Allow users to click the save button even when the draft matches the stored note** (nothing to save), but prevent any action. This enables progressive enhancement and prevents frustration.
 - **Show a pending indicator** while the note mutation is pending.
 
+### Cart attribute editing
+
+- **Treat an attribute update as complete-list replacement.** `attributes-update` sends the full next attribute list; attributes omitted from the submission are removed. When editing one attribute, explicitly include every unrelated existing attribute as repeated hidden `attributeKey` / `attributeValue` pairs. Submit no pairs to clear all attributes.
+- **Keep keys and values paired and ordered.** Each `attributeKey` must have a corresponding `attributeValue`. Storefront API mutation inputs require string values, so normalize a nullable returned value deliberately (usually to `""`) before resubmitting it.
+- **Use the register contract exactly.** Field names are camelCase (`attributeKey`, `attributeValue`) because they name payload properties. The submit intent is kebab-case (`attributes-update`) because action intents follow the existing `discount-apply`, `discount-remove`, and `note-update` convention.
+- **Maintain a local draft** for an editable attribute when the UI can remain mounted across server responses. Only sync confirmed attribute data into that draft while `pending.attributes` is `false`, so a response does not clobber typing that happened during the request.
+- **Show scoped pending and errors.** Use `pending.attributes` for the save state and display entries from `errors.attributes` next to the editor for the matching key. A save-style submit button may be disabled until the attribute promise settles.
+
 ### Form structure
 
 - **Each line item is its own form.** This gives each line its own identity input and its own submit buttons. A single form containing multiple lines creates ambiguity about which line an action targets.
 - **Each line item form must preserve the progressive-enhancement shape.** The rendered structure will vary by framework and design system, but every line item quantity form needs the same Hydrogen contract: `register("set")`, `register("lineId", { value: line.id })`, and a real editable quantity input using `register("quantity", { value: line.quantity, interactive: true })`. Increase, decrease, and remove buttons are additional submit controls, not replacements for the set intent or the quantity input.
 - **The `set` control is a hidden submit button, not a hidden input.** `register("set")` already returns `{ type: "submit", hidden: true }`; render it on a `<button>`. Do not swap it for `<input type="hidden">` — that removes the submit button, so pressing Enter in the quantity input no longer submits the set action.
 - **Each discount "remove" button is its own form** — separate from the "apply" form. The apply form needs input validation (empty/duplicate prevention); each remove form is a single action.
+- **Attribute forms submit repeated pairs.** Render one `register("attributeKey", {value})` and one `register("attributeValue", {value})` control for every attribute in the complete next list, then submit with `register("attributes-update")`.
 
 ### Loading
 
@@ -167,22 +180,31 @@ Errors survive unrelated cart work and clear when a new mutation begins for the
 15. **No-op save** — When the draft matches the stored note, clicking on save does nothing (but can still be clicked).
 16. **Server sync without clobber** — After save completes, the local draft updates to match the server response — but only when `pending.note` is `false`, preserving any typing the user did in the meantime.
 
+### Cart attributes
+
+17. **Save attribute** — Edit an attribute and submit. The optimistic value appears immediately, `pending.attributes` is `true`, and the editor shows a saving state until confirmation.
+18. **Preserve unrelated attributes** — Saving one attribute includes all unrelated existing key/value pairs; those attributes remain after the server response.
+19. **Clear attributes** — Submitting an empty attribute list removes every cart attribute.
+20. **Failure rollback** — If the update fails, the complete attribute list returns to the last confirmed baseline.
+21. **Attribute-scoped error** — An error for a key appears next to that key's editor and marks its input invalid.
+22. **No draft clobber** — Typing that occurs while an attribute save is pending is not overwritten by the confirming response.
+
 ### Error banner
 
-17. **Network error** — When a mutation fails due to a transport error, a banner appears with the error message and a dismiss control.
-18. **Cart-level error** — Errors not attributable to a line, code, or note appear in the banner.
-19. **Orphaned line error** — If a line no longer exists in `state.data.lines.nodes` but `errors.lines` has an entry for its ID, that error appears in the banner.
-20. **Dismiss and re-trigger** — Dismissing the banner hides it. A subsequent error (with a newer `lastUpdatedAt`) re-shows it.
+23. **Network error** — When a mutation fails due to a transport error, a banner appears with the error message and a dismiss control.
+24. **Cart-level error** — Errors not attributable to a line, code, note, or attribute appear in the banner.
+25. **Orphaned line error** — If a line no longer exists in `state.data.lines.nodes` but `errors.lines` has an entry for its ID, that error appears in the banner.
+26. **Dismiss and re-trigger** — Dismissing the banner hides it. A subsequent error (with a newer `lastUpdatedAt`) re-shows it.
 
 ### Totals
 
-21. **Pending totals** — While any line or discount mutation is in-flight, subtotal and total appear in their pending visual state. The amounts shown are the last server-confirmed values — never client-computed.
-22. **Settled totals** — After an ordinary mutation settles, totals display the latest server values. Overlapping mutation bursts retain pending styling and the last trustworthy amounts while one authoritative cart refresh is in flight.
+27. **Pending totals** — While any line or discount mutation is in-flight, subtotal and total appear in their pending visual state. The amounts shown are the last server-confirmed values — never client-computed.
+28. **Settled totals** — After an ordinary mutation settles, totals display the latest server values. Overlapping mutation bursts retain pending styling and the last trustworthy amounts while one authoritative cart refresh is in flight.
 
 ### Loading
 
-23. **Initial load** — Before the cart is fetched, show skeleton placeholders.
-24. **Empty cart** — After fetch completes with zero lines, show empty state.
+29. **Initial load** — Before the cart is fetched, show skeleton placeholders.
+30. **Empty cart** — After fetch completes with zero lines, show empty state.
 
 ---
 
diff --git a/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md b/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md
index 6b333aa1b7..1b403a017f 100644
--- a/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md
+++ b/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md
@@ -149,6 +149,8 @@ const lines = useCart((state) => state.data.lines.nodes);
 const pendingLines = useCart((state) => state.pending.lines);
 const totalsPending = useCart((state) => state.pending.cost === true || state.revalidating === true);
 const lineErrors = useCart((state) => state.errors.lines);
+const attributesPending = useCart((state) => state.pending.attributes);
+const attributeErrors = useCart((state) => state.errors.attributes);
 ```
 
 Use this for the navbar cart count, cart line list, totals, pending state, and scoped errors. Do not mirror selected cart state into React state; the store already publishes updates.
@@ -174,7 +176,7 @@ Keep using `useCart(selector)` for non-blocking UI such as cart counts, pending
 
 ## Mutating Cart State
 
-Use `useCartForm()` for existing cart forms: line quantity changes, line removal, discount codes, and order notes. It returns `formProps()` and `register()` helpers that encode Hydrogen's cart action contract.
+Use `useCartForm()` for existing cart forms: line quantity changes, line removal, discount codes, order notes, and cart attributes. It returns `formProps()` and `register()` helpers that encode Hydrogen's cart action contract.
 
 Line item quantity forms must keep this shape even when the surrounding markup, styling, or component boundaries differ:
 
@@ -214,6 +216,35 @@ Important React form fields:
 - `register("increase")`, `register("decrease")`, and `register("remove")` create line item controls.
 - `register("discountCode", { defaultValue: "" })`, `register("discountCode", { value: code })`, `register("discount-apply")`, and `register("discount-remove")` create discount forms.
 - `register("note")` and `register("note-update")` create note forms.
+- Repeated `register("attributeKey", { value: key })` and `register("attributeValue", { value })` controls define the complete next cart attribute list; `register("attributes-update")` submits it. Preserve unrelated attributes explicitly because omitted attributes are removed.
+
+A save-style attribute editor can use the scoped pending boolean to prevent duplicate saves while the promise resolves:
+
+```tsx
+function GiftMessage({ attributes }: { attributes: Array<{ key: string; value: string | null }> }) {
+  const { formProps, register } = useCartForm();
+  const pending = useCart((state) => state.pending.attributes);
+  const key = "gift-message";
+
+  return (
+    <form {...formProps()}>
+      {attributes.filter((attribute) => attribute.key !== key).map((attribute) => (
+        <Fragment key={attribute.key}>
+          <input type="hidden" {...register("attributeKey", { value: attribute.key })} />
+          <input type="hidden" {...register("attributeValue", { value: attribute.value ?? "" })} />
+        </Fragment>
+      ))}
+      <input type="hidden" {...register("attributeKey", { value: key })} />
+      <textarea {...register("attributeValue", { defaultValue: attributes.find((attribute) => attribute.key === key)?.value ?? "" })} />
+      <button type="submit" {...register("attributes-update")} disabled={pending} aria-busy={pending}>
+        {pending ? "Saving…" : "Save message"}
+      </button>
+    </form>
+  );
+}
+```
+
+Import `Fragment` from React for this example, or use a keyed wrapper element. If the cart page and drawer can render together, also give the textarea a `useId()`-generated ID instead of a hard-coded document ID.
 
 Each line item still gets its own form; the binding removes boilerplate, not the form identity requirement.
 
diff --git a/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md b/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md
index 95c841dfca..03a9005ab4 100644
--- a/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md
+++ b/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md
@@ -128,6 +128,8 @@ const lines = useCart((state) => state.data.lines.nodes);
 const pendingLines = useCart((state) => state.pending.lines);
 const totalsPending = useCart((state) => state.pending.cost === true || state.revalidating === true);
 const lineErrors = useCart((state) => state.errors.lines);
+const attributesPending = useCart((state) => state.pending.attributes);
+const attributeErrors = useCart((state) => state.errors.attributes);
 </script>
 
 <template>
@@ -180,6 +182,7 @@ Important Vue form fields:
 - `register("increase")`, `register("decrease")`, and `register("remove")` create line item controls.
 - `register("discountCode", { defaultValue: "" })`, `register("discountCode", { value: code })`, `register("discount-apply")`, and `register("discount-remove")` create discount forms.
 - `register("note")` and `register("note-update")` create note forms.
+- Repeated `register("attributeKey", { value: key })` and `register("attributeValue", { value })` controls define the complete next cart attribute list; `register("attributes-update")` submits it. Preserve unrelated attributes explicitly because omitted attributes are removed. Use `pending.attributes` for a scoped saving state.
 
 Each line item still gets its own form; the binding removes boilerplate, not the form identity requirement.
 
diff --git a/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md b/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md
index ef09d20f6d..a93b5852d6 100644
--- a/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md
+++ b/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md
@@ -52,7 +52,8 @@ Cart:
 - [ ] Each line item form includes hidden set, scoped lineId, and editable quantity
 - [ ] Quantity Enter key submits a set action
 - [ ] Rapid quantity clicks settle to the final expected quantity
-- [ ] Line, discount, note, network, and cart-level errors appear in the right scope
+- [ ] Line, discount, note, attribute, network, and cart-level errors appear in the right scope
+- [ ] Attribute editing submits the complete list, preserves unrelated attributes, and shows scoped pending UI
 - [ ] Totals are server-provided and visually pending during cart mutations
 
 Collection and search:
@@ -170,7 +171,8 @@ Expected: a redirect whose `location` header points at Shopify's hosted login, n
 - Each line item form includes hidden `set`, scoped `lineId`, and editable `quantity`.
 - Quantity Enter key submits a set action.
 - Rapid quantity clicks settle to the final expected quantity.
-- Line, discount, note, network, and cart-level errors appear in the right scope.
+- Line, discount, note, attribute, network, and cart-level errors appear in the right scope.
+- Saving one cart attribute submits the complete next list, preserves unrelated attributes, and shows a saving state while `pending.attributes` is true. Submitting no attribute pairs clears the list.
 - Totals are server-provided and visually pending during cart mutations.
 
 ## Collection And Search
diff --git a/templates/nextjs/lib/content.ts b/templates/nextjs/lib/content.ts
index 2a5f9adb79..cadaa018bf 100644
--- a/templates/nextjs/lib/content.ts
+++ b/templates/nextjs/lib/content.ts
@@ -40,6 +40,12 @@ export const content = {
     itemRemoved: "Item removed from cart",
     updated: "Cart updated",
     updateError: "Could not update cart. Please try again.",
+    giftMessage: {
+      label: "Gift message",
+      placeholder: "Add a message for the recipient",
+      save: "Save message",
+      saving: "Saving…",
+    },
     iconLabel: {
       one: "Cart (1 item)",
       other: "Cart ({{ count }} items)",

From 1abc1190f9c14437ed2cd0384428cf949c5f945b Mon Sep 17 00:00:00 2001
From: Andrew Nguyen <andrew.nguyen@shopify.com>
Date: Wed, 5 Aug 2026 14:43:00 -0700
Subject: [PATCH 3/5] feat: update cart with latest attribute behavior

---
 packages/hydrogen/src/core/cart/actions.ts    | 10 +--
 .../hydrogen/vendor/standard-actions.d.ts     | 24 +++---
 packages/hydrogen/vendor/standard-events.d.ts | 73 +++++++++++++++++++
 3 files changed, 90 insertions(+), 17 deletions(-)

diff --git a/packages/hydrogen/src/core/cart/actions.ts b/packages/hydrogen/src/core/cart/actions.ts
index 45aa13c391..e0d0348d70 100644
--- a/packages/hydrogen/src/core/cart/actions.ts
+++ b/packages/hydrogen/src/core/cart/actions.ts
@@ -1,21 +1,21 @@
 import { normalizeCartId } from "./cookie";
 
+export type CartAttributeInput = { key: string; value: string };
+
 export type CartLineAddInput = {
   merchandiseId: string;
   quantity: number;
-  attributes?: Array<{ key: string; value: string }>;
+  attributes?: CartAttributeInput[];
   sellingPlanId?: string;
 };
 
 export type CartLineUpdateInput = {
   id: string;
   quantity: number;
-  attributes?: Array<{ key: string; value: string }>;
+  attributes?: CartAttributeInput[];
   sellingPlanId?: string;
 };
 
-export type CartAttributeInput = { key: string; value: string };
-
 export type CartAction =
   | { intent: "add"; lines: CartLineAddInput[] }
   | { intent: "update"; lines: CartLineUpdateInput[] }
@@ -165,7 +165,7 @@ function extractOptionalLineFields(
   const result: Pick<CartLineAddInput, "attributes" | "sellingPlanId"> = {};
 
   if ("attributes" in line && Array.isArray(line.attributes)) {
-    result.attributes = line.attributes as Array<{ key: string; value: string }>;
+    result.attributes = line.attributes as CartAttributeInput[];
   }
 
   if ("sellingPlanId" in line && typeof line.sellingPlanId === "string") {
diff --git a/packages/hydrogen/vendor/standard-actions.d.ts b/packages/hydrogen/vendor/standard-actions.d.ts
index 59d7a74727..327b6abb1d 100644
--- a/packages/hydrogen/vendor/standard-actions.d.ts
+++ b/packages/hydrogen/vendor/standard-actions.d.ts
@@ -1,4 +1,8 @@
 // version: ea315691e9819723879605d727a20fde6bdda314
+// NOTE: hand-patched with cart attribute types from
+// shopify-playground/storefront-standard-events#161 (84234055) pending the
+// next Standard Actions CDN release. Re-run scripts/download-standard-types.ts
+// once the release ships to replace this file.
 export interface Price {
 	amount: string;
 	currencyCode: string;
@@ -66,6 +70,10 @@ export interface ActionFunction<P, R, Meta extends object = {}, O = void> {
 }
 export type UpdateCartUserError = CartMutationUserError;
 export type UpdateCartWarning = CartMutationWarning;
+export interface CartAttributeInput {
+	key: string;
+	value: string;
+}
 export interface StorefrontCartLinesConnection {
 	nodes: CartLine[];
 }
@@ -75,10 +83,6 @@ export interface StorefrontCartSummary {
 	cost: CartCost;
 	lines: StorefrontCartLinesConnection;
 	discountCodes: CartDiscountCode[];
-	attributes?: Array<{
-		key: string;
-		value: string;
-	}>;
 }
 export type UpdateCartEventTargetMeta = {
 	type: "shopify:cart:lines-update";
@@ -106,10 +110,8 @@ export interface CartLineInput {
 	merchandiseId?: string;
 	/** Set to 0 to remove. */
 	quantity: number;
-	attributes?: Array<{
-		key: string;
-		value: string;
-	}>;
+	/** Line item-level custom attributes */
+	attributes?: CartAttributeInput[];
 	/** Selling plan GID or raw selling plan id. */
 	sellingPlanId?: string;
 }
@@ -119,10 +121,8 @@ export interface UpdateCartPayload {
 	lines?: CartLineInput[];
 	note?: string;
 	discountCodes?: string[];
-	attributes?: Array<{
-		key: string;
-		value: string;
-	}>;
+	/** Cart-level custom attributes */
+	attributes?: CartAttributeInput[];
 }
 export interface UpdateCartResult {
 	cart: StorefrontCartSummary;
diff --git a/packages/hydrogen/vendor/standard-events.d.ts b/packages/hydrogen/vendor/standard-events.d.ts
index dd9216e779..43bf6f56df 100644
--- a/packages/hydrogen/vendor/standard-events.d.ts
+++ b/packages/hydrogen/vendor/standard-events.d.ts
@@ -1,4 +1,18 @@
 // version: ea315691e9819723879605d727a20fde6bdda314
+// NOTE: hand-patched with cart attribute types from
+// shopify-playground/storefront-standard-events#161 (84234055) pending the
+// next Standard Events CDN release. Re-run scripts/download-standard-types.ts
+// once the release ships to replace this file.
+export interface CartAttributeInput {
+	key: string;
+	value: string;
+}
+export interface CartAttributesUpdatePayloadDetail {
+	[k: string]: unknown;
+}
+export interface CartAttributesUpdateResultDetail {
+	[k: string]: unknown;
+}
 export interface CartDiscountUpdatePayloadDetail {
 	[k: string]: unknown;
 }
@@ -50,6 +64,55 @@ export interface SearchUpdatePayloadDetail {
 export interface SearchUpdateResultDetail {
 	[k: string]: unknown;
 }
+export interface CartAttributesUpdatePayload {
+	context: "product" | "cart" | "dialog" | "standard-action";
+	attributes: CartAttributeInput[];
+	promise: Promise<CartAttributesUpdateResult>;
+	/**
+	 * Optional custom data. Use this to provide additional data for internal use in the theme.
+	 */
+	detail?: CartAttributesUpdatePayloadDetail;
+}
+export interface CartAttributesUpdateResult {
+	cart: {
+		id: string;
+		totalQuantity: number;
+		cost: {
+			totalAmount: {
+				amount: string;
+				currencyCode: string;
+			};
+		};
+		lines: {
+			id: string;
+			quantity: number;
+			cost: {
+				totalAmount: {
+					amount: string;
+					currencyCode: string;
+				};
+			};
+		}[];
+		discountCodes: {
+			applicable: boolean;
+			code: string;
+		}[];
+	} | null;
+	userErrors?: {
+		code?: string;
+		field?: string[];
+		message: string;
+	}[];
+	warnings?: {
+		code?: string;
+		message: string;
+		target?: string;
+	}[];
+	/**
+	 * Optional custom data. Use this to provide additional data for internal use in the theme.
+	 */
+	detail?: CartAttributesUpdateResultDetail;
+}
 export interface CartDiscountUpdatePayload {
 	discountCodes: {
 		code: string;
@@ -522,6 +585,7 @@ export interface SearchUpdateResult {
 	detail?: SearchUpdateResultDetail;
 }
 export interface StandardStorefrontEventMap {
+	"shopify:cart:attributes-update": CartAttributesUpdateEvent;
 	"shopify:cart:discount-update": CartDiscountUpdateEvent;
 	"shopify:cart:error": CartErrorEvent;
 	"shopify:cart:lines-update": CartLinesUpdateEvent;
@@ -596,6 +660,7 @@ export declare const StandardEvents: {
 	readonly cartError: "shopify:cart:error";
 	readonly cartLinesUpdate: "shopify:cart:lines-update";
 	readonly cartNoteUpdate: "shopify:cart:note-update";
+	readonly cartAttributesUpdate: "shopify:cart:attributes-update";
 	readonly cartDiscountUpdate: "shopify:cart:discount-update";
 	readonly searchUpdate: "shopify:search:update";
 	readonly collectionView: "shopify:collection:view";
@@ -863,6 +928,14 @@ export declare class CartNoteUpdateEvent extends ShopifyStandardEvent {
 	};
 	constructor(payload: WithGidInput<CartNoteUpdatePayload>);
 }
+export interface CartAttributesUpdateEvent extends CartAttributesUpdatePayload {
+}
+export declare class CartAttributesUpdateEvent extends ShopifyStandardEvent {
+	static readonly eventName: "shopify:cart:attributes-update";
+	static createCartFromAjaxResponse: typeof fromAjaxCart;
+	static createPromise: typeof CartNoteUpdateEvent.createPromise;
+	constructor(payload: WithGidInput<CartAttributesUpdatePayload>);
+}
 export interface CartDiscountUpdateEvent extends CartDiscountUpdatePayload {
 }
 export declare class CartDiscountUpdateEvent extends ShopifyStandardEvent {

From fcfb28deaf6848e40471b429ae07528e88748c95 Mon Sep 17 00:00:00 2001
From: Andrew Nguyen <andrew.nguyen@shopify.com>
Date: Mon, 10 Aug 2026 15:06:47 -0700
Subject: [PATCH 4/5] feat: sync latest standard events and actions type from
 CDN

---
 .../hydrogen/vendor/standard-actions.d.ts     |  6 +-
 packages/hydrogen/vendor/standard-events.d.ts | 93 ++++++++++++++++---
 scripts/download-standard-types.ts            |  7 +-
 .../react-router/app/standard-actions.d.ts    | 23 +++--
 4 files changed, 104 insertions(+), 25 deletions(-)

diff --git a/packages/hydrogen/vendor/standard-actions.d.ts b/packages/hydrogen/vendor/standard-actions.d.ts
index 327b6abb1d..48d5b2a9d2 100644
--- a/packages/hydrogen/vendor/standard-actions.d.ts
+++ b/packages/hydrogen/vendor/standard-actions.d.ts
@@ -1,8 +1,4 @@
-// version: ea315691e9819723879605d727a20fde6bdda314
-// NOTE: hand-patched with cart attribute types from
-// shopify-playground/storefront-standard-events#161 (84234055) pending the
-// next Standard Actions CDN release. Re-run scripts/download-standard-types.ts
-// once the release ships to replace this file.
+// version: 977e4f914dd2b3eca85ad01dee81c2c96eb1b2e5
 export interface Price {
 	amount: string;
 	currencyCode: string;
diff --git a/packages/hydrogen/vendor/standard-events.d.ts b/packages/hydrogen/vendor/standard-events.d.ts
index 43bf6f56df..d7b2f67309 100644
--- a/packages/hydrogen/vendor/standard-events.d.ts
+++ b/packages/hydrogen/vendor/standard-events.d.ts
@@ -1,12 +1,4 @@
-// version: ea315691e9819723879605d727a20fde6bdda314
-// NOTE: hand-patched with cart attribute types from
-// shopify-playground/storefront-standard-events#161 (84234055) pending the
-// next Standard Events CDN release. Re-run scripts/download-standard-types.ts
-// once the release ships to replace this file.
-export interface CartAttributeInput {
-	key: string;
-	value: string;
-}
+// version: 977e4f914dd2b3eca85ad01dee81c2c96eb1b2e5
 export interface CartAttributesUpdatePayloadDetail {
 	[k: string]: unknown;
 }
@@ -66,7 +58,10 @@ export interface SearchUpdateResultDetail {
 }
 export interface CartAttributesUpdatePayload {
 	context: "product" | "cart" | "dialog" | "standard-action";
-	attributes: CartAttributeInput[];
+	attributes: {
+		key: string;
+		value: string;
+	}[];
 	promise: Promise<CartAttributesUpdateResult>;
 	/**
 	 * Optional custom data. Use this to provide additional data for internal use in the theme.
@@ -933,7 +928,83 @@ export interface CartAttributesUpdateEvent extends CartAttributesUpdatePayload {
 export declare class CartAttributesUpdateEvent extends ShopifyStandardEvent {
 	static readonly eventName: "shopify:cart:attributes-update";
 	static createCartFromAjaxResponse: typeof fromAjaxCart;
-	static createPromise: typeof CartNoteUpdateEvent.createPromise;
+	static createPromise: () => {
+		promise: Promise<{
+			cart: {
+				id: string | number;
+				totalQuantity: number;
+				cost: {
+					totalAmount: {
+						amount: string;
+						currencyCode: string;
+					};
+				};
+				lines: {
+					id: string | number;
+					quantity: number;
+					cost: {
+						totalAmount: {
+							amount: string;
+							currencyCode: string;
+						};
+					};
+				}[];
+				discountCodes: {
+					applicable: boolean;
+					code: string;
+				}[];
+			} | null;
+			userErrors?: {
+				code?: string | undefined;
+				field?: string[] | undefined;
+				message: string;
+			}[] | undefined;
+			warnings?: {
+				code?: string | undefined;
+				message: string;
+				target?: string | undefined;
+			}[] | undefined;
+			detail?: any;
+		}>;
+		resolve: (value: {
+			cart: {
+				id: string | number;
+				totalQuantity: number;
+				cost: {
+					totalAmount: {
+						amount: string;
+						currencyCode: string;
+					};
+				};
+				lines: {
+					id: string | number;
+					quantity: number;
+					cost: {
+						totalAmount: {
+							amount: string;
+							currencyCode: string;
+						};
+					};
+				}[];
+				discountCodes: {
+					applicable: boolean;
+					code: string;
+				}[];
+			} | null;
+			userErrors?: {
+				code?: string | undefined;
+				field?: string[] | undefined;
+				message: string;
+			}[] | undefined;
+			warnings?: {
+				code?: string | undefined;
+				message: string;
+				target?: string | undefined;
+			}[] | undefined;
+			detail?: any;
+		}) => void;
+		reject: (reason?: any) => void;
+	};
 	constructor(payload: WithGidInput<CartAttributesUpdatePayload>);
 }
 export interface CartDiscountUpdateEvent extends CartDiscountUpdatePayload {
diff --git a/scripts/download-standard-types.ts b/scripts/download-standard-types.ts
index 7e445a4adb..479aac6232 100644
--- a/scripts/download-standard-types.ts
+++ b/scripts/download-standard-types.ts
@@ -30,12 +30,13 @@ async function downloadFile(url: string): Promise<string> {
 function normalizeStandardActionsTypes(file: string, source: string): string {
   if (file !== "standard-actions.d.ts") return source;
 
+  // Hydrogen owns a richer ShopifyGlobal declaration in src/globals.ts, so
+  // retain the action type but omit the CDN file's overlapping ambient global.
   return source
-    .replace("Shopify: Shopify & {", "Shopify?: Shopify & {")
     .replace("cart: CartSummary;", "cart: CartSummary | null;")
     .replace(
-      "declare global {",
-      "export type ShopifyStandardActions = typeof actions;\ndeclare global {",
+      /\ndeclare global \{[\s\S]*?\n\}\n\nexport \{\};/,
+      "\nexport type ShopifyStandardActions = typeof actions;\n\nexport {};",
     );
 }
 
diff --git a/templates/react-router/app/standard-actions.d.ts b/templates/react-router/app/standard-actions.d.ts
index 1b9c7feac5..7a196ad4ba 100644
--- a/templates/react-router/app/standard-actions.d.ts
+++ b/templates/react-router/app/standard-actions.d.ts
@@ -9,7 +9,7 @@
 // any sibling example. @shopify/hydrogen's own analytics globals augment the
 // `Shopify` interface declared here (see its src/core/analytics/globals.d.ts).
 //
-// version: ea315691e9819723879605d727a20fde6bdda314
+// version: 977e4f914dd2b3eca85ad01dee81c2c96eb1b2e5
 export interface Price {
   amount: string;
   currencyCode: string;
@@ -56,6 +56,10 @@ export interface ActionFunction<P, R, Meta extends object = {}, O = void> {
 }
 export type UpdateCartUserError = CartMutationUserError;
 export type UpdateCartWarning = CartMutationWarning;
+export interface CartAttributeInput {
+  key: string;
+  value: string;
+}
 export interface StorefrontCartLinesConnection {
   nodes: CartLine[];
 }
@@ -72,7 +76,11 @@ export type UpdateCartEventTargetMeta =
       action: CartUpdateAction;
     }
   | {
-      type: "shopify:cart:note-update" | "shopify:cart:discount-update" | "shopify:cart:error";
+      type:
+        | "shopify:cart:note-update"
+        | "shopify:cart:attributes-update"
+        | "shopify:cart:discount-update"
+        | "shopify:cart:error";
     };
 export interface EventTargetConfigurationMeta {
   /**
@@ -94,10 +102,8 @@ export interface CartLineInput {
   merchandiseId?: string;
   /** Set to 0 to remove. */
   quantity: number;
-  attributes?: Array<{
-    key: string;
-    value: string;
-  }>;
+  /** Line item-level custom attributes */
+  attributes?: CartAttributeInput[];
   /** Selling plan GID or raw selling plan id. */
   sellingPlanId?: string;
 }
@@ -107,6 +113,8 @@ export interface UpdateCartPayload {
   lines?: CartLineInput[];
   note?: string;
   discountCodes?: string[];
+  /** Cart-level custom attributes */
+  attributes?: CartAttributeInput[];
 }
 export interface UpdateCartResult {
   cart: StorefrontCartSummary;
@@ -160,6 +168,9 @@ declare global {
     actions?: typeof actions;
     country?: string;
     locale?: string;
+    theme?: {
+      theme_store_id?: number | null;
+    };
   }
   interface Window {
     Shopify?: Shopify & {

From 30db11796e3ac6a2bcc35c6a2670d1ee575f94e5 Mon Sep 17 00:00:00 2001
From: Andrew Nguyen <andrew.nguyen@shopify.com>
Date: Thu, 13 Aug 2026 18:38:54 -0700
Subject: [PATCH 5/5] fix: attribute form register and error message

---
 .../hydrogen/app/components/CartSummary.tsx   |  30 +++-
 .../hydrogen/skills/hydrogen-cart-ui/SKILL.md |   8 +-
 .../hydrogen-cart-ui/references/react.md      |  24 ++-
 .../skills/hydrogen-cart-ui/references/vue.md |   2 +-
 .../skills/hydrogen-smoke-test/SKILL.md       |   2 +-
 .../hydrogen/src/core/cart/actions.test.ts    |  16 +-
 packages/hydrogen/src/core/cart/actions.ts    |  14 +-
 packages/hydrogen/src/core/cart/cart.test.ts  | 145 +++++++++++++++++-
 packages/hydrogen/src/core/cart/cart.ts       | 105 ++++++++++++-
 packages/hydrogen/src/core/cart/form.test.ts  |  21 ++-
 packages/hydrogen/src/core/cart/form.ts       | 101 ++++++++----
 packages/hydrogen/src/core/cart/index.ts      |   1 +
 packages/hydrogen/src/core/cart/queries.ts    |  57 +++++++
 packages/hydrogen/src/core/cart/state.ts      |   8 +-
 packages/hydrogen/src/react/cart.test.tsx     |   8 +-
 15 files changed, 450 insertions(+), 92 deletions(-)

diff --git a/examples/hydrogen/app/components/CartSummary.tsx b/examples/hydrogen/app/components/CartSummary.tsx
index 0c5440a300..93268c11c6 100644
--- a/examples/hydrogen/app/components/CartSummary.tsx
+++ b/examples/hydrogen/app/components/CartSummary.tsx
@@ -43,26 +43,44 @@ const GIFT_MESSAGE_ATTRIBUTE = "gift-message";
 function CartGiftMessage({ attributes }: { attributes: CartData["attributes"] }) {
   const { formProps, register } = useCartForm();
   const attributesPending = useCart((state) => state.pending.attributes);
+  const giftMessageErrors = useCart((state) => state.errors.attributes.get(GIFT_MESSAGE_ATTRIBUTE));
   const giftMessageId = useId();
+  const giftMessageErrorId = useId();
   const giftMessage = attributes.find(({ key }) => key === GIFT_MESSAGE_ATTRIBUTE)?.value ?? "";
   const preservedAttributes = attributes.filter(({ key }) => key !== GIFT_MESSAGE_ATTRIBUTE);
+  const giftMessageErrorMessages = [
+    ...(giftMessageErrors?.userErrors ?? []),
+    ...(giftMessageErrors?.warnings ?? []),
+  ];
 
   return (
     <form {...formProps()} className="cart-attribute">
       {preservedAttributes.map(({ key, value }) => (
-        <div key={key}>
-          <input type="hidden" {...register("attributeKey", { value: key })} />
-          <input type="hidden" {...register("attributeValue", { value: value ?? "" })} />
-        </div>
+        <input
+          key={key}
+          type="hidden"
+          {...register("attributeValue", { key, value: value ?? "" })}
+        />
       ))}
-      <input type="hidden" {...register("attributeKey", { value: GIFT_MESSAGE_ATTRIBUTE })} />
       <label htmlFor={giftMessageId}>Gift message</label>
       <textarea
         id={giftMessageId}
         rows={3}
-        {...register("attributeValue", { defaultValue: giftMessage })}
+        {...register("attributeValue", {
+          key: GIFT_MESSAGE_ATTRIBUTE,
+          defaultValue: giftMessage,
+        })}
+        aria-describedby={giftMessageErrorMessages.length > 0 ? giftMessageErrorId : undefined}
+        aria-invalid={(giftMessageErrors?.userErrors.length ?? 0) > 0 || undefined}
         placeholder="Add a message for the recipient"
       />
+      {giftMessageErrorMessages.length > 0 ? (
+        <div id={giftMessageErrorId} role="alert">
+          {giftMessageErrorMessages.map(({ message }, index) => (
+            <p key={`${message}-${index}`}>{message}</p>
+          ))}
+        </div>
+      ) : null}
       <button
         type="submit"
         {...register("attributes-update")}
diff --git a/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md b/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md
index dfae19ecec..7ef5cfb156 100644
--- a/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md
+++ b/packages/hydrogen/skills/hydrogen-cart-ui/SKILL.md
@@ -131,9 +131,9 @@ Errors survive unrelated cart work and clear when a new mutation begins for the
 
 ### Cart attribute editing
 
-- **Treat an attribute update as complete-list replacement.** `attributes-update` sends the full next attribute list; attributes omitted from the submission are removed. When editing one attribute, explicitly include every unrelated existing attribute as repeated hidden `attributeKey` / `attributeValue` pairs. Submit no pairs to clear all attributes.
-- **Keep keys and values paired and ordered.** Each `attributeKey` must have a corresponding `attributeValue`. Storefront API mutation inputs require string values, so normalize a nullable returned value deliberately (usually to `""`) before resubmitting it.
-- **Use the register contract exactly.** Field names are camelCase (`attributeKey`, `attributeValue`) because they name payload properties. The submit intent is kebab-case (`attributes-update`) because action intents follow the existing `discount-apply`, `discount-remove`, and `note-update` convention.
+- **Treat an attribute update as complete-list replacement.** `attributes-update` sends the full next attribute list; attributes omitted from the submission are removed. When editing one attribute, explicitly include every unrelated existing attribute as a hidden keyed `attributeValue` field. Submit no attribute fields to clear all attributes.
+- **Keep each key attached to its value.** Pass the attribute key to every `register("attributeValue", {key, ...})` call. The generated `attributes.<key>` field name encodes that key, so the server never relies on parallel field positions. Storefront API mutation inputs require string values, so normalize a nullable returned value deliberately (usually to `""`) before resubmitting it.
+- **Use the register contract exactly.** Call `register("attributeValue", {key, ...})` rather than spelling its generated `attributes.<key>` field name by hand. The submit intent is kebab-case (`attributes-update`) because action intents follow the existing `discount-apply`, `discount-remove`, and `note-update` convention.
 - **Maintain a local draft** for an editable attribute when the UI can remain mounted across server responses. Only sync confirmed attribute data into that draft while `pending.attributes` is `false`, so a response does not clobber typing that happened during the request.
 - **Show scoped pending and errors.** Use `pending.attributes` for the save state and display entries from `errors.attributes` next to the editor for the matching key. A save-style submit button may be disabled until the attribute promise settles.
 
@@ -143,7 +143,7 @@ Errors survive unrelated cart work and clear when a new mutation begins for the
 - **Each line item form must preserve the progressive-enhancement shape.** The rendered structure will vary by framework and design system, but every line item quantity form needs the same Hydrogen contract: `register("set")`, `register("lineId", { value: line.id })`, and a real editable quantity input using `register("quantity", { value: line.quantity, interactive: true })`. Increase, decrease, and remove buttons are additional submit controls, not replacements for the set intent or the quantity input.
 - **The `set` control is a hidden submit button, not a hidden input.** `register("set")` already returns `{ type: "submit", hidden: true }`; render it on a `<button>`. Do not swap it for `<input type="hidden">` — that removes the submit button, so pressing Enter in the quantity input no longer submits the set action.
 - **Each discount "remove" button is its own form** — separate from the "apply" form. The apply form needs input validation (empty/duplicate prevention); each remove form is a single action.
-- **Attribute forms submit repeated pairs.** Render one `register("attributeKey", {value})` and one `register("attributeValue", {value})` control for every attribute in the complete next list, then submit with `register("attributes-update")`.
+- **Attribute forms submit keyed values.** Render one `register("attributeValue", {key, value})` control for every attribute in the complete next list, then submit with `register("attributes-update")`.
 
 ### Loading
 
diff --git a/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md b/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md
index 1b403a017f..bb7f7aceea 100644
--- a/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md
+++ b/packages/hydrogen/skills/hydrogen-cart-ui/references/react.md
@@ -216,7 +216,7 @@ Important React form fields:
 - `register("increase")`, `register("decrease")`, and `register("remove")` create line item controls.
 - `register("discountCode", { defaultValue: "" })`, `register("discountCode", { value: code })`, `register("discount-apply")`, and `register("discount-remove")` create discount forms.
 - `register("note")` and `register("note-update")` create note forms.
-- Repeated `register("attributeKey", { value: key })` and `register("attributeValue", { value })` controls define the complete next cart attribute list; `register("attributes-update")` submits it. Preserve unrelated attributes explicitly because omitted attributes are removed.
+- Repeated `register("attributeValue", { key, value })` controls define the complete next cart attribute list; `register("attributes-update")` submits it. Preserve unrelated attributes explicitly because omitted attributes are removed.
 
 A save-style attribute editor can use the scoped pending boolean to prevent duplicate saves while the promise resolves:
 
@@ -229,13 +229,21 @@ function GiftMessage({ attributes }: { attributes: Array<{ key: string; value: s
   return (
     <form {...formProps()}>
       {attributes.filter((attribute) => attribute.key !== key).map((attribute) => (
-        <Fragment key={attribute.key}>
-          <input type="hidden" {...register("attributeKey", { value: attribute.key })} />
-          <input type="hidden" {...register("attributeValue", { value: attribute.value ?? "" })} />
-        </Fragment>
+        <input
+          key={attribute.key}
+          type="hidden"
+          {...register("attributeValue", {
+            key: attribute.key,
+            value: attribute.value ?? "",
+          })}
+        />
       ))}
-      <input type="hidden" {...register("attributeKey", { value: key })} />
-      <textarea {...register("attributeValue", { defaultValue: attributes.find((attribute) => attribute.key === key)?.value ?? "" })} />
+      <textarea
+        {...register("attributeValue", {
+          key,
+          defaultValue: attributes.find((attribute) => attribute.key === key)?.value ?? "",
+        })}
+      />
       <button type="submit" {...register("attributes-update")} disabled={pending} aria-busy={pending}>
         {pending ? "Saving…" : "Save message"}
       </button>
@@ -244,7 +252,7 @@ function GiftMessage({ attributes }: { attributes: Array<{ key: string; value: s
 }
 ```
 
-Import `Fragment` from React for this example, or use a keyed wrapper element. If the cart page and drawer can render together, also give the textarea a `useId()`-generated ID instead of a hard-coded document ID.
+If the cart page and drawer can render together, give the textarea a `useId()`-generated ID instead of a hard-coded document ID.
 
 Each line item still gets its own form; the binding removes boilerplate, not the form identity requirement.
 
diff --git a/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md b/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md
index 03a9005ab4..e4f45c1dc6 100644
--- a/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md
+++ b/packages/hydrogen/skills/hydrogen-cart-ui/references/vue.md
@@ -182,7 +182,7 @@ Important Vue form fields:
 - `register("increase")`, `register("decrease")`, and `register("remove")` create line item controls.
 - `register("discountCode", { defaultValue: "" })`, `register("discountCode", { value: code })`, `register("discount-apply")`, and `register("discount-remove")` create discount forms.
 - `register("note")` and `register("note-update")` create note forms.
-- Repeated `register("attributeKey", { value: key })` and `register("attributeValue", { value })` controls define the complete next cart attribute list; `register("attributes-update")` submits it. Preserve unrelated attributes explicitly because omitted attributes are removed. Use `pending.attributes` for a scoped saving state.
+- Repeated `register("attributeValue", { key, value })` controls define the complete next cart attribute list; `register("attributes-update")` submits it. Preserve unrelated attributes explicitly because omitted attributes are removed. Use `pending.attributes` for a scoped saving state.
 
 Each line item still gets its own form; the binding removes boilerplate, not the form identity requirement.
 
diff --git a/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md b/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md
index a93b5852d6..5eecfc0a3f 100644
--- a/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md
+++ b/packages/hydrogen/skills/hydrogen-smoke-test/SKILL.md
@@ -172,7 +172,7 @@ Expected: a redirect whose `location` header points at Shopify's hosted login, n
 - Quantity Enter key submits a set action.
 - Rapid quantity clicks settle to the final expected quantity.
 - Line, discount, note, attribute, network, and cart-level errors appear in the right scope.
-- Saving one cart attribute submits the complete next list, preserves unrelated attributes, and shows a saving state while `pending.attributes` is true. Submitting no attribute pairs clears the list.
+- Saving one cart attribute submits the complete next list, preserves unrelated attributes, and shows a saving state while `pending.attributes` is true. Submitting no attribute fields clears the list.
 - Totals are server-provided and visually pending during cart mutations.
 
 ## Collection And Search
diff --git a/packages/hydrogen/src/core/cart/actions.test.ts b/packages/hydrogen/src/core/cart/actions.test.ts
index f11bad0d08..abaebf4ccc 100644
--- a/packages/hydrogen/src/core/cart/actions.test.ts
+++ b/packages/hydrogen/src/core/cart/actions.test.ts
@@ -574,13 +574,11 @@ describe("parseCartRequest", () => {
   });
 
   describe("FormData — attributes intent", () => {
-    it("pairs repeated attribute keys and values", async () => {
+    it("parses attribute values with their encoded keys", async () => {
       const body = new URLSearchParams([
         ["intent", "attributes-update"],
-        ["attributeKey", "gift-message"],
-        ["attributeValue", "Happy birthday!"],
-        ["attributeKey", "delivery-date"],
-        ["attributeValue", "Friday"],
+        ["attributes.gift-message", "Happy birthday!"],
+        ["attributes.delivery-date", "Friday"],
       ]);
       const request = new Request("http://localhost/api/cart", {
         method: "POST",
@@ -603,12 +601,10 @@ describe("parseCartRequest", () => {
       expect(action).toEqual({ intent: "attributes-update", attributes: [] });
     });
 
-    it("rejects mismatched attribute fields", async () => {
+    it("rejects an empty encoded attribute key", async () => {
       await expect(
-        parseCartRequest(
-          formRequest({ intent: "attributes-update", attributeKey: "gift-message" }),
-        ),
-      ).rejects.toThrow(/one "attributeValue"/);
+        parseCartRequest(formRequest({ intent: "attributes-update", "attributes.": "value" })),
+      ).rejects.toThrow(/not to be empty/);
     });
   });
 
diff --git a/packages/hydrogen/src/core/cart/actions.ts b/packages/hydrogen/src/core/cart/actions.ts
index e0d0348d70..219aee9b4b 100644
--- a/packages/hydrogen/src/core/cart/actions.ts
+++ b/packages/hydrogen/src/core/cart/actions.ts
@@ -1,4 +1,5 @@
 import { normalizeCartId } from "./cookie";
+import { getCartAttributeFormEntries } from "./form";
 
 export type CartAttributeInput = { key: string; value: string };
 
@@ -183,7 +184,7 @@ function extractOptionalLineFields(
 //   Update qty:     server does the math — form sends current qty, server increments/decrements
 //   Remove line:    explicit intent field (can't express "quantity=0 means remove" implicitly)
 //   Discount bulk:  no FormData equivalent — forms handle one code at a time
-//   Cart attributes: parallel attributeKey/attributeValue fields preserve the ordered list
+//   Cart attributes: attributes.<key> fields preserve each key/value relationship
 //   Selling plan:   add only — no way to change selling plan on existing line via form
 //
 // Design decisions:
@@ -300,18 +301,9 @@ function parseNoteIntent(form: FormData): CartAction {
 }
 
 function parseAttributesIntent(form: FormData): CartAction {
-  const keys = form.getAll("attributeKey");
-  const values = form.getAll("attributeValue");
-
-  if (keys.length !== values.length) {
-    throw new CartActionError(
-      'Intent "attributes-update" requires one "attributeValue" field for every "attributeKey" field.',
-    );
-  }
-
   return {
     intent: "attributes-update",
-    attributes: parseAttributes(keys.map((key, index) => ({ key, value: values[index] }))),
+    attributes: parseAttributes(getCartAttributeFormEntries(form)),
   };
 }
 
diff --git a/packages/hydrogen/src/core/cart/cart.test.ts b/packages/hydrogen/src/core/cart/cart.test.ts
index 5332e4387a..5373e894c2 100644
--- a/packages/hydrogen/src/core/cart/cart.test.ts
+++ b/packages/hydrogen/src/core/cart/cart.test.ts
@@ -242,6 +242,16 @@ function createStandardActionsMock({ dispatchEvents = true } = {}) {
         },
       );
       document.dispatchEvent(event);
+    } else if (dispatchEvents && payload.attributes !== undefined) {
+      const event = Object.assign(
+        new Event("shopify:cart:attributes-update", { bubbles: true, cancelable: true }),
+        {
+          attributes: payload.attributes,
+          promise: eventDeferred.promise,
+          detail: (options as any)?.event?.detail,
+        },
+      );
+      document.dispatchEvent(event);
     }
 
     if (options?.signal) {
@@ -342,6 +352,7 @@ describe("createCartStore", () => {
     expect(state.pending).toEqual({
       lines: new Set(),
       note: false,
+      attributes: false,
       discountCodes: new Set(),
       cost: false,
     });
@@ -819,14 +830,14 @@ describe("CartStore lifecycle", () => {
 
       expect(
         addSpy.mock.calls.filter(([eventName]) => String(eventName).startsWith("shopify:cart:")),
-      ).toHaveLength(3);
+      ).toHaveLength(4);
 
       localStore.destroy();
       localStore.destroy();
 
       expect(
         removeSpy.mock.calls.filter(([eventName]) => String(eventName).startsWith("shopify:cart:")),
-      ).toHaveLength(3);
+      ).toHaveLength(4);
     } finally {
       localStore.destroy();
       addSpy.mockRestore();
@@ -2345,6 +2356,136 @@ describe("CartStore.handleFormSubmit — error handling", () => {
     expect(errors.network).toEqual([]);
   });
 
+  it("optimistically updates cart attributes from a form and reconciles the result", async () => {
+    store.hydrate(
+      makeCartState({
+        id: "gid://shopify/Cart/attributes-success",
+        attributes: [{ key: "gift-message", value: "Old" }],
+      }),
+    );
+    expect(store.getState().data.attributes).toEqual([{ key: "gift-message", value: "Old" }]);
+    const event = submitForm(
+      { "attributes.gift-message": "Happy birthday!" },
+      "intent",
+      "attributes-update",
+    );
+    const promise = store.handleFormSubmit(event);
+    await nextTick();
+
+    expect(mockUpdateCart).toHaveBeenCalledWith(
+      { attributes: [{ key: "gift-message", value: "Happy birthday!" }] },
+      expect.objectContaining({ signal: expect.any(AbortSignal) }),
+    );
+    expect(store.getState().data.attributes).toEqual([
+      { key: "gift-message", value: "Happy birthday!" },
+    ]);
+    expect(store.getState().pending.attributes).toBe(true);
+
+    // Resolved standard-event carts intentionally omit attributes; the
+    // event's top-level attributes describe the resulting state.
+    resolveUpdate(0, serverResult());
+    await promise;
+
+    expect(store.getState().pending.attributes).toBe(false);
+    expect(store.getState().data.attributes).toEqual([
+      { key: "gift-message", value: "Happy birthday!" },
+    ]);
+  });
+
+  it("restores baseline attributes when the result resolves with userErrors", async () => {
+    store.hydrate(
+      makeCartState({
+        id: "gid://shopify/Cart/attributes-user-errors",
+        attributes: [{ key: "gift-message", value: "Old" }],
+      }),
+    );
+    const event = submitForm({ "attributes.gift-message": "New" }, "intent", "attributes-update");
+    const promise = store.handleFormSubmit(event);
+    await nextTick();
+
+    expect(store.getState().data.attributes).toEqual([{ key: "gift-message", value: "New" }]);
+
+    resolveUpdate(0, {
+      ...serverResult(),
+      userErrors: [
+        {
+          code: "INVALID",
+          message: "Invalid gift message",
+          field: ["attributes", "0"],
+        },
+      ],
+    });
+    await promise;
+
+    const state = store.getState();
+    expect(state.data.attributes).toEqual([{ key: "gift-message", value: "Old" }]);
+    expect(state.pending.attributes).toBe(false);
+    expect(state.errors.attributes.get("gift-message")?.userErrors).toEqual([
+      {
+        code: "INVALID",
+        message: "Invalid gift message",
+        field: ["attributes", "0"],
+      },
+    ]);
+  });
+
+  it("preserves attributes when other cart mutations resolve", async () => {
+    store.hydrate(
+      makeCartState({
+        id: "gid://shopify/Cart/attributes-preserved",
+        attributes: [{ key: "gift-message", value: "Keep me" }],
+      }),
+    );
+    const event = submitForm({ note: "new note" }, "intent", "note-update");
+    const promise = store.handleFormSubmit(event);
+    await nextTick();
+
+    // Resolved standard-event carts omit attributes entirely.
+    resolveUpdate(0, serverResult());
+    await promise;
+
+    expect(store.getState().data.note).toBe("new note");
+    expect(store.getState().data.attributes).toEqual([{ key: "gift-message", value: "Keep me" }]);
+  });
+
+  it("rolls back rejected attributes and scopes errors by attribute key", async () => {
+    store.hydrate(
+      makeCartState({
+        id: "gid://shopify/Cart/attributes-failure",
+        attributes: [{ key: "gift-message", value: "Old" }],
+      }),
+    );
+    expect(store.getState().data.attributes).toEqual([{ key: "gift-message", value: "Old" }]);
+    const event = submitForm({ "attributes.gift-message": "New" }, "intent", "attributes-update");
+    const promise = store.handleFormSubmit(event);
+    await nextTick();
+
+    rejectUpdate(
+      0,
+      cartActionError({
+        userErrors: [
+          {
+            code: "INVALID",
+            message: "Invalid gift message",
+            field: ["attributes", "0"],
+          },
+        ],
+      }),
+    );
+    await expect(promise).rejects.toThrow("Cart action failed");
+
+    const state = store.getState();
+    expect(state.data.attributes).toEqual([{ key: "gift-message", value: "Old" }]);
+    expect(state.pending.attributes).toBe(false);
+    expect(state.errors.attributes.get("gift-message")?.userErrors).toEqual([
+      {
+        code: "INVALID",
+        message: "Invalid gift message",
+        field: ["attributes", "0"],
+      },
+    ]);
+  });
+
   it("routes note business errors to errors.network", async () => {
     store.hydrate(makeCartState({ note: "old note" }));
     const event = submitForm({ note: "new note" }, "intent", "note-update");
diff --git a/packages/hydrogen/src/core/cart/cart.ts b/packages/hydrogen/src/core/cart/cart.ts
index 0712b67ebc..0daee0a43d 100644
--- a/packages/hydrogen/src/core/cart/cart.ts
+++ b/packages/hydrogen/src/core/cart/cart.ts
@@ -6,6 +6,8 @@ import type {
   UpdateCartResult,
 } from "../../../vendor/standard-actions";
 import type {
+  CartAttributesUpdateEvent,
+  CartAttributesUpdateResult,
   CartDiscountUpdateEvent,
   CartDiscountUpdateResult,
   CartLinesUpdateEvent,
@@ -20,6 +22,7 @@ import {
   SHOPIFY_STOREFRONT_STANDARD_ACTIONS_SCRIPT,
   VISITOR_CONSENT_COLLECTED_EVENT,
 } from "../shopify-scripts/index";
+import { getCartAttributeFormEntries } from "./form";
 import { DEFAULT_MINIMUM_QUANTITY, sanitizeQuantity } from "./quantity";
 import type {
   CartCost,
@@ -44,6 +47,7 @@ interface CartResponse extends CartData {
 
 type CartMutationResult =
   | UpdateCartResult
+  | CartAttributesUpdateResult
   | CartLinesUpdateResult
   | CartDiscountUpdateResult
   | CartNoteUpdateResult;
@@ -66,6 +70,7 @@ const LINE_KEY_PREFIX = "line:";
 const MERCHANDISE_KEY_PREFIX = "merchandise:";
 const DISCOUNT_KEY_PREFIX = "discount:";
 const NOTE_KEY = "note";
+const ATTRIBUTES_KEY = "attributes";
 const DISCOUNT_CODES_KEY = "discount-codes";
 const REVALIDATION_ERROR_KEY = "cart-revalidation";
 const TRANSACTION_EVENT_TOKEN_KEY = "__shopifyHydrogenCartTransaction";
@@ -138,6 +143,10 @@ type SetNotePayload = {
   note: string;
 };
 
+type SetAttributesPayload = {
+  attributes: Array<{ key: string; value: string }>;
+};
+
 type TransactionDefinition<TPayload> = {
   payload: TPayload;
   transport(
@@ -287,6 +296,7 @@ type CartEventHandlers = {
   lines: EventListener;
   discount: EventListener;
   note: EventListener;
+  attributes: EventListener;
 };
 
 let configuredCartEndpoint: string | null = null;
@@ -461,22 +471,23 @@ function reuseVisibleReferences(previous: CartState, next: CartState): CartState
   const pendingDiscountCodes = sameSet(previous.pending.discountCodes, next.pending.discountCodes)
     ? previous.pending.discountCodes
     : next.pending.discountCodes;
-  const pending = {
+  const nextPending = {
     lines: pendingLines,
     note: next.pending.note,
+    attributes: next.pending.attributes,
     discountCodes: pendingDiscountCodes,
     cost: next.pending.cost,
   };
+  const pending = shallowEqualRecord(previous.pending, nextPending)
+    ? previous.pending
+    : nextPending;
 
   if (
     previous.data === data &&
     previous.loading === next.loading &&
     previous.revalidating === next.revalidating &&
     previous.errors === next.errors &&
-    previous.pending.lines === pending.lines &&
-    previous.pending.note === pending.note &&
-    previous.pending.discountCodes === pending.discountCodes &&
-    previous.pending.cost === pending.cost
+    previous.pending === pending
   ) {
     return previous;
   }
@@ -488,11 +499,13 @@ function derivePending(state: CartState, transactions: PendingTransaction[]): Ca
   const lines = new Set<string>();
   const discountCodes = new Set<string>();
   let note = false;
+  let attributes = false;
   let cost = false;
 
   for (const transaction of transactions) {
     for (const key of transaction.pendingKeys) {
       if (key === NOTE_KEY) note = true;
+      if (key === ATTRIBUTES_KEY) attributes = true;
       if (key.startsWith(LINE_KEY_PREFIX)) {
         lines.add(key.slice(LINE_KEY_PREFIX.length));
         cost = true;
@@ -509,7 +522,7 @@ function derivePending(state: CartState, transactions: PendingTransaction[]): Ca
     }
   }
 
-  return { lines, note, discountCodes, cost };
+  return { lines, note, attributes, discountCodes, cost };
 }
 
 function projectVisibleState(store: CartStoreContext): CartState {
@@ -684,6 +697,23 @@ function groupDiscountErrors(
   return { discountCodes: codes, cart };
 }
 
+function groupAttributeErrors(
+  failure: CartActionFailure | undefined,
+  attributes: CartData["attributes"],
+): { attributes: Map<string, CartErrorGroup>; cart: CartErrorGroup } {
+  const attributeErrors = new Map<string, CartErrorGroup>();
+  const cart = createEmptyErrorGroup();
+
+  for (const error of failure?.userErrors ?? []) {
+    const attributeIndex = findFieldIndex(error.field, "attributes");
+    const key = attributeIndex === undefined ? undefined : attributes[attributeIndex]?.key;
+    const group = key ? getErrorGroup(attributeErrors, key) : cart;
+    group.userErrors.push(toCartUserError(error));
+  }
+  for (const warning of failure?.warnings ?? []) cart.warnings.push(toCartWarning(warning));
+  return { attributes: attributeErrors, cart };
+}
+
 function toCartErrorGroup(failure: CartActionFailure | undefined): CartErrorGroup {
   return {
     userErrors: (failure?.userErrors ?? []).map(toCartUserError),
@@ -782,6 +812,27 @@ function projectNoteErrors(
   };
 }
 
+function projectAttributeErrors(
+  state: CartState,
+  failure: CartActionFailure | undefined,
+  attributes: CartData["attributes"],
+  timestampMs: number,
+): CartState {
+  if (!failure) return state;
+  const grouped = groupAttributeErrors(failure, attributes);
+  return {
+    ...state,
+    errors: {
+      ...state.errors,
+      attributes: new Map([...state.errors.attributes, ...grouped.attributes]),
+      cart: mergeErrorGroups(state.errors.cart, grouped.cart),
+      attributesUpdatedAt: timestampMs,
+      cartUpdatedAt: timestampMs,
+      lastUpdatedAt: timestampMs,
+    },
+  };
+}
+
 function extractProductDetails(
   detail: Record<string, unknown> | undefined,
 ): Array<Record<string, unknown>> {
@@ -1165,6 +1216,25 @@ export const CART_TRANSACTION_TYPES = defineTransactionTypes({
     },
     getSignalKeys: () => NOTE_KEY,
   },
+  set_attributes: {
+    payload: {} as SetAttributesPayload,
+    transport: (payload, signal, updateCart) =>
+      updateCart({ attributes: payload.attributes }, { signal }),
+    projectPayload: (state, payload) => ({
+      ...state,
+      data: { ...state.data, attributes: payload.attributes },
+    }),
+    projectPromise: (state, result, payload, addError) => {
+      if (hasProjectedErrors(result)) {
+        addError((current, timestampMs) =>
+          projectAttributeErrors(current, result, payload.attributes, timestampMs),
+        );
+      }
+      if (!result.cart || (result.userErrors?.length ?? 0) > 0) return state;
+      return { ...state, data: { ...state.data, attributes: payload.attributes } };
+    },
+    getSignalKeys: () => ATTRIBUTES_KEY,
+  },
 });
 
 function getTransactionProjectionKeys<TType extends TransactionType>(
@@ -1775,6 +1845,17 @@ function handleNoteEvent(store: CartStoreContext, event: CartNoteUpdateEvent): v
   );
 }
 
+function handleAttributesEvent(store: CartStoreContext, event: CartAttributesUpdateEvent): void {
+  enqueueTransaction(
+    store,
+    "set_attributes",
+    { attributes: event.attributes },
+    event.promise,
+    undefined,
+    getTransactionEventToken(event.detail),
+  );
+}
+
 function connectCartStore(store: CartStoreContext, handlers: CartEventHandlers): boolean {
   if (typeof document === "undefined") return false;
   if (store.lifecycleController.signal.aborted) store.lifecycleController = new AbortController();
@@ -1785,6 +1866,7 @@ function connectCartStore(store: CartStoreContext, handlers: CartEventHandlers):
   document.addEventListener("shopify:cart:lines-update", handlers.lines);
   document.addEventListener("shopify:cart:discount-update", handlers.discount);
   document.addEventListener("shopify:cart:note-update", handlers.note);
+  document.addEventListener("shopify:cart:attributes-update", handlers.attributes);
   void getShopifyStandardActions().catch(() => {});
   return true;
 }
@@ -1822,6 +1904,7 @@ function destroyCartStore(store: CartStoreContext, handlers: CartEventHandlers):
     document.removeEventListener("shopify:cart:lines-update", handlers.lines);
     document.removeEventListener("shopify:cart:discount-update", handlers.discount);
     document.removeEventListener("shopify:cart:note-update", handlers.note);
+    document.removeEventListener("shopify:cart:attributes-update", handlers.attributes);
   }
   connectedCartStores.delete(store);
   detachCartConsentListenerIfIdle();
@@ -2022,6 +2105,8 @@ export function createCartStore<TData extends CartData = CartData>(
     discount: ((event: Event) =>
       handleDiscountEvent(store, event as CartDiscountUpdateEvent)) as EventListener,
     note: ((event: Event) => handleNoteEvent(store, event as CartNoteUpdateEvent)) as EventListener,
+    attributes: ((event: Event) =>
+      handleAttributesEvent(store, event as CartAttributesUpdateEvent)) as EventListener,
   };
   if (asyncInitialData) {
     loadCartInStore(
@@ -2157,6 +2242,13 @@ async function handleFormSubmitInStore(
     const note = (formData.get("note") as string) ?? "";
     return dispatchTransaction(store, "set_note", { note });
   }
+  if (intent === "attributes-update") {
+    const attributes = getCartAttributeFormEntries(formData).map(({ key, value }) => ({
+      key,
+      value: String(value),
+    }));
+    return dispatchTransaction(store, "set_attributes", { attributes });
+  }
   throw new Error(`Unknown cart form intent: "${intent}"`);
 }
 
@@ -2281,6 +2373,7 @@ function fetchCartData(cartId?: string | null): Promise<CartData | null> {
           ...cart,
           checkoutUrl: cart.checkoutUrl ?? null,
           note: extractNoteFromCart(cart),
+          attributes: cart.attributes ?? [],
         }
       : null,
   );
diff --git a/packages/hydrogen/src/core/cart/form.test.ts b/packages/hydrogen/src/core/cart/form.test.ts
index dc588347ca..240e51c62b 100644
--- a/packages/hydrogen/src/core/cart/form.test.ts
+++ b/packages/hydrogen/src/core/cart/form.test.ts
@@ -60,17 +60,24 @@ describe("createCartFormRegister", () => {
       expect(result).toEqual({ name: "note", defaultValue: "gift wrap" });
     });
 
-    it("attribute fields return repeatable key and value names", () => {
-      expect(register("attributeKey", { value: "gift-message" })).toEqual({
-        name: "attributeKey",
-        value: "gift-message",
-      });
-      expect(register("attributeValue", { defaultValue: "Happy birthday!" })).toEqual({
-        name: "attributeValue",
+    it("attribute values encode their key in the field name", () => {
+      expect(
+        register("attributeValue", {
+          key: "gift-message",
+          defaultValue: "Happy birthday!",
+        }),
+      ).toEqual({
+        name: "attributes.gift-message",
         defaultValue: "Happy birthday!",
       });
     });
 
+    it("rejects an empty attribute key", () => {
+      expect(() => register("attributeValue", { key: "", value: "Happy birthday!" })).toThrow(
+        /non-empty "key"/,
+      );
+    });
+
     it("sellingPlanId returns name and value", () => {
       const result = register("sellingPlanId", {
         value: "gid://shopify/SellingPlan/1",
diff --git a/packages/hydrogen/src/core/cart/form.ts b/packages/hydrogen/src/core/cart/form.ts
index 38dd66a2e5..ac488b957d 100644
--- a/packages/hydrogen/src/core/cart/form.ts
+++ b/packages/hydrogen/src/core/cart/form.ts
@@ -15,6 +15,8 @@ export interface QuantityInputAttributes {
   autoCorrect: "off";
 }
 
+type AttributeValueName = `attributes.${string}`;
+
 export type CartFormRegister = {
   (field: "lineId", opts: { value: string }): { name: "lineId"; value: string; readOnly: true };
   (field: "quantity", opts: { value: number | string; interactive: true }): QuantityInputAttributes;
@@ -31,12 +33,14 @@ export type CartFormRegister = {
   (field: "merchandiseId", opts: { value: string }): { name: "merchandiseId"; value: string };
   (field: "note", opts: { value: string }): { name: "note"; value: string };
   (field: "note", opts: { defaultValue: string }): { name: "note"; defaultValue: string };
-  (field: "attributeKey", opts: { value: string }): { name: "attributeKey"; value: string };
-  (field: "attributeValue", opts: { value: string }): { name: "attributeValue"; value: string };
   (
     field: "attributeValue",
-    opts: { defaultValue: string },
-  ): { name: "attributeValue"; defaultValue: string };
+    opts: { key: string; value: string },
+  ): { name: AttributeValueName; value: string };
+  (
+    field: "attributeValue",
+    opts: { key: string; defaultValue: string },
+  ): { name: AttributeValueName; defaultValue: string };
   (field: "sellingPlanId", opts: { value: string }): { name: "sellingPlanId"; value: string };
   (action: "add"): { name: "intent"; value: "add" };
   (action: "increase"): { name: "intent"; value: "increase" };
@@ -55,41 +59,70 @@ const FIELD_REGISTERS = new Set([
   "discountCode",
   "merchandiseId",
   "note",
-  "attributeKey",
-  "attributeValue",
   "sellingPlanId",
 ]);
 
+const ATTRIBUTE_VALUE_NAME_PREFIX = "attributes.";
+
+type RegisterOptions = {
+  key?: string;
+  value?: string | number;
+  defaultValue?: string;
+  interactive?: boolean;
+};
+
+export function getCartAttributeFormEntries(
+  formData: FormData,
+): Array<{ key: string; value: FormDataEntryValue }> {
+  const attributes: Array<{ key: string; value: FormDataEntryValue }> = [];
+  for (const [name, value] of formData.entries()) {
+    if (!name.startsWith(ATTRIBUTE_VALUE_NAME_PREFIX)) continue;
+    attributes.push({ key: name.slice(ATTRIBUTE_VALUE_NAME_PREFIX.length), value });
+  }
+  return attributes;
+}
+
+function createAttributeValueAttributes(opts?: RegisterOptions) {
+  if (!opts?.key) throw new TypeError('Cart attribute values require a non-empty "key".');
+  const name = `${ATTRIBUTE_VALUE_NAME_PREFIX}${opts.key}` as AttributeValueName;
+  if ("defaultValue" in opts) {
+    return { name, defaultValue: String(opts.defaultValue) };
+  }
+  return { name, value: String(opts.value ?? "") };
+}
+
+function createFieldAttributes(name: string, opts?: RegisterOptions) {
+  if (opts && "defaultValue" in opts) {
+    return { name, defaultValue: String(opts.defaultValue) };
+  }
+
+  const value = String(opts?.value ?? "");
+
+  if (name === "quantity" && opts?.interactive) {
+    return {
+      name: "quantity",
+      value,
+      type: "text",
+      inputMode: "numeric",
+      pattern: "\\d+",
+      autoComplete: "off",
+      autoCorrect: "off",
+    } satisfies QuantityInputAttributes;
+  }
+
+  const attrs: Record<string, string | boolean> = { name, value };
+  if (name === "lineId") attrs.readOnly = true;
+  return attrs;
+}
+
 export function createCartFormRegister(): CartFormRegister {
-  return ((
-    nameOrAction: string,
-    opts?: { value?: string | number; defaultValue?: string; interactive?: boolean },
-  ) => {
+  return ((nameOrAction: string, opts?: RegisterOptions) => {
+    if (nameOrAction === "attributeValue") {
+      return createAttributeValueAttributes(opts);
+    }
+
     if (FIELD_REGISTERS.has(nameOrAction)) {
-      if (opts && "defaultValue" in opts) {
-        return { name: nameOrAction, defaultValue: String(opts.defaultValue) };
-      }
-
-      const value = String(opts?.value ?? "");
-
-      if (nameOrAction === "quantity" && opts?.interactive) {
-        return {
-          name: "quantity",
-          value,
-          type: "text",
-          inputMode: "numeric",
-          pattern: "\\d+",
-          autoComplete: "off",
-          autoCorrect: "off",
-        } satisfies QuantityInputAttributes;
-      }
-
-      const attrs: Record<string, string | boolean> = {
-        name: nameOrAction,
-        value,
-      };
-      if (nameOrAction === "lineId") attrs.readOnly = true;
-      return attrs;
+      return createFieldAttributes(nameOrAction, opts);
     }
 
     if (nameOrAction === "set") {
diff --git a/packages/hydrogen/src/core/cart/index.ts b/packages/hydrogen/src/core/cart/index.ts
index c2f55e280b..d4fc4963e8 100644
--- a/packages/hydrogen/src/core/cart/index.ts
+++ b/packages/hydrogen/src/core/cart/index.ts
@@ -32,6 +32,7 @@ export type {
   CartLineMerchandise,
   CartCost,
   DiscountCode,
+  Attribute,
 } from "./state";
 export {
   EMPTY_CART_DATA,
diff --git a/packages/hydrogen/src/core/cart/queries.ts b/packages/hydrogen/src/core/cart/queries.ts
index 0de4d306f6..9fd593fabe 100644
--- a/packages/hydrogen/src/core/cart/queries.ts
+++ b/packages/hydrogen/src/core/cart/queries.ts
@@ -29,6 +29,10 @@ const HYDROGEN_CART_FRAGMENT = gql(`
     checkoutUrl
     totalQuantity
     note
+    attributes {
+      key
+      value
+    }
     cost {
       subtotalAmount {
         amount
@@ -257,6 +261,28 @@ const CART_NOTE_UPDATE_MUTATION = gql(
   [HYDROGEN_CART_FRAGMENT],
 );
 
+const CART_ATTRIBUTES_UPDATE_MUTATION = gql(
+  `mutation CartAttributesUpdate($cartId: ID!, $attributes: [AttributeInput!]!, $country: CountryCode, $language: LanguageCode)
+  @inContext(country: $country, language: $language) {
+    cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
+      cart {
+        ...HydrogenCartFragment
+      }
+      userErrors {
+        code
+        field
+        message
+      }
+      warnings {
+        code
+        message
+        target
+      }
+    }
+  }`,
+  [HYDROGEN_CART_FRAGMENT],
+);
+
 // The custom variants spread the consumer's `CartFragment`, which only exists
 // at runtime. Its spread is interpolated on purpose: the gql.tada plugin skips
 // documents containing interpolations instead of flagging an unknown fragment,
@@ -411,6 +437,29 @@ const CUSTOM_CART_NOTE_UPDATE_MUTATION = gql(
   [HYDROGEN_CART_FRAGMENT],
 );
 
+const CUSTOM_CART_ATTRIBUTES_UPDATE_MUTATION = gql(
+  `mutation CartAttributesUpdate($cartId: ID!, $attributes: [AttributeInput!]!, $country: CountryCode, $language: LanguageCode)
+  @inContext(country: $country, language: $language) {
+    cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
+      cart {
+        ...HydrogenCartFragment
+        ...${CART_FRAGMENT_NAME}
+      }
+      userErrors {
+        code
+        field
+        message
+      }
+      warnings {
+        code
+        message
+        target
+      }
+    }
+  }`,
+  [HYDROGEN_CART_FRAGMENT],
+);
+
 const DEFAULT_CART_QUERIES = {
   cart: CART_QUERY,
   cartCreate: CART_CREATE_MUTATION,
@@ -419,6 +468,7 @@ const DEFAULT_CART_QUERIES = {
   cartLinesRemove: CART_LINES_REMOVE_MUTATION,
   cartDiscountCodesUpdate: CART_DISCOUNT_CODES_UPDATE_MUTATION,
   cartNoteUpdate: CART_NOTE_UPDATE_MUTATION,
+  cartAttributesUpdate: CART_ATTRIBUTES_UPDATE_MUTATION,
 } as const;
 
 type DefaultCartQueries = typeof DEFAULT_CART_QUERIES;
@@ -451,6 +501,10 @@ type CartQueriesForFragment<TCartFragment extends CartFragmentDocument> = {
     TCartFragment
   >;
   readonly cartNoteUpdate: CustomQueryFor<typeof CUSTOM_CART_NOTE_UPDATE_MUTATION, TCartFragment>;
+  readonly cartAttributesUpdate: CustomQueryFor<
+    typeof CUSTOM_CART_ATTRIBUTES_UPDATE_MUTATION,
+    TCartFragment
+  >;
 };
 
 type CartDataFromCartQuery<TQuery extends AnyStorefrontQueryString> =
@@ -528,6 +582,8 @@ function createCartQueries<const TCartFragment extends CartFragmentDocument>(
 
   const cartNoteUpdate = gql(CUSTOM_CART_NOTE_UPDATE_MUTATION, fragments);
 
+  const cartAttributesUpdate = gql(CUSTOM_CART_ATTRIBUTES_UPDATE_MUTATION, fragments);
+
   return {
     cart,
     cartCreate,
@@ -536,6 +592,7 @@ function createCartQueries<const TCartFragment extends CartFragmentDocument>(
     cartLinesRemove,
     cartDiscountCodesUpdate,
     cartNoteUpdate,
+    cartAttributesUpdate,
   } as const;
 }
 
diff --git a/packages/hydrogen/src/core/cart/state.ts b/packages/hydrogen/src/core/cart/state.ts
index 3138b600a2..da0237ed74 100644
--- a/packages/hydrogen/src/core/cart/state.ts
+++ b/packages/hydrogen/src/core/cart/state.ts
@@ -133,7 +133,13 @@ export interface CartState<TData extends CartData = CartData> {
 }
 
 export function createEmptyPending(): CartPending {
-  return { lines: new Set(), note: false, attributes: false, discountCodes: new Set(), cost: false };
+  return {
+    lines: new Set(),
+    note: false,
+    attributes: false,
+    discountCodes: new Set(),
+    cost: false,
+  };
 }
 
 export function createEmptyErrorGroup(): CartErrorGroup {
diff --git a/packages/hydrogen/src/react/cart.test.tsx b/packages/hydrogen/src/react/cart.test.tsx
index edf60999be..54e1477e91 100644
--- a/packages/hydrogen/src/react/cart.test.tsx
+++ b/packages/hydrogen/src/react/cart.test.tsx
@@ -722,7 +722,13 @@ describe("useCart pending state", () => {
     const mockStore = createMockStore();
     mockStore.setState(
       makeCartState({
-        pending: { lines: new Set(), note: false, discountCodes: new Set(), cost: true },
+        pending: {
+          lines: new Set(),
+          note: false,
+          attributes: false,
+          discountCodes: new Set(),
+          cost: true,
+        },
       }),
     );
     vi.mocked(createCartStore).mockImplementation(() => mockStore);