@replohq/sdk 1.12.0 → 1.13.0

package/cart/cart-actions.d.ts

@@ -1,5 +1,5 @@
 import type { StorefrontCountryCode } from "../loaders/markets";
-import type { AddToCartPayload, Cart, CartLinePayload, RemoveFromCartPayload, UpdateCartLineItemPayload } from "./cart-types";
+import type { AddToCartPayload, Cart, CartLineAttribute, CartLinePayload, RemoveFromCartPayload, UpdateCartLineItemPayload } from "./cart-types";
 /**
  * Gets the existing cart or creates a new one if none exists. This is necessary
  * because we may not have cookies in the server context during initial load.
@@ -73,3 +73,19 @@ export declare function removeCartLineItemsAction(lineIds: RemoveFromCartPayload
  * @returns The updated cart
  */
 export declare function updateCartDiscountCodesAction(discountCodes: string[], cartId: string): Promise<Cart | null>;
+/**
+ * Sets the order-level note on a cart. Pass an empty string to clear it.
+ *
+ * @param note - The note text
+ * @param cartId - The ID of the cart to update
+ * @returns The updated cart
+ */
+export declare function updateCartNoteAction(note: string, cartId: string): Promise<Cart | null>;
+/**
+ * Replaces the order-level attributes on a cart.
+ *
+ * @param attributes - The full attribute list to store on the cart
+ * @param cartId - The ID of the cart to update
+ * @returns The updated cart
+ */
+export declare function replaceCartAttributesAction(attributes: CartLineAttribute[], cartId: string): Promise<Cart | null>;

package/cart/cart-actions.js

@@ -108,6 +108,14 @@ async function updateCartDiscountCodesAction(discountCodes, cartId) {
   const cartGateway = await getCartGateway();
   return await cartGateway.updateCartDiscountCodes({ discountCodes, cartId });
 }
