@osimart/create-storefront 1.0.20 → 1.0.21

package/app/composables/useAddToCart.js

@@ -2,12 +2,14 @@ import CartServices from "#osi/services/CartServices";
 import { useToast } from "vue-toastification";
 import { useCart } from "./useCart";
 import { useSidebar } from "./useSidebar";
+import { isCustomizationError, needsPersonalization } from "./useProductCustomization";
 
 export function useAddToCart() {
   const router = useRouter();
-  const { fetchCart } = useCart();
+  const { apply: applyCart } = useCart();
   const { toggleCartSidebar } = useSidebar();
   const { cartType } = useStorefront();
+  const { productUrl } = useProductUrl();
 
   function openCartUi() {
     if (cartType.value === "PAGE") {
@@ -38,10 +40,12 @@ export function useAddToCart() {
       return;
     }
 
-    // If product has multiple variants, redirect to detail page
-    if (Array.isArray(product.product_variants) && product.product_variants.length > 1) {
-      const categorySlug = product.categories?.[0]?.category?.slugified_name || 'products';
-      router.push(`/${categorySlug}/${product.slugified_name}/`);
+    // Multiple variants, or a required personalization: picked on the product page.
+    if (
+      (Array.isArray(product.product_variants) && product.product_variants.length > 1) ||
+      needsPersonalization(product)
+    ) {
+      router.push(productUrl(product));
       return;
     }
 
@@ -58,10 +62,16 @@ export function useAddToCart() {
         variant: product.product_variants?.[0],
       });
       if (response) {
-        await fetchCart();
+        // The add already returned the whole cart.
+        applyCart(response);
         openCartUi();
       }
     } catch (error) {
+      // 400 { properties }: required personalization the list didn't know about.
+      if (isCustomizationError(error)) {
+        router.push(productUrl(product));
+        return;
+      }
       console.error("[useAddToCart] Error adding to cart:", error);
       try {
         const toast = useToast();

package/app/composables/useCart.js

@@ -1,10 +1,16 @@
-import CartServices from "#osi/services/CartServices";
+import CartServices, { cartLines } from "#osi/services/CartServices";
 import { clearCartToken } from "#osi/services/CartToken";
 
+/** A line's identity. Lines are keyed by order_item_id; `id` is the variant. */
+export const lineKey = (item) => String(item?.order_item_id ?? item ?? "");
+
 export function useCart() {
   // The raw server payload. Checkout needs it to build its order lines, so
   // it's kept rather than discarded after mapping.
   const cart = useState("cart-raw", () => null);
+  // Every line, add-ons included. Each has `order_item_id` (the line),
+  // `id` (the variant), `parent_item` (the parent line for an add-on, else
+  // null), `properties` (customization answers) and `customization_price`.
   const cartItems = useState("cart-items", () => []);
   const cartTotal = useState("cart-total", () => 0);
   const loading = useState("cart-loading", () => false);
@@ -18,22 +24,37 @@ export function useCart() {
     if (!response) return response;
     cart.value = response;
     cartTotal.value = response.total_price || 0;
-    cartItems.value = Object.entries(response.cart || {}).map(([id, item]) => ({
-      id,
-      ...item,
-    }));
+    cartItems.value = cartLines(response);
     return response;
   }
 
-  const isUpdating = (item) => {
-    const id = item?.id ?? item;
-    return updatingIds.value.includes(id);
-  };
+  /** Lines the shopper controls: products, not the add-ons hanging off them. */
+  const topLevelItems = computed(() => cartItems.value.filter((item) => !item.parent_item));
+
+  /** Add-on lines (gift wrap, box…) of one line. */
+  const childrenOf = (item) =>
+    cartItems.value.filter((child) => child.parent_item && String(child.parent_item) === lineKey(item));
+
+  /**
+   * Parents each followed by their add-ons — the order every cart list renders
+   * in. An add-on whose parent is missing (shouldn't happen) goes last rather
+   * than disappearing.
+   */
+  const orderedItems = computed(() => {
+    const parents = topLevelItems.value;
+    const parentKeys = new Set(parents.map(lineKey));
+    return [
+      ...parents.flatMap((parent) => [parent, ...childrenOf(parent)]),
+      ...cartItems.value.filter((item) => item.parent_item && !parentKeys.has(String(item.parent_item))),
+    ];
+  });
 
-  function markUpdating(id, busy) {
+  const isUpdating = (item) => updatingIds.value.includes(lineKey(item));
+
+  function markUpdating(key, busy) {
     updatingIds.value = busy
-      ? [...updatingIds.value, id]
-      : updatingIds.value.filter((existing) => existing !== id);
+      ? [...updatingIds.value, key]
+      : updatingIds.value.filter((existing) => existing !== key);
   }
 
   async function fetchCart() {
@@ -49,29 +70,44 @@ export function useCart() {
   }
 
   /**
-   * Add or remove quantity on one line. Per-line busy state, not a single
+   * Change one line, by its order_item_id. Per-line busy state, not a single
    * global flag — one slow line shouldn't freeze the controls on the others.
    *
+   *   edit        quantity = the line's new quantity
+   *   remove      quantity = how many to take off
+   *   remove_all  deletes the line (and its add-ons, server-side)
+   *
+   * Add-on lines are ignored: they follow their parent.
+   *
    * Throws on failure so the caller can decide how to surface it (the drawer
    * has useApiErrorToast, checkout has its own extractErrorMessage).
    */
   async function editItem(item, action, quantity) {
-    const id = item?.id ?? item;
-    if (!id || isUpdating(id)) return null;
+    const key = lineKey(item);
+    if (!item?.order_item_id || item.parent_item || isUpdating(key)) return null;
 
-    const step = quantity ?? item?.quantity_step ?? 1;
-    markUpdating(id, true);
+    markUpdating(key, true);
     try {
-      return apply(await CartServices.EditCart(id, step, action));
+      return apply(await CartServices.editLine(item, action, quantity));
     } finally {
-      markUpdating(id, false);
+      markUpdating(key, false);
     }
   }
 
-  const increaseItem = (item) => editItem(item, "add");
-  const decreaseItem = (item) => editItem(item, "remove");
-  // Remove is a decrease by the full quantity — the API has no delete verb.
-  const removeItem = (item) => editItem(item, "remove", item?.quantity);
+  const step = (item) => Number(item?.quantity_step) || 1;
+
+  // "add" with a variant id would add a new plain line (no customization),
+  // so increasing a line sets its quantity instead.
+  const increaseItem = (item) =>
+    editItem(item, "edit", (Number(item?.quantity) || 0) + step(item));
+  const decreaseItem = (item) => editItem(item, "remove", step(item));
+  const removeItem = (item) => editItem(item, "remove_all");
+
+  /** How many of a variant the shopper has, across all its lines. */
+  const quantityOf = (variantId) =>
+    topLevelItems.value
+      .filter((item) => String(item.id) === String(variantId))
+      .reduce((total, item) => total + (Number(item.quantity) || 0), 0);
 
   /**
    * Call only once the server has confirmed there's nothing left to pay. The
@@ -87,17 +123,22 @@ export function useCart() {
     updatingIds.value = [];
   }
 
+  // Header badge: products the shopper picked, not their add-on lines.
   const count = computed(() =>
-    cartItems.value.reduce((total, item) => total + (item.quantity || 0), 0),
+    topLevelItems.value.reduce((total, item) => total + (Number(item.quantity) || 0), 0),
   );
 
   return {
     cart,
     cartItems,
+    topLevelItems,
+    orderedItems,
+    childrenOf,
     cartTotal,
     loading,
     count,
     isUpdating,
+    quantityOf,
     fetchCart,
     editItem,
     increaseItem,
@@ -106,4 +147,4 @@ export function useCart() {
     apply,
     clear,
   };
-}
+}

package/app/composables/useCheckout.js

@@ -75,11 +75,14 @@ export function useCheckout() {
   const {
     cart: rawCart,
     cartItems,
+    orderedItems,
+    topLevelItems,
     cartTotal,
     loading: cartLoading,
     isUpdating,
     fetchCart,
-    editItem,
+    increaseItem,
+    decreaseItem,
     removeItem,
   } = useCart();
 
@@ -162,14 +165,23 @@ export function useCheckout() {
   // ================================================================
   // COMPUTED
   // ================================================================
-  // Template keeps its original names.
-  const CartItems = computed(() => cartItems.value);
+  // Template keeps its original names. Every line, each product followed by
+  // its add-on lines (gift wrap…), which render nested with no stepper.
+  const CartItems = computed(() => orderedItems.value);
+  // The products the shopper picked (thumbnails strip, item count).
+  const TopLevelItems = computed(() => topLevelItems.value);
   const total_price = computed(() => cartTotal.value);
 
   const totalItemsCount = computed(() =>
-    CartItems.value.reduce((sum, item) => sum + Number(item.quantity || 0), 0),
+    TopLevelItems.value.reduce((sum, item) => sum + Number(item.quantity || 0), 0),
   );
 
+  // Checkout re-checks each line's customization against the product's
+  // current setup. When the merchant changed it (field made required, option
+  // deleted, add-on changed) placeOrder answers { cart: "The options for X
+  // have changed…" }: shown as a banner that links to the lines.
+  const cartError = ref("");
+
   const isLoading = computed(() => cartLoading.value || needsUserInfo.value);
 
   const selectedAddress = computed(() =>
@@ -299,13 +311,26 @@ export function useCheckout() {
       toast.error(extractErrorMessage(error));
     }
   }
+  // Each targets one line by order_item_id; add-on lines are never edited
+  // directly (useCart ignores them, the template offers no controls).
   const increaseQuantity = (item) =>
-    mutateCart(() => editItem(item, "add"), "Error adding to cart:");
+    mutateCart(() => increaseItem(item), "Error adding to cart:");
   const decreaseQuantity = (item) =>
-    mutateCart(() => editItem(item, "remove"), "Error decreasing quantity:");
+    mutateCart(() => decreaseItem(item), "Error decreasing quantity:");
   const deleteItem = (item) =>
     mutateCart(() => removeItem(item), "Error removing from cart:");
 
+  /** "Review cart" on the banner: bring the line items into view. */
+  function reviewCart() {
+    const desktop = typeof window !== "undefined" && window.matchMedia("(min-width: 1024px)").matches;
+    if (!desktop) mobileSummaryOpen.value = true;
+    nextTick(() => {
+      document
+        .querySelector(desktop ? "[data-checkout-lines='rail']" : "[data-checkout-lines='mobile']")
+        ?.scrollIntoView({ behavior: "smooth", block: "center" });
+    });
+  }
+
   // ================================================================
   // REFERENCE DATA
   // ================================================================
@@ -762,6 +787,13 @@ export function useCheckout() {
     } catch (error) {
       console.error("Error placing order:", error);
       if (handleOrderPromoError(error)) return;
+      const data = errorData(error);
+      if (data && typeof data === "object" && !Array.isArray(data) && data.cart) {
+        cartError.value = [].concat(data.cart).join(" ");
+        await nextTick();
+        if (typeof window !== "undefined") window.scrollTo({ top: 0, behavior: "smooth" });
+        return;
+      }
       toast.error(extractErrorMessage(error));
     } finally {
       isCheckingOut.value = false;
@@ -859,6 +891,12 @@ export function useCheckout() {
     refreshFreeDelivery();
   });
 
+  // Any cart change (the shopper removed / re-added the line) clears the
+  // "options have changed" banner; the next attempt re-checks server-side.
+  watch(cartItems, () => {
+    cartError.value = "";
+  });
+
   watch(phoneNumberResults, (results) => {
     if (formErrors.value.mobile_number && results?.isValid) {
       clearFieldError("mobile_number");
@@ -894,12 +932,15 @@ export function useCheckout() {
 
     // cart
     CartItems,
+    TopLevelItems,
     total_price,
     totalItemsCount,
     isItemUpdating,
     increaseQuantity,
     decreaseQuantity,
     deleteItem,
+    cartError,
+    reviewCart,
 
     // user + form
     isLoggedIn,

package/app/composables/useProductCustomization.js

@@ -1,52 +1,93 @@
-import { computed, reactive, watch } from "vue";
+import { computed, nextTick, reactive, watch } from "vue";
 
+// 0 is a valid NUMBER answer, so only null / undefined / false / blank are empty.
 const EMPTY = (value) =>
   value === null || value === undefined || value === false ||
   (typeof value === "string" && value.trim() === "");
 
-/** Product customization answers, scoped to the product and variant shown. */
+const sameId = (a, b) => a != null && b != null && String(a) === String(b);
+
+/**
+ * Product customization answers, scoped to the product and variant shown.
+ *
+ * `product` and `selectedVariant` are refs; the variant is the variant object
+ * (its `id` is checked against each set's excluded_variants).
+ *
+ * The backend validates and prices everything again on add to cart; the
+ * prices here are only a preview.
+ */
 export function useProductCustomization(product, selectedVariant) {
   const values = reactive({});
   const errors = reactive({});
 
+  // A set is hidden for the selected variant when it's in excluded_variants.
+  // No variant picked yet: show every set.
   const visibleSets = computed(() => {
     const variantId = selectedVariant.value?.id;
     return (product.value?.customization_sets || []).filter(
-      (set) => !variantId || !(set.excluded_variants || []).includes(variantId),
+      (set) => variantId == null || !(set.excluded_variants || []).some((id) => sameId(id, variantId)),
     );
   });
   const visibleFields = computed(() =>
     visibleSets.value.flatMap((set) => set.customization_fields || []),
   );
 
+  const hasCustomization = computed(() => visibleFields.value.length > 0);
+  const hasRequired = computed(() =>
+    (product.value?.customization_sets || []).some((set) =>
+      (set.customization_fields || []).some((field) => field.required),
+    ),
+  );
+
+  // A variant change that hides a set drops its answers (and their price);
+  // answers for fields still visible are kept.
   watch(visibleFields, (fields) => {
     const keys = new Set(fields.map((field) => field.key));
     Object.keys(values).forEach((key) => { if (!keys.has(key)) delete values[key]; });
     Object.keys(errors).forEach((key) => { if (!keys.has(key)) delete errors[key]; });
-  });
+  }, { immediate: true });
 
   function optionFor(field) {
-    return field.options?.find((option) => option.id === values[field.key]) || null;
+    return field.options?.find((option) => sameId(option.id, values[field.key])) || null;
   }
 
+  /** What a filled field costs: { delta } on the line, or { addon } as its own line. */
   function costOf(field) {
     if (EMPTY(values[field.key])) return null;
     if (field.type === "SELECT") {
       const option = optionFor(field);
       if (!option) return null;
+      // option.price_delta null means "use the field's price", not 0.
       return option.addon_variant
         ? { addon: option.addon_variant }
-        : { delta: option.price_delta ?? field.price_delta ?? 0 };
+        : { delta: Number(option.price_delta ?? field.price_delta ?? 0) || 0 };
     }
     return field.addon_variant
       ? { addon: field.addon_variant }
-      : { delta: field.price_delta || 0 };
+      : { delta: Number(field.price_delta) || 0 };
   }
 
   const deltaPerUnit = computed(() => visibleFields.value.reduce(
-    (sum, field) => sum + (Number(costOf(field)?.delta) || 0), 0,
+    (sum, field) => sum + (costOf(field)?.delta || 0), 0,
   ));
-  const addons = computed(() => visibleFields.value.map(costOf).filter((cost) => cost?.addon).map((cost) => cost.addon));
+  const addons = computed(() =>
+    visibleFields.value.map(costOf).filter((cost) => cost?.addon).map((cost) => cost.addon),
+  );
+  const addonsPerUnit = computed(() =>
+    addons.value.reduce((sum, addon) => sum + (Number(addon.price) || 0), 0),
+  );
+
+  /** Scroll the first field with an error into view. */
+  function scrollToFirstError() {
+    if (typeof document === "undefined") return;
+    const first = visibleFields.value.find((field) => errors[field.key]);
+    if (!first) return;
+    nextTick(() => {
+      const el = [...document.querySelectorAll(".osi-pdp-customization [data-key]")]
+        .find((node) => node.dataset.key === String(first.key));
+      el?.scrollIntoView({ behavior: "smooth", block: "center" });
+    });
+  }
 
   function validate() {
     Object.keys(errors).forEach((key) => delete errors[key]);
@@ -62,9 +103,12 @@ export function useProductCustomization(product, selectedVariant) {
         errors[field.key] = `${field.label} must be at most ${field.max_length} characters.`;
       }
     }
-    return Object.keys(errors).length === 0;
+    const ok = Object.keys(errors).length === 0;
+    if (!ok) scrollToFirstError();
+    return ok;
   }
 
+  /** Add-to-cart `properties`: filled, visible fields only, keyed by field key. */
   const payload = computed(() => {
     const result = {};
     for (const field of visibleFields.value) {
@@ -72,17 +116,31 @@ export function useProductCustomization(product, selectedVariant) {
       if (EMPTY(value)) continue;
       if (field.type === "CHECKBOX") result[field.key] = true;
       else if (field.type === "NUMBER") result[field.key] = Number(value);
-      else if (field.type === "SELECT") result[field.key] = value;
+      else if (field.type === "SELECT") result[field.key] = value; // the option id, not its text
       else result[field.key] = String(value).trim();
     }
     return result;
   });
 
+  /**
+   * Backend 400 { properties: { key: message } } -> messages under the fields.
+   * Returns false when nothing matched a visible field, so the caller shows
+   * the error some other way.
+   */
   function applyServerErrors(error) {
-    const serverErrors = error?.data?.properties || error?.response?._data?.properties;
+    const data = error?.data ?? error?.response?._data ?? error?.response?.data;
+    const serverErrors = data?.properties;
     if (!serverErrors) return false;
-    Object.assign(errors, serverErrors);
-    return true;
+    if (typeof serverErrors !== "object") return false;
+    const keys = new Set(visibleFields.value.map((field) => field.key));
+    let matched = false;
+    for (const [key, message] of Object.entries(serverErrors)) {
+      if (!keys.has(key)) continue;
+      errors[key] = Array.isArray(message) ? message.join(" ") : String(message);
+      matched = true;
+    }
+    if (matched) scrollToFirstError();
+    return matched;
   }
 
   function reset() {
@@ -90,5 +148,39 @@ export function useProductCustomization(product, selectedVariant) {
     Object.keys(errors).forEach((key) => delete errors[key]);
   }
 
-  return { values, errors, visibleSets, visibleFields, deltaPerUnit, addons, costOf, validate, payload, applyServerErrors, reset };
+  return {
+    values,
+    errors,
+    visibleSets,
+    visibleFields,
+    hasCustomization,
+    hasRequired,
+    deltaPerUnit,
+    addons,
+    addonsPerUnit,
+    costOf,
+    validate,
+    payload,
+    applyServerErrors,
+    scrollToFirstError,
+    reset,
+  };
+}
+
+/**
+ * A product with a required customization field can't be added from a card:
+ * the answers are picked on its page. Lists usually don't carry
+ * `customization_sets`, so this only catches what's known up front; the
+ * backend's 400 { properties } catches the rest (isCustomizationError).
+ */
+export function needsPersonalization(product) {
+  return !!product?.customization_sets?.some((set) =>
+    (set.customization_fields || []).some((field) => field.required),
+  );
+}
+
+/** Whether an add-to-cart error is a customization rejection (400 { properties }). */
+export function isCustomizationError(error) {
+  const data = error?.data ?? error?.response?._data ?? error?.response?.data;
+  return !!(data && typeof data === "object" && !Array.isArray(data) && data.properties);
 }

package/app/composables/useProductDetail.js

@@ -337,6 +337,27 @@ export function createProductDetail({ product, settings = {}, loading = false }
 
   const customization = useProductCustomization(p, exactMatchVariant);
 
+  /**
+   * Price preview with customization: per-unit fees on the line, add-on items
+   * charged as their own lines. Only a preview — the cart total from the
+   * backend is what's charged. Null until something adds to the price.
+   */
+  const customizationPreview = computed(() => {
+    const delta = customization.deltaPerUnit.value;
+    const addonUnit = customization.addonsPerUnit.value;
+    if (!(delta > 0) && !(addonUnit > 0)) return null;
+    const qty = Number(quantity.value) || 1;
+    const line = pricing.value.total?.after ?? (Number(priceRange.value?.min) || 0) * qty;
+    const total = round2(line + (delta + addonUnit) * qty);
+    return {
+      delta,
+      addons: addonUnit,
+      quantity: qty,
+      total,
+      text: { delta: formatMoney(delta), addons: formatMoney(addonUnit), total: formatMoney(total) },
+    };
+  });
+
   function selectVariant(value) {
     if (value?.isAvailable === false) return;
     variants.selectVariant(value);
@@ -748,10 +769,8 @@ export function createProductDetail({ product, settings = {}, loading = false }
       return false;
     }
 
-    if (!customization.validate()) {
-      nextTick(() => document.querySelector(".osi-pdp-customization .has-error")?.scrollIntoView({ behavior: "smooth", block: "center" }));
-      return false;
-    }
+    // Required / max length / number checks; scrolls to the first bad field.
+    if (!customization.validate()) return false;
 
     isAddingToCart.value = true;
     try {
@@ -767,10 +786,8 @@ export function createProductDetail({ product, settings = {}, loading = false }
 
       return true;
     } catch (error) {
-      if (customization.applyServerErrors(error)) {
-        nextTick(() => document.querySelector(".osi-pdp-customization .has-error")?.scrollIntoView({ behavior: "smooth", block: "center" }));
-        return false;
-      }
+      // 400 { properties: { key: message } }: shown under each field.
+      if (customization.applyServerErrors(error)) return false;
       showApiError(error, "Couldn't add that to your cart.");
       return false;
     } finally {
@@ -888,6 +905,9 @@ export function createProductDetail({ product, settings = {}, loading = false }
 
   function resetSelections() {
     variants.reset();
+    // Field keys repeat across products (e.g. "engraving"), so answers never
+    // carry over to the next product.
+    customization.reset();
     quantity.value = quantityStep.value;
     showError.value = false;
   }
@@ -930,6 +950,7 @@ export function createProductDetail({ product, settings = {}, loading = false }
 
     // customization
     customization,
+    customizationPreview,
 
     // price
     pricing,

package/app/composables/useQuickShop.js

@@ -1,4 +1,5 @@
 import CartServices from "#osi/services/CartServices";
+import { isCustomizationError, needsPersonalization } from "./useProductCustomization";
 
 /**
  * Quick-shop: pick a variant and add to cart without leaving the grid.
@@ -26,6 +27,14 @@ export function useQuickShop({ product, variants, onAdded, closeOnAdd = true } =
 
   const { fetchCart } = useCart();
   const { showApiError } = useApiErrorToast();
+  const { productUrl } = useProductUrl();
+  const router = useRouter();
+
+  /** Required personalization: answered on the product page, not here. */
+  function goPersonalize() {
+    close();
+    router.push(productUrl(p.value));
+  }
 
   // Mobile only: the sheet covers the page, the desktop overlay doesn't.
   useBodyScrollLock(() => mode.value === "MOBILE");
@@ -61,6 +70,11 @@ export function useQuickShop({ product, variants, onAdded, closeOnAdd = true } =
       return false;
     }
 
+    if (needsPersonalization(p.value)) {
+      goPersonalize();
+      return false;
+    }
+
     adding.value = true;
     try {
       await CartServices.EditCart(
@@ -74,6 +88,11 @@ export function useQuickShop({ product, variants, onAdded, closeOnAdd = true } =
       if (closeOnAdd) close();
       return true;
     } catch (error) {
+      // 400 { properties }: the product needs personalizing first.
+      if (isCustomizationError(error)) {
+        goPersonalize();
+        return false;
+      }
       // Stock and cart-limit errors come back as field errors, so they need the
       // flattening — a bare error.message here would print "[object Object]".
       flashError(showApiError(error, "Couldn't add that to your cart."));
@@ -111,5 +130,6 @@ export function useQuickShop({ product, variants, onAdded, closeOnAdd = true } =
     addVariant,
     addSelected,
     flashError,
+    goPersonalize,
   };
 }

package/app/logic/components/CartDrawer.js

@@ -1,4 +1,3 @@
-import CartServices from "#osi/services/CartServices";
 import ProductServices from "#osi/services/ProductServices";
 
 export default function useLogic() {
@@ -33,7 +32,7 @@ export default function useLogic() {
   const txt = (key) => String(t(settings.value[key]) ?? "").trim() || TEXT_DEFAULTS[key] || "";
   const scheme = useColorScheme(computed(() => settings.value.CART_DRAWER_COLOR_SCHEME || null));
   const { isCartSidebarVisible, toggleCartSidebar } = useSidebar();
-  const { cartItems, cartTotal, count, fetchCart } = useCart();
+  const { cartItems, topLevelItems, childrenOf, cartTotal, count, fetchCart, isUpdating, increaseItem, decreaseItem, removeItem } = useCart();
   const { showApiError } = useApiErrorToast();
   const { mediaUrl } = useMediaUrl();
   const { productUrl } = useProductUrl();
@@ -124,27 +123,20 @@ export default function useLogic() {
 
   /* ---------------------------------------------------------------- lines */
 
-  // Per-line, not a single global flag: one slow line shouldn't disable the
-  // controls on every other line in the drawer.
-  const updatingIds = ref(new Set());
-  const isUpdating = (item) => updatingIds.value.has(item.id);
-
-  async function edit(item, action) {
-    if (isUpdating(item)) return;
-    updatingIds.value = new Set(updatingIds.value).add(item.id);
+  // Edits target one line by its order_item_id (one variant can have several
+  // lines with different customizations). Busy state is per line, in useCart,
+  // so the checkout page and header badge move with the drawer. Each edit
+  // returns the whole cart, so there's no follow-up fetch.
+  async function edit(fn, item) {
     try {
-      await CartServices.EditCart(item.id, item.quantity_step || 1, action);
-      await fetchCart();
+      await fn(item);
     } catch (error) {
       showApiError(error, "Couldn't update the cart.");
-    } finally {
-      const next = new Set(updatingIds.value);
-      next.delete(item.id);
-      updatingIds.value = next;
     }
   }
-  const increase = (item) => edit(item, "add");
-  const decrease = (item) => edit(item, "remove");
+  const increase = (item) => edit(increaseItem, item);
+  const decrease = (item) => edit(decreaseItem, item);
+  const remove = (item) => edit(removeItem, item);
 
   function close() {
     toggleCartSidebar(false);
@@ -269,5 +261,5 @@ export default function useLogic() {
   // rely on a page's onMounted to load the cart.
   onMounted(fetchCart);
 
-  return { settings, t, TEXT_DEFAULTS, txt, scheme, isCartSidebarVisible, toggleCartSidebar, cartItems, cartTotal, count, fetchCart, showApiError, mediaUrl, productUrl, handleAddToCart, store, currency, money, px, has, VARIANTS, buttonVars, button, checkoutBtn, emptyBtn, addBtn, cardStyle, RATIOS, rootStyle, updatingIds, isUpdating, edit, increase, decrease, close, go, threshold, shipping, recs, recsLoading, recsKey, pickedIds, limit, loadRecs, inCart, shownRecs, recsLayout, pricePos, adding, addRec, priceOf, analytics };
+  return { settings, t, TEXT_DEFAULTS, txt, scheme, isCartSidebarVisible, toggleCartSidebar, cartItems, topLevelItems, childrenOf, cartTotal, count, fetchCart, showApiError, mediaUrl, productUrl, handleAddToCart, store, currency, money, px, has, VARIANTS, buttonVars, button, checkoutBtn, emptyBtn, addBtn, cardStyle, RATIOS, rootStyle, isUpdating, edit, increase, decrease, remove, close, go, threshold, shipping, recs, recsLoading, recsKey, pickedIds, limit, loadRecs, inCart, shownRecs, recsLayout, pricePos, adding, addRec, priceOf, analytics };
 }

package/app/logic/components/CartItem.js

@@ -27,5 +27,22 @@ export default function useLogic({ props, emit }) {
     emit("add-item", props.item);
   }
 
-  return { mediaUrl, store, currency, imageSrc, variantLabel, handleRemove, handleAdd };
+  function handleDelete() {
+    if (props.loading) return;
+    emit("delete-item", props.item);
+  }
+
+  /** Customization answers, as "Label: value" (a ticked checkbox reads "Yes"). */
+  const properties = computed(() =>
+    (Array.isArray(props.item?.properties) ? props.item.properties : []).map((p) => ({
+      key: p.key,
+      label: p.label,
+      value: p.value === true ? "Yes" : p.value,
+    }))
+  );
+
+  // Add-on lines follow their product's quantity and go with it.
+  const isAddon = computed(() => !!props.item?.parent_item);
+
+  return { mediaUrl, store, currency, imageSrc, variantLabel, properties, isAddon, handleRemove, handleAdd, handleDelete };
 }

package/app/pages/checkout.vue

@@ -1,6 +1,14 @@
 <template>
   <div class="bg-gray-50 font-body text-primaryColor">
 
+    <!-- Customization changed since the item was added: placeOrder said so. -->
+    <div v-if="cartError" class="mx-auto max-w-6xl px-4 pt-4 lg:px-9" role="alert">
+      <div class="flex items-center justify-between gap-4 rounded-xl border border-red-200 bg-red-50 p-3 text-sm text-red-700">
+        <span>{{ cartError }}</span>
+        <button type="button" class="shrink-0 underline" @click="reviewCart">Review cart</button>
+      </div>
+    </div>
+
     <!-- ============ MOBILE ORDER STRIP ============ -->
     <div class="border-b border-gray-200 bg-white lg:hidden">
       <button
@@ -14,17 +22,17 @@
         <template v-else>
           <div class="flex flex-shrink-0 gap-1.5">
             <div
-              v-for="item in CartItems.slice(0, 2)"
-              :key="`strip-${item.id}`"
+              v-for="item in TopLevelItems.slice(0, 2)"
+              :key="`strip-${item.order_item_id}`"
               class="h-11 w-9 overflow-hidden rounded-md border border-gray-200 bg-white"
             >
               <img :src="imageUrl(item.image)" :alt="item.name" class="h-full w-full object-cover" />
             </div>
             <div
-              v-if="CartItems.length > 2"
+              v-if="TopLevelItems.length > 2"
               class="flex h-11 w-9 items-center justify-center rounded-md border border-dashed border-gray-300 text-xs text-gray-500"
             >
-              +{{ CartItems.length - 2 }}
+              +{{ TopLevelItems.length - 2 }}
             </div>
           </div>
           <div class="min-w-0 flex-1">
@@ -53,7 +61,9 @@
             <!-- line items with steppers -->
             <div
               v-for="item in CartItems"
-              :key="`strip-item-${item.id}`"
+              :key="`strip-item-${item.order_item_id}`"
+              :class="item.parent_item ? 'ms-5 opacity-80' : ''"
+              :data-checkout-lines="item === CartItems[0] ? 'mobile' : undefined"
               class="group flex items-center gap-3 py-2"
             >
               <div class="h-14 w-12 flex-shrink-0 overflow-hidden rounded-md border border-gray-200 bg-white">
@@ -62,7 +72,8 @@
               <div class="min-w-0 flex-1">
                 <p class="truncate text-[13px]">{{ item.name }}</p>
                 <p v-if="Array.isArray(item.values) ? item.values.length : item.values" class="truncate text-xs text-gray-400">{{ Array.isArray(item.values) && item.values.length ? item.values.join(' | ') : item.values || '' }}</p>
-                <div class="mt-1.5 flex items-center gap-3">
+                <p v-for="prop in item.properties || []" :key="prop.key" class="text-xs text-gray-500">{{ prop.label }}: {{ prop.value === true ? 'Yes' : prop.value }}</p>
+                <div v-if="!item.parent_item" class="mt-1.5 flex items-center gap-3">
                   <div class="flex h-7 w-fit items-center rounded-full border border-gray-300">
                     <button
                       type="button"
@@ -572,7 +583,9 @@
 
             <div
               v-for="item in CartItems"
-              :key="`rail-${item.id}`"
+              :key="`rail-${item.order_item_id}`"
+              :class="item.parent_item ? 'ms-5 opacity-80' : ''"
+              :data-checkout-lines="item === CartItems[0] ? 'rail' : undefined"
               class="group flex items-center gap-3 py-2"
             >
               <div class="h-14 w-12 flex-shrink-0 overflow-hidden rounded-md border border-gray-200 bg-white">
@@ -581,7 +594,8 @@
               <div class="min-w-0 flex-1">
                 <p class="truncate text-[13px]">{{ item.name }}</p>
                 <p v-if="Array.isArray(item.values) ? item.values.length : item.values" class="truncate text-xs text-gray-400">{{ Array.isArray(item.values) && item.values.length ? item.values.join(' | ') : item.values || '' }}</p>
-                <div class="mt-1.5 flex items-center gap-3">
+                <p v-for="prop in item.properties || []" :key="prop.key" class="text-xs text-gray-500">{{ prop.label }}: {{ prop.value === true ? 'Yes' : prop.value }}</p>
+                <div v-if="!item.parent_item" class="mt-1.5 flex items-center gap-3">
                   <div class="flex h-7 w-fit items-center rounded-full border border-gray-300">
                     <button
                       type="button"
@@ -774,7 +788,8 @@
               <!-- line items -->
               <div
                 v-for="item in CartItems"
-                :key="`bottom-${item.id}`"
+                :key="`bottom-${item.order_item_id}`"
+                :class="item.parent_item ? 'ms-5 opacity-80' : ''"
                 class="group flex items-center gap-3 py-2"
               >
                 <div class="h-14 w-12 flex-shrink-0 overflow-hidden rounded-md border border-gray-200 bg-white">
@@ -783,7 +798,8 @@
                 <div class="min-w-0 flex-1">
                   <p class="truncate text-[13px]">{{ item.name }}</p>
                   <p v-if="Array.isArray(item.values) ? item.values.length : item.values" class="truncate text-xs text-gray-400">{{ Array.isArray(item.values) && item.values.length ? item.values.join(' | ') : item.values || '' }}</p>
-                  <div class="mt-1.5 flex items-center gap-3">
+                <p v-for="prop in item.properties || []" :key="prop.key" class="text-xs text-gray-500">{{ prop.label }}: {{ prop.value === true ? 'Yes' : prop.value }}</p>
+                  <div v-if="!item.parent_item" class="mt-1.5 flex items-center gap-3">
                     <div class="flex h-7 w-fit items-center rounded-full border border-gray-300">
                       <button
                         type="button"
@@ -977,12 +993,15 @@ const {
   accordionAfterEnter,
   // cart
   CartItems,
+  TopLevelItems,
   total_price,
   totalItemsCount,
   isItemUpdating,
   increaseQuantity,
   decreaseQuantity,
   deleteItem,
+  cartError,
+  reviewCart,
   // user + form
   isLoggedIn,
   needsPhoneInput,

package/app/pages/order-detail.vue

@@ -209,8 +209,9 @@
               <div class="flex flex-col gap-4 mb-6">
                 <div
                   v-for="(item, index) in cartItemsWithLink"
-                  :key="index"
+                  :key="item.id ?? index"
                   class="flex gap-4 items-start"
+                  :class="item.parent_item ? 'ms-6 opacity-80' : ''"
                 >
                   <component
                     :is="item.productLink ? 'RouterLink' : 'div'"
@@ -242,6 +243,14 @@
                         <p v-if="item.variant_values" class="text-gray-500 text-xs mt-1">
                           {{ item.variant_values }}
                         </p>
+                        <!-- Customization snapshot taken at checkout. -->
+                        <p
+                          v-for="prop in item.properties || []"
+                          :key="prop.key"
+                          class="text-gray-500 text-xs mt-1"
+                        >
+                          {{ prop.label }}: {{ prop.value === true ? "Yes" : prop.value }}
+                        </p>
                       </div>
                       <p class="text-gray-800 font-medium text-sm whitespace-nowrap">
                         {{ currency }}{{ item.checkout_price }}
@@ -387,8 +396,22 @@ const sortedStatuses = computed(() =>
 
 const currentStatus = computed(() => sortedStatuses.value[0]?.status_name || "");
 
+// Each product followed by its add-on lines (parent_item = the parent's id).
+const orderedItems = computed(() => {
+  const items = cartItems.value;
+  const parents = items.filter((item) => !item.parent_item);
+  const ids = new Set(parents.map((item) => String(item.id)));
+  return [
+    ...parents.flatMap((parent) => [
+      parent,
+      ...items.filter((child) => child.parent_item && String(child.parent_item) === String(parent.id)),
+    ]),
+    ...items.filter((item) => item.parent_item && !ids.has(String(item.parent_item))),
+  ];
+});
+
 const cartItemsWithLink = computed(() =>
-  cartItems.value.map((item) => {
+  orderedItems.value.map((item) => {
     const product = item?.product?.product;
     const categorySlug = product?.categories?.[0]?.category?.slugified_name;
     const productSlug = product?.slugified_name;

package/app/pages/user-profile/components/orders.vue

@@ -28,14 +28,14 @@
             </div>
             <div class="pb-5">
               <p class="osi-acc-muted font-bold">
-                {{ currency }}{{ order?.checkout_cart_price + order?.checkout_delivery_fees }}
+                {{ currency }}{{ orderTotal(order) }}
               </p>
             </div>
           </div>
           <div class="w-full max-w-[1800px] grid grid-cols-2 sm:grid-cols-4">
             <div
               v-for="(item, index) in getCartItemsWithLink(order?.items || [])"
-              :key="index"
+              :key="item.id ?? index"
               class="transition-all w-full sm:w-[200px] duration-300"
             >
               <component
@@ -65,6 +65,17 @@
                   >
                     {{ item.variant_values }}
                   </p>
+                  <!-- Add-on line (gift wrap…) bought with another product. -->
+                  <p v-if="item.parent_item" class="osi-acc-muted text-xs">
+                    Add-on{{ parentName(order, item) ? ` · ${parentName(order, item)}` : "" }}
+                  </p>
+                  <p
+                    v-for="prop in item.properties || []"
+                    :key="prop.key"
+                    class="osi-acc-muted text-xs"
+                  >
+                    {{ prop.label }}: {{ prop.value === true ? "Yes" : prop.value }}
+                  </p>
                 </div>
               </div>
             </div>
@@ -146,6 +157,16 @@ const getLatestStatus = (order) => {
   return latest.status_name;
 };
 
+// The server's own total (promo, fees and customization included). The old
+// sum of two fields concatenated when the API returned them as strings.
+const orderTotal = (order) =>
+  order?.checkout_order_total ??
+  (Number(order?.checkout_cart_price) || 0) + (Number(order?.checkout_delivery_fees) || 0);
+
+/** The product an add-on line was bought with. */
+const parentName = (order, item) =>
+  (order?.items || []).find((line) => String(line.id) === String(item.parent_item))?.name || "";
+
 const getCartItemsWithLink = (items = []) => {
   return items.map((item) => {
     const product = item?.product?.product;

package/app/services/CartServices.js

@@ -17,39 +17,112 @@ const persistCartToken = (responseData) => {
 };
 
 /**
- * Add to / remove from a cart line (a line is a variant id).
+ * A cart response's lines as a list. Lines are keyed by their line id
+ * (order_item_id); one variant can sit on several lines (different
+ * customizations, or as an add-on of another product), so nothing may look a
+ * line up by variant id.
+ */
+export function cartLines(response) {
+  return Object.entries(response?.cart || {}).map(([key, line]) => ({
+    ...line,
+    order_item_id: line?.order_item_id ?? key,
+  }));
+}
+
+/** A variant's own top-level lines summed: what "this product in the cart" means now. */
+function variantSnapshot(lines, variantId) {
+  const own = lines.filter((l) => String(l.id) === String(variantId) && !l.parent_item);
+  if (!own.length) return null;
+  return { ...own[0], quantity: own.reduce((n, l) => n + (Number(l.quantity) || 0), 0) };
+}
+
+async function post(body) {
+  const baseUrl = getBaseUrl();
+  const responseData = await apiService(`${baseUrl}store/apis/cart/update-item/`, {
+    method: "POST",
+    headers: cartHeaders(),
+    body: JSON.stringify(body),
+  });
+  return persistCartToken(responseData);
+}
+
+/**
+ * Add a variant to the cart (the only action that takes a variant id).
  *
  * `context` is optional: callers that hold the product (product page, card,
  * quick buy) pass `{ product, variant }` so the analytics event carries its
- * brand and category, which the cart payload doesn't repeat. Cart-side callers
- * (drawer, checkout) omit it and get it from what was remembered at add time.
+ * brand and category, which the cart payload doesn't repeat.
+ *
+ * `properties` are the customization answers, keyed by field key
+ * ({ cover_name: "Lara", cover_color: "<option id>", gift_wrap: true }). The
+ * backend validates and prices them; a bad answer comes back as
+ * 400 { properties: { key: message } } and nothing is added. Same variant +
+ * same answers merges into the existing line, different answers make a new one.
  *
- * This is the single place add_to_cart / remove_from_cart are reported: every
- * cart edit in the storefront goes through here, once.
+ * Signature kept from before (item_id, quantity, action, context, properties)
+ * so existing callers don't change. Any action other than "add" is forwarded
+ * to editLine with `item_id` treated as the line id.
  */
-const EditCart = async (item_id, quantity = 1, action, context, properties = null) => {
+const EditCart = async (item_id, quantity = 1, action = "add", context, properties = null) => {
+  if (action !== "add") return editLine({ order_item_id: item_id }, action, quantity);
   try {
-    const baseUrl = getBaseUrl();
-    const before = analytics.peekCartLine(item_id);
-    const body = { quantity, item_id, action };
+    const before = variantSnapshot(analytics.peekCartLines(), item_id);
+    const body = { item_id, quantity, action: "add" };
     if (properties && Object.keys(properties).length) body.properties = properties;
-    const responseData = await apiService(`${baseUrl}store/apis/cart/update-item/`, {
-      method: "POST",
-      headers: cartHeaders(),
-      body: JSON.stringify(body),
-    });
-    persistCartToken(responseData);
+    const responseData = await post(body);
     analytics.cartEdited({
       itemId: item_id,
+      variantId: item_id,
       quantity,
-      action,
+      action: "add",
       before,
-      after: responseData?.cart?.[item_id] ?? null,
+      after: variantSnapshot(cartLines(responseData), item_id),
       context,
     });
     return responseData;
   } catch (error) {
-    console.error('Cart fetch error:', error);
+    console.error('Cart update error:', error);
+    throw error;
+  }
+};
+
+/**
+ * Change one exact cart line.
+ *
+ *   edit        set the line's quantity to `quantity`
+ *   remove      take `quantity` off the line (0 deletes it)
+ *   remove_all  delete the line
+ *
+ * Add-on lines (parent_item set) follow their parent and can't be edited on
+ * their own — the backend rejects it, so callers never offer it.
+ */
+const editLine = async (line, action, quantity) => {
+  const orderItemId = line?.order_item_id;
+  if (!orderItemId) throw new Error("Missing cart line id.");
+  try {
+    const before = analytics.peekCartLine(orderItemId);
+    const body = { order_item_id: orderItemId, action };
+    if (action !== "remove_all") body.quantity = quantity;
+    const responseData = await post(body);
+    const after = responseData?.cart?.[orderItemId]
+      ?? cartLines(responseData).find((l) => String(l.order_item_id) === String(orderItemId))
+      ?? null;
+    const prev = Number(before?.quantity ?? line?.quantity) || 0;
+    const next = Number(after?.quantity) || 0;
+    // Analytics speaks add/remove; "edit" is whichever way the quantity moved.
+    if (next !== prev) {
+      analytics.cartEdited({
+        itemId: orderItemId,
+        variantId: before?.id ?? line?.id,
+        quantity: Math.abs(next - prev),
+        action: next > prev ? "add" : "remove",
+        before: before ?? line,
+        after,
+      });
+    }
+    return responseData;
+  } catch (error) {
+    console.error('Cart update error:', error);
     throw error;
   }
 };
@@ -88,6 +161,7 @@ const mergeCart = async () => {
 
 export default {
   EditCart,
+  editLine,
   fetchCart,
   mergeCart,
 };

package/app/utils/analytics.js

@@ -72,9 +72,9 @@ const state = {
   pixelIds: [],
   currency: "",
   consent: true,
-  /** Last cart the server sent, keyed by line (variant) id. */
+  /** Last cart the server sent, keyed by line id (order_item_id). */
   cart: {},
-  /** What we know about a line beyond the cart payload: brand, category… */
+  /** What we know about a variant beyond the cart payload: brand, category… (keyed by variant id) */
   lineContext: new Map(),
   /** Once-per-page guards (view_item, view_item_list). Cleared on navigation. */
   seen: new Set(),
@@ -240,12 +240,14 @@ export function productToItem(product, opts = {}) {
 }
 
 /**
- * A cart line (the server's `cart[id]` entry, keyed by variant id) -> item.
- * The payload doesn't repeat brand / category, so what the add-to-cart call
- * site knew is remembered per line and laid back over it here.
+ * A cart line -> item. `line.id` is the variant id (one variant can sit on
+ * several lines now, so lines are keyed by order_item_id); `id` is only the
+ * fallback. The payload doesn't repeat brand / category, so what the
+ * add-to-cart call site knew is remembered per variant and laid back over it.
  */
 function cartLineToItem(id, line, quantity) {
-  const known = state.lineContext.get(String(id)) ?? {};
+  const variantId = line?.id ?? id;
+  const known = state.lineContext.get(String(variantId)) ?? {};
   const productId =
     known.item_id ?? line?.product_id ?? line?.product?.id ?? line?.product?.product?.id ?? id;
   return clean({
@@ -255,7 +257,7 @@ function cartLineToItem(id, line, quantity) {
     item_category: known.item_category,
     item_category2: known.item_category2,
     item_variant: variantLabel(line) || known.item_variant,
-    variant_id: String(id),
+    variant_id: String(variantId),
     sku: line?.sku ?? known.sku,
     price: money(line?.price ?? known.price),
     quantity: quantity ?? Math.max(1, num(line?.quantity)),
@@ -499,11 +501,16 @@ function selectItem(product, override = {}) {
   log("select_item", ga);
 }
 
-/** What we last heard the cart contained for this line, before an edit. */
+/** What we last heard the cart contained for this line (order_item_id), before an edit. */
 function peekCartLine(id) {
   return state.cart[String(id)] ?? null;
 }
 
+/** Every line we last heard about, as a list (to sum a variant across lines). */
+function peekCartLines() {
+  return Object.entries(state.cart).map(([key, line]) => ({ ...line, order_item_id: line?.order_item_id ?? key }));
+}
+
 /** Remembers the server's cart. Called with every cart response. */
 function rememberCart(response) {
   if (!isClient() || !response || typeof response !== "object") return;
@@ -524,13 +531,16 @@ function resetCart() {
  * through, from product pages, cards, quick buy, the drawer and checkout — so
  * nothing is missed and nothing is counted twice.
  *
- * @param {{ itemId: string|number, quantity: number, action: "add"|"remove",
+ * `variantId` keys what the call site knew (brand, category); `itemId` is the
+ * line or variant the edit targeted.
+ *
+ * @param {{ itemId: string|number, variantId?: string|number, quantity: number, action: "add"|"remove",
  *           before: object|null, after: object|null,
  *           context?: { product?: object, variant?: object } }} edit
  */
-function cartEdited({ itemId, quantity, action, before, after, context }) {
+function cartEdited({ itemId, variantId, quantity, action, before, after, context }) {
   if (!isClient()) return;
-  const id = String(itemId);
+  const id = String(variantId ?? before?.id ?? after?.id ?? itemId);
 
   // Remember what the call site knew, for later edits made from the drawer.
   if (context?.product) {
@@ -832,6 +842,7 @@ const api = {
   viewItemList,
   selectItem,
   peekCartLine,
+  peekCartLines,
   rememberCart,
   resetCart,
   cartEdited,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osimart/create-storefront",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Osimart storefront platform — logic, platform pages and CLI; extended by every theme repo",
   "type": "module",
   "main": "./nuxt.config.ts",