+async function updateCartNoteAction(note, cartId) {
+  const cartGateway = await getCartGateway();
+  return await cartGateway.updateCartNote({ note, cartId });
+}
+async function replaceCartAttributesAction(attributes, cartId) {
+  const cartGateway = await getCartGateway();
+  return await cartGateway.replaceCartAttributes({ attributes, cartId });
+}
 export {
   addToCartAction,
   createCartAction,
@@ -115,6 +123,8 @@ export {
   getOrCreateCartAction,
   reconcileCartAction,
   removeCartLineItemsAction,
+  replaceCartAttributesAction,
   updateCartDiscountCodesAction,
-  updateCartLineItemAction
+  updateCartLineItemAction,
+  updateCartNoteAction
 };

package/cart/cart-provider.d.ts

@@ -1,7 +1,7 @@
 import type { StorefrontCountryCode } from "../loaders/markets";
-import type { Cart, CartLine, CartLineAdjustment, CartLinePayload } from "./cart-types";
+import type { Cart, CartLine, CartLineAdjustment, CartLineAttribute, CartLinePayload } from "./cart-types";
 import React from "react";
-export type CartOperation = "add" | "update" | "remove" | "discount";
+export type CartOperation = "add" | "update" | "remove" | "discount" | "note" | "attributes";
 /**
  * The most recent cart change that could not be saved. `message` is written
  * for the shopper, so a cart UI can render it as-is next to a retry.
@@ -39,6 +39,10 @@ export interface CartContextTypeInternal {
     removeCartItem: (lineId: string) => Promise<void>;
     /** Function to update discount codes on cart */
     updateDiscountCodes: (discountCodes: string[]) => Promise<void>;
+    /** Function to set the order-level cart note (empty string clears it) */
+    updateNote: (note: string) => Promise<void>;
+    /** Function to replace the order-level cart attributes */
+    replaceAttributes: (attributes: CartLineAttribute[]) => Promise<void>;
     /** Re-read the persisted cart and adopt it if no mutations are in flight */
     refreshCart: () => Promise<void>;
     /** Function to create cart and checkout immediately */
@@ -72,6 +76,24 @@ export interface CartContextType {
     closeCart: () => void;
     /** Function to update discount codes on cart */
     updateDiscountCodes: (discountCodes: string[]) => Promise<void>;
+    /**
+     * Set the order-level cart note (Shopify `cart.note`, the "special
+     * instructions" field on the order). Pass an empty string to clear it.
+     * Each call is one Shopify mutation: save on blur or after the shopper
+     * stops typing, never on every keystroke. Shopify checkout only; on Replo
+     * Products (Stripe) sites the note is kept on the cart but is not
+     * forwarded to the order.
+     */
+    updateNote: (note: string) => Promise<void>;
+    /**
+     * Replace the order-level cart attributes (Shopify `cart.attributes`), the
+     * key/value pairs gift-message and fulfillment apps read off the order.
+     * These are distinct from per-line `properties`. The full list is replaced
+     * on every call, so a key left out is removed; values are stored as
+     * strings. Shopify checkout only; on Replo Products (Stripe) sites the
+     * attributes are kept on the cart but are not forwarded to the order.
+     */
+    replaceAttributes: (attributes: CartLineAttribute[]) => Promise<void>;
     /**
      * Re-read the persisted cart and adopt it if no mutations are in flight.
      * Call after something outside the provider rewrote the cart — e.g. the

package/cart/cart-provider.js

@@ -10,8 +10,10 @@ import {
   getOrCreateCartAction,
   reconcileCartAction,
   removeCartLineItemsAction,
+  replaceCartAttributesAction,
   updateCartDiscountCodesAction,
-  updateCartLineItemAction
+  updateCartLineItemAction,
+  updateCartNoteAction
 } from "./cart-actions";
 import { CartCountryContext } from "./cart-country-context";
 import { useShouldReconcileSuppliedCart } from "./supplied-cart-reconciliation";
@@ -487,22 +489,15 @@ function CartProvider({
       updateCartData
     ]
   );
-  const updateDiscountCodes = React.useCallback(
-    (discountCodes) => {
-      return runWithErrorState("discount", async () => {
+  const updateCartField = React.useCallback(
+    (operation, patch, save) => {
+      return runWithErrorState(operation, async () => {
         const readyCart = cartData ?? serverCart.current ?? await initializeCart();
-        updateCartData((currentCart) => {
-          return {
-            ...currentCart ?? readyCart,
-            discountCodes: discountCodes.map((code) => ({
-              code,
-              applicable: true
-            }))
-          };
-        });
-        await enqueueMutation((currentCart) => {
-          return updateCartDiscountCodesAction(discountCodes, currentCart.id);
-        });
+        updateCartData((currentCart) => ({
+          ...currentCart ?? readyCart,
+          ...patch
+        }));
+        await enqueueMutation((currentCart) => save(currentCart.id));
       });
     },
     [
@@ -513,6 +508,43 @@ function CartProvider({
       updateCartData
     ]
   );
+  const updateDiscountCodes = React.useCallback(
+    (discountCodes) => {
+      return updateCartField(
+        "discount",
+        {
+          discountCodes: discountCodes.map((code) => ({
+            code,
+            applicable: true
+          }))
+        },
+        (cartId) => updateCartDiscountCodesAction(discountCodes, cartId)
+      );
+    },
+    [updateCartField]
+  );
+  const updateNote = React.useCallback(
+    (note) => {
+      return updateCartField("note", { note }, (cartId) => {
+        return updateCartNoteAction(note, cartId);
+      });
+    },
+    [updateCartField]
+  );
+  const replaceAttributes = React.useCallback(
+    (attributes) => {
+      const stringAttributes = attributes.map((attribute) => ({
+        key: attribute.key,
+        value: String(attribute.value)
+      }));
+      return updateCartField(
+        "attributes",
+        { attributes: stringAttributes },
+        (cartId) => replaceCartAttributesAction(stringAttributes, cartId)
+      );
+    },
+    [updateCartField]
+  );
   const buyNow = React.useCallback(
     (lines, discountCodes) => {
       return createBuyNowCart({ lines, discountCodes, country });
@@ -530,6 +562,8 @@ function CartProvider({
       updateCartItem,
       removeCartItem,
       updateDiscountCodes,
+      updateNote,
+      replaceAttributes,
       refreshCart,
       buyNow,
       checkoutUrl: cartData?.checkoutUrl ?? "/",
@@ -552,8 +586,10 @@ function CartProvider({
       refreshCart,
       removeCartItem,
       subtotal,
+      replaceAttributes,
       updateCartItem,
-      updateDiscountCodes
+      updateDiscountCodes,
+      updateNote
     ]
   );
   return /* @__PURE__ */ jsx(CartCountryContext.Provider, { value: country, children: /* @__PURE__ */ jsx(CartContext.Provider, { value: contextValue, children }) });
@@ -580,6 +616,8 @@ function useCart() {
     openCart: context.openCart,
     closeCart: context.closeCart,
     updateDiscountCodes: context.updateDiscountCodes,
+    updateNote: context.updateNote,
+    replaceAttributes: context.replaceAttributes,
     refreshCart: context.refreshCart,
     error: context.error,
     clearError: context.clearError

package/cart/cart-schema.d.ts

@@ -77,6 +77,11 @@ export declare const cartSchema: z.ZodObject<{
     buyerIdentity: z.ZodOptional<z.ZodObject<{
         country: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
+    note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const clientCartSchema: z.ZodObject<{
     id: z.ZodString;
@@ -97,6 +102,11 @@ export declare const clientCartSchema: z.ZodObject<{
     buyerIdentity: z.ZodOptional<z.ZodObject<{
         country: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
+    note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attributes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>>>;
     lines: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         quantity: z.ZodNumber;

package/cart/cart-schema.js

@@ -67,7 +67,9 @@ const cartSchema = z.object({
   checkoutUrl: z.string().optional(),
   discountCodes: z.array(cartDiscountCodeSchema).optional(),
   discountAllocations: z.array(cartDiscountAllocationSchema).optional(),
-  buyerIdentity: z.object({ country: z.string().nullable() }).optional()
+  buyerIdentity: z.object({ country: z.string().nullable() }).optional(),
+  note: z.string().nullish(),
+  attributes: z.array(cartLineAttributeSchema).optional()
 });
 const clientCartSchema = cartSchema.extend({
   lines: z.array(

package/cart/cart-types.d.ts

@@ -127,6 +127,10 @@ export interface Cart {
     buyerIdentity?: {
         country: string | null;
     };
+    /** Order-level note the shopper attached to the cart (Shopify `cart.note`) */
+    note?: string | null;
+    /** Order-level attributes (Shopify `cart.attributes`), distinct from line properties */
+    attributes?: CartLineAttribute[];
 }
 /**
  * How a cart write differed from what the shopper asked for, derived by
@@ -166,6 +170,14 @@ export interface UpdateCartDiscountCodesPayload {
     cartId: string;
     discountCodes: string[];
 }
+export interface UpdateCartNotePayload {
+    cartId: string;
+    note: string;
+}
+export interface ReplaceCartAttributesPayload {
+    cartId: string;
+    attributes: CartLineAttribute[];
+}
 export interface CartBuyerIdentity {
     country: StorefrontCountryCode;
 }

package/cart/gateways/cart-gateway.d.ts

@@ -1,4 +1,4 @@
-import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload } from "../cart-types";
+import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, ReplaceCartAttributesPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload, UpdateCartNotePayload } from "../cart-types";
 export interface CartGateway {
     getCart(cartId: string): Promise<Cart | null>;
     /**
@@ -21,5 +21,7 @@ export interface CartGateway {
     updateCartLineItem(cartPayload: UpdateCartLineItemPayload): Promise<Cart | null>;
     removeCartLineItems(cartPayload: RemoveFromCartPayload): Promise<Cart | null>;
     updateCartDiscountCodes(cartPayload: UpdateCartDiscountCodesPayload): Promise<Cart | null>;
+    updateCartNote(cartPayload: UpdateCartNotePayload): Promise<Cart | null>;
+    replaceCartAttributes(cartPayload: ReplaceCartAttributesPayload): Promise<Cart | null>;
 }
 export declare function getCartGateway(): Promise<CartGateway>;

package/cart/gateways/cookie-cart-gateway.d.ts

@@ -1,5 +1,5 @@
 import type { ReconciledCartLine } from "../../gateways/canopy-api";
-import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload } from "../cart-types";
+import type { AddToCartPayload, Cart, CartBuyerIdentity, CartLinePayload, RemoveFromCartPayload, ReplaceCartAttributesPayload, UpdateCartDiscountCodesPayload, UpdateCartLineItemPayload, UpdateCartNotePayload } from "../cart-types";
 import type { LineMergeFn } from "../utils/cookie-cart-persistence";
 import type { CartGateway } from "./cart-gateway";
 /**
@@ -41,5 +41,8 @@ export declare abstract class CookieBasedCartGateway implements CartGateway {
         cartId: string;
         buyerIdentity: CartBuyerIdentity;
     }): Promise<Cart | null>;
+    updateCartNote({ cartId, note, }: UpdateCartNotePayload): Promise<Cart | null>;
+    replaceCartAttributes({ cartId, attributes, }: ReplaceCartAttributesPayload): Promise<Cart | null>;
+    private patchCart;
 }
 export {};

package/cart/gateways/cookie-cart-gateway.js

@@ -5,6 +5,7 @@ import {
   loadCartFromCookie,
   removeCartLineItemsWithPersistence,
   saveCartToCookie,
+  updateCartInCookie,
   updateCartLineItemWithPersistence
 } from "../utils/cookie-cart-persistence";
 class CookieBasedCartGateway {
@@ -156,6 +157,45 @@ class CookieBasedCartGateway {
   }) {
     return this.getCart(cartId);
   }
+  async updateCartNote({
+    cartId,
+    note
+  }) {
+    return this.patchCart(cartId, { note });
+  }
+  async replaceCartAttributes({
+    cartId,
+    attributes
+  }) {
+    return this.patchCart(cartId, {
+      attributes: attributes.map((attribute) => ({
+        key: attribute.key,
+        value: String(attribute.value)
+      }))
+    });
+  }
+  async patchCart(cartId, patch) {
+    console.warn(
+      `${this.config.gatewayName} cart gateway keeps cart note/attributes on the cart but does not forward them to checkout`
+    );
+    try {
+      return await updateCartInCookie(
+        cartId,
+        this.config.cookieName,
+        (cart) => ({
+          ...cart,
+          ...patch
+        })
+      );
+    } catch (error) {
+      console.warn(`Failed to update ${this.config.gatewayName} cart:`, {
+        error: error instanceof Error ? error.message : String(error),
+        cartId,
+        patch
+      });
+      return null;
+    }
+  }
 }
 export {
   CookieBasedCartGateway

package/cart/gateways/resolver-cart-gateway.js

@@ -117,6 +117,33 @@ class ResolverCartGateway {
       return null;
     }
   }
+  async updateCartNote(cartPayload) {
+    try {
+      const gateway = await getCanopyApiGateway();
+      return await gateway.cartUpdateNote({
+        cartId: cartPayload.cartId,
+        note: cartPayload.note
+      });
+    } catch (error) {
+      console.warn("Failed to update cart note via canopy-api:", error);
+      return null;
+    }
+  }
+  async replaceCartAttributes(cartPayload) {
+    try {
+      const gateway = await getCanopyApiGateway();
+      return await gateway.cartReplaceAttributes({
+        cartId: cartPayload.cartId,
+        attributes: cartPayload.attributes.map((attribute) => ({
+          key: attribute.key,
+          value: String(attribute.value)
+        }))
+      });
+    } catch (error) {
+      console.warn("Failed to update cart attributes via canopy-api:", error);
+      return null;
+    }
+  }
 }
 async function createResolverCartGateway() {
   return new ResolverCartGateway();

package/cart/utils/cart-error.js

@@ -5,7 +5,9 @@ const FALLBACK_MESSAGES = {
   add: "Could not add to your cart. Please try again.",
   update: "Could not update your cart. Please try again.",
   remove: "Could not remove that item. Please try again.",
-  discount: "Could not apply that discount. Please try again."
+  discount: "Could not apply that discount. Please try again.",
+  note: "Could not save your note. Please try again.",
+  attributes: "Could not save your cart details. Please try again."
 };
 function toCartError(operation, caught) {
   return {

package/gateways/canopy-api.d.ts

@@ -110,6 +110,17 @@ declare class CanopyApiGateway {
         cartId: string;
         country: StorefrontCountryCode;
     }): Promise<Cart>;
+    cartUpdateNote({ cartId, note, }: {
+        cartId: string;
+        note: string;
+    }): Promise<Cart>;
+    cartReplaceAttributes({ cartId, attributes, }: {
+        cartId: string;
+        attributes: {
+            key: string;
+            value: string;
+        }[];
+    }): Promise<Cart>;
 }
 export declare function getCanopyApiGateway(): Promise<CanopyApiGateway>;
 export {};

package/gateways/canopy-api.js

@@ -228,6 +228,18 @@ If you're running locally, make sure the canopy-api cloudflare worker is running
   }) {
     return this._cartPost("/update-buyer-identity", { cartId, country });
   }
+  async cartUpdateNote({
+    cartId,
+    note
+  }) {
+    return this._cartPost("/update-note", { cartId, note });
+  }
+  async cartReplaceAttributes({
+    cartId,
+    attributes
+  }) {
+    return this._cartPost("/replace-attributes", { cartId, attributes });
+  }
 }
 async function getCanopyApiGateway() {
   return CanopyApiGateway.setup();

package/lib/buildMetadata.js

@@ -1,7 +1,7 @@
 export const BUILD_METADATA = {
   "packageName": "@replohq/sdk",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "branch": "HEAD",
-  "commit": "3d57d078085b1361b40fd9feb54651a1fca5a985",
-  "builtAt": "2026-09-22T02:12:30.362Z"
+  "commit": "55186f7cb6b1441e4d471b2d954118f3d11767ae",
+  "builtAt": "2026-09-22T17:30:33.714Z"
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@replohq/sdk",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "reploBuild": {
     "packageName": "@replohq/sdk",
-    "version": "1.12.0",
+    "version": "1.13.0",
     "branch": "HEAD",
-    "commit": "3d57d078085b1361b40fd9feb54651a1fca5a985",
-    "builtAt": "2026-09-22T02:12:30.362Z"
+    "commit": "55186f7cb6b1441e4d471b2d954118f3d11767ae",
+    "builtAt": "2026-09-22T17:30:33.714Z"
   },
   "description": "Replo SDK — cart, analytics, and data loaders for agent-built Next.js sites.",
   "license": "SEE LICENSE IN LICENSE",