@wix/agent-skills 1.16.2 → 1.17.0

package/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js

@@ -11,15 +11,16 @@ import { wixApiRequest } from "./wix-client.js";
  *   fulfillmentIds {string[]}, businessLocationId {string}
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/operation-object.md
  *
- * Cart (Wix eCom) — restaurant orders use the same visitor cart as the storefront.
- *   id {string}, currency {string},
+ * Cart (Wix eCom V2) — restaurant orders use the same visitor cart as the storefront.
+ *   id {string} — the cart id IS the checkout id,
  *   lineItems[].id {string} — lineItemId for update/remove (NOT the item id),
- *   lineItems[].quantity {number},
- *   lineItems[].catalogReference.catalogItemId {string} — the ordered item's GUID,
- *   lineItems[].productName.original {string},
- *   lineItems[].price.formattedAmount {string},
- *   lineItems[].availability.status {string} — "AVAILABLE"|"NOT_AVAILABLE"|"PARTIALLY_AVAILABLE"|"NOT_FOUND"
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/cart/cart-object.md
+ *   lineItems[].quantityInfo.confirmedQuantity {number},
+ *   lineItems[].source.catalogReference.catalogItemId {string} — the ordered item's GUID (NOT top-level in V2),
+ *   lineItems[].name.original {string},
+ *   lineItems[].pricing.unitPrice / lineItems[].pricing.totalPrice {ConvertedMoney} —
+ *     { amount, convertedAmount } with NO formatted string; format the number client-side,
+ *   lineItems[].status {string} — "IN_STOCK"|"PARTIALLY_IN_STOCK"|"OUT_OF_STOCK"|"REMOVED_FROM_CATALOG"
+ * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md
  */
 
 // Wix Restaurants Orders app id — required in catalogReference when adding menu items to the eCom cart.
@@ -61,7 +62,7 @@ export async function getDefaultOperation() {
  * Confirm the shape before extending:
  * https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/sample-flows.md
  *
- * POST https://www.wixapis.com/ecom/v1/carts/current/add-to-cart
+ * POST https://www.wixapis.com/ecom/v2/carts/current/add-line-items
  * @param {string} itemId  Menu item GUID (item.id).
  * @param {{ operationId: string, menuId: string, sectionId: string, onlineOrderingPageUrl?: string, quantity?: number }} opts
  * @returns {Promise<object>} Updated cart.
@@ -74,15 +75,16 @@ export async function addItemToCart(itemId, { operationId, menuId, sectionId, on
   const options = { operationId, menuId, sectionId };
   if (onlineOrderingPageUrl) options.onlineOrderingPageUrl = onlineOrderingPageUrl;
 
-  const res = await wixApiRequest("/ecom/v1/carts/current/add-to-cart", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/add-line-items", {
     method: "POST",
     body: {
-      lineItems: [{ catalogReference: { appId: RESTAURANTS_ORDERS_APP_ID, catalogItemId: itemId, options }, quantity }],
+      catalogItems: [{ catalogReference: { appId: RESTAURANTS_ORDERS_APP_ID, catalogItemId: itemId, options }, quantity }],
     },
   });
-  const line = (res?.cart?.lineItems ?? []).find((l) => l.catalogReference?.catalogItemId === itemId);
-  if (line?.availability?.status && line.availability.status !== "AVAILABLE") {
-    throw new Error(`Item not available to order (status: ${line.availability.status}).`);
+  // V2 nests the reference under `source` — a top-level lineItem.catalogReference no longer exists.
+  const line = (res?.cart?.lineItems ?? []).find((l) => l.source?.catalogReference?.catalogItemId === itemId);
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`Item not available to order (status: ${line.status}).`);
   }
   return res?.cart;
 }
@@ -90,7 +92,7 @@ export async function addItemToCart(itemId, { operationId, menuId, sectionId, on
 /** Read the visitor's current cart. Returns null if no cart exists yet. */
 export async function getCurrentCart() {
   try {
-    const res = await wixApiRequest("/ecom/v1/carts/current", { method: "GET" });
+    const res = await wixApiRequest("/ecom/v2/carts/current", { method: "GET" });
     return res?.cart ?? null;
   } catch {
     return null;
@@ -99,24 +101,24 @@ export async function getCurrentCart() {
 
 /**
  * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not the item id.
- * POST https://www.wixapis.com/ecom/v1/carts/current/update-line-items-quantity
+ * POST https://www.wixapis.com/ecom/v2/carts/current/update-line-items
  * @returns {Promise<object>} Updated cart.
  */
 export async function updateCartItemQuantity(lineItemId, quantity) {
-  const res = await wixApiRequest("/ecom/v1/carts/current/update-line-items-quantity", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/update-line-items", {
     method: "POST",
-    body: { lineItems: [{ id: lineItemId, quantity }] },
+    body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] },
   });
   return res?.cart;
 }
 
 /**
  * Remove a line from the current cart by its cart.lineItems[].id.
- * POST https://www.wixapis.com/ecom/v1/carts/current/remove-line-items
+ * POST https://www.wixapis.com/ecom/v2/carts/current/remove-line-items
  * @returns {Promise<object>} Updated cart.
  */
 export async function removeFromCart(lineItemId) {
-  const res = await wixApiRequest("/ecom/v1/carts/current/remove-line-items", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/remove-line-items", {
     method: "POST",
     body: { lineItemIds: [lineItemId] },
   });
@@ -124,7 +126,9 @@ export async function removeFromCart(lineItemId) {
 }
 
 /**
- * Create a checkout from the current cart and return the Wix-hosted checkout URL.
+ * Start the hosted checkout for the current cart and return the Wix-hosted checkout URL.
+ * In Cart V2 the cart id IS the checkout id — there is no separate checkout-creation call; the
+ * redirect session is created straight from the current cart's id.
  * Throws on empty cart, unavailable lines, or a missing redirect URL.
  * Redirect with: window.location.href = await checkout()
  * @returns {Promise<string>}
@@ -133,22 +137,16 @@ export async function checkout() {
   const cart = await getCurrentCart();
   const lines = cart?.lineItems ?? [];
   if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
-  const unavailable = lines.filter((l) => l.availability?.status && l.availability.status !== "AVAILABLE");
+  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
   if (unavailable.length) {
-    const names = unavailable.map((l) => l.productName?.original ?? l.catalogReference?.catalogItemId).join(", ");
+    const names = unavailable.map((l) => l.name?.original ?? l.source?.catalogReference?.catalogItemId).join(", ");
     throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
   }
-
-  const checkoutRes = await wixApiRequest("/ecom/v1/carts/current/create-checkout", {
-    method: "POST",
-    body: { channelType: "WEB" },
-  });
-  const checkoutId = checkoutRes?.checkoutId;
-  if (!checkoutId) throw new Error("Failed to create checkout from the current cart.");
+  if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");
 
   const redirect = await wixApiRequest("/headless/v1/redirect-session", {
     method: "POST",
-    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+    body: { ecomCheckout: { checkoutId: cart.id }, callbacks: { postFlowUrl: window.location.href } },
   });
   const url = redirect?.redirectSession?.fullUrl;
   if (!url) throw new Error("Failed to create the checkout redirect session.");

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -237,6 +237,8 @@ render.
 
 ## Using the client from your own UI (cart, hand-built images)
 
+> Migrating from Cart V1 / Checkout V1? These helpers are V2-only — see the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide) for the before/after.
+
 ```jsx
 import { Link } from "react-router-dom";
 import { useCart } from "@/context/CartContext";
@@ -246,15 +248,20 @@ import { useCart } from "@/context/CartContext";
 //   addToCart(productId, variantId?, qty=1, { modifierChoices?, customTextFields? }?),
 //   removeItem(lineItemId), updateQuantity(lineItemId, qty), checkout(), refreshCart() }
 // Every mutation catches its own failure into `error` (the shipped CartDrawer renders it), so a
-// refusal — an empty cart, or a line item that stopped being AVAILABLE — reaches the buyer instead
+// refusal — an empty cart, or a line item whose status left IN_STOCK — reaches the buyer instead
 // of becoming an unhandled rejection.
 //
-// Cart money: every amount is { amount, convertedAmount, formattedAmount, formattedConvertedAmount } —
-// show a formatted one so the currency symbol and grouping come from Wix. Read
-// `cart.subtotalAfterDiscounts` rather than `cart.subtotal`: the two match until a cart-level coupon
-// applies, and then `subtotal` is the pre-discount figure. `cart.discount` + `cart.appliedDiscounts`
-// carry the reduction. Never sum line items yourself — tax and shipping resolve at checkout.
-// `lineItems[].availability.quantityAvailable` is the stock cap for a quantity control.
+// Cart money: every amount is a ConvertedMoney { amount, convertedAmount } with NO formatted string —
+// `amount` is in the site currency, `convertedAmount` in the display currency; format the number
+// yourself (Intl.NumberFormat with the cart's currency —
+// `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode`) so the symbol and grouping
+// match the locale. The V2 cart has no `subtotalAfterDiscounts`/`discount`/`appliedDiscounts`: it
+// carries only a raw `cart.subtotal` (ConvertedMoney). The authoritative discounted totals come from
+// a currentCartV2 estimate/calculate `summary.priceSummary`, not the cart — call that when you need
+// the after-coupon figure; otherwise show `cart.subtotal`. Never sum line items yourself — tax and
+// shipping resolve at checkout.
+// A line's `status` (IN_STOCK / PARTIALLY_IN_STOCK / OUT_OF_STOCK) tells a quantity control whether
+// another increment is still fulfillable.
 
 function CartCount() {                                   // header badge
   const { itemCount, setIsOpen } = useCart();
@@ -294,7 +301,7 @@ const { products: inCategory } = await queryProductsByCategory(menu[0].id, { lim
 
 // product.plainDescription is HTML → render as HTML (the PDP does this):
 <div dangerouslySetInnerHTML={{ __html: product.plainDescription }} />
-// image urls live at: product.media.main.image.url  ·  cart lineItems[].image.url
+// image urls live at: product.media.main.image.url  ·  cart lineItems[].attributes.image.url
 ```
 
 Fallback only — when you hit an error or need something not shown here (coupons, members, a field

package/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx

@@ -2,29 +2,36 @@
 // check out via the context (redirect-session URL). Styled with base44 design tokens (shadcn Tailwind classes).
 //
 // Load-bearing beyond the styling:
-// • prices come from the SERVER cart — `price` is post-discount, `fullPrice` is before it, so the
-//   two together are the strikethrough. Never compute a total in the client: tax, shipping and
-//   promotions are resolved server-side, so `subtotal` is the only figure safe to show pre-checkout.
-//   Money objects carry { amount, convertedAmount, formattedAmount, formattedConvertedAmount }; use a
-//   formatted one so the currency symbol and grouping come from Wix. Prefer `subtotalAfterDiscounts`
-//   over `subtotal` — the two are equal until a cart-level coupon applies, and then `subtotal` is the
-//   pre-discount figure, which would quote the buyer more than they'll pay.
-// • `availability.quantityAvailable` caps the stepper, so exceeding stock is refused here rather than
+// • prices come from the SERVER cart. In Cart V2 each line total is `pricing.totalPrice`, a
+//   ConvertedMoney { amount, convertedAmount } with NO formatted string — format it yourself with the
+//   cart's currency (see formatCartMoney). Never compute a total in the client: tax, shipping and
+//   promotions are resolved server-side, so the cart's `subtotal` is the only figure safe to show
+//   pre-checkout. The V2 cart has no `subtotalAfterDiscounts`/`discount`/`appliedDiscounts` — the
+//   discounted total comes from a currentCartV2 estimate/calculate `summary.priceSummary`, not the
+//   cart; absent that call, show the raw `subtotal`.
+// • `quantityInfo.availableQuantity` caps the stepper, so exceeding stock is refused here rather than
 //   at checkout.
-// • `availability.status` is flagged per line here because checkout() refuses the whole cart when
-//   any item isn't AVAILABLE — showing it on the row is what makes that refusal understandable.
+// • `status` is flagged per line here because checkout() refuses the whole cart when any item isn't
+//   IN_STOCK — showing it on the row is what makes that refusal understandable.
 import { useEffect } from "react";
 import { useCart } from "@/context/CartContext";
 import { storeImage } from "@/lib/storeImage";
 
+// Cart V2 money is a ConvertedMoney { amount, convertedAmount } with NO formatted string — format it
+// with the cart's currency (buyer's display currency when present, else the site currency).
+function formatCartMoney(money, cart) {
+  const value = money?.convertedAmount ?? money?.amount;
+  const currency = cart?.customerInfo?.currencyCode ?? cart?.businessInfo?.currencyCode ?? "USD";
+  return value == null ? "" : new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+}
+
 export default function CartDrawer() {
   const { cart, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
   const lineItems = cart?.lineItems ?? [];
-  const money = (m) => m?.formattedConvertedAmount || m?.formattedAmount;
-  const subtotal = money(cart?.subtotalAfterDiscounts) || money(cart?.subtotal);
-  const discount = money(cart?.discount);
-  const hasDiscount = (cart?.appliedDiscounts?.length || 0) > 0 && Number(cart?.discount?.amount) > 0;
-  const unavailable = lineItems.filter((li) => li.availability?.status && li.availability.status !== "AVAILABLE");
+  // The V2 cart carries only a raw `subtotal` (ConvertedMoney); discounted totals live on an
+  // estimate/calculate `summary.priceSummary`, which this cart helper doesn't fetch — so show `subtotal`.
+  const subtotal = formatCartMoney(cart?.subtotal, cart);
+  const unavailable = lineItems.filter((li) => li.status && li.status !== "IN_STOCK");
 
   // Escape closes the drawer while it's open — expected of anything modal, and the only way out for
   // keyboard users (the backdrop click is pointer-only).
@@ -70,46 +77,44 @@ export default function CartDrawer() {
                 className="border border-border bg-card text-foreground rounded-sm py-2 px-4 cursor-pointer text-sm">Continue shopping</button>
             </div>
           ) : lineItems.map((item) => {
-            const image = storeImage(item.image?.url);
-            const struck = item.fullPrice?.formattedAmount;
-            const paid = item.price?.formattedAmount;
-            const isOut = item.availability?.status && item.availability.status !== "AVAILABLE";
-            const stock = item.availability?.quantityAvailable;
-            const atStockLimit = Number.isFinite(stock) && item.quantity >= stock;
+            const image = storeImage(item.attributes?.image?.url);
+            const paid = formatCartMoney(item.pricing?.totalPrice, cart);
+            const isOut = item.status && item.status !== "IN_STOCK";
+            const stock = item.quantityInfo?.availableQuantity;
+            const qty = item.quantityInfo?.confirmedQuantity;
+            const atStockLimit = Number.isFinite(stock) && qty >= stock;
             return (
               <div key={item.id} className="flex gap-3 py-3 px-0 border-b border-border">
                 <div className="w-16 h-16 shrink-0 rounded-sm bg-card overflow-hidden">
-                  {image && <img src={image} alt={item.productName?.original || ""} className="w-full h-full object-cover" />}
+                  {image && <img src={image} alt={item.name?.original || ""} className="w-full h-full object-cover" />}
                 </div>
                 <div className="flex-1 flex flex-col gap-1 min-w-0">
-                  <span className="font-semibold truncate">{item.productName?.original}</span>
-                  {item.descriptionLines?.map((dl, i) => (
+                  <span className="font-semibold truncate">{item.name?.original}</span>
+                  {/* V2 nests these under `attributes` — a top-level lineItem.descriptionLines no longer exists */}
+                  {item.attributes?.descriptionLines?.map((dl, i) => (
                     <small key={i} className="text-muted-foreground">
                       {dl.name?.original}: {dl.plainText?.original || dl.colorInfo?.original}
                     </small>
                   ))}
                   {isOut ? (
                     <small className="text-destructive">
-                      {item.availability.status === "NOT_AVAILABLE" ? "No longer available" : "Not enough stock"}
+                      {item.status === "PARTIALLY_IN_STOCK" ? "Not enough stock" : "No longer available"}
                     </small>
                   ) : atStockLimit ? (
                     <small className="text-muted-foreground">Only {stock} left</small>
                   ) : null}
                   <div className="flex items-center gap-2 mt-1">
-                    <QtyButton disabled={loading || item.quantity <= 1} label="Decrease quantity"
-                      onClick={() => updateQuantity(item.id, item.quantity - 1)}>−</QtyButton>
-                    <span className="min-w-5 text-center" aria-label={`Quantity ${item.quantity}`}>{item.quantity}</span>
+                    <QtyButton disabled={loading || qty <= 1} label="Decrease quantity"
+                      onClick={() => updateQuantity(item.id, qty - 1)}>−</QtyButton>
+                    <span className="min-w-5 text-center" aria-label={`Quantity ${qty}`}>{qty}</span>
                     <QtyButton disabled={loading || atStockLimit} label="Increase quantity"
-                      onClick={() => updateQuantity(item.id, item.quantity + 1)}>+</QtyButton>
+                      onClick={() => updateQuantity(item.id, qty + 1)}>+</QtyButton>
                     <button onClick={() => removeItem(item.id)} disabled={loading}
                       className="ml-auto border-none bg-transparent cursor-pointer text-muted-foreground text-[13px] underline disabled:opacity-50">Remove</button>
                   </div>
                 </div>
                 <div className="flex flex-col items-end shrink-0">
                   <span className="font-semibold">{paid}</span>
-                  {struck && struck !== paid && (
-                    <span className="text-muted-foreground line-through text-[13px]">{struck}</span>
-                  )}
                 </div>
               </div>
             );
@@ -118,12 +123,6 @@ export default function CartDrawer() {
 
         {lineItems.length > 0 && (
           <footer className="p-4 border-t border-border flex flex-col gap-3">
-            {hasDiscount && (
-              <div className="flex justify-between items-baseline text-sm">
-                <span className="text-muted-foreground">Discount</span>
-                <span>−{discount}</span>
-              </div>
-            )}
             {subtotal && (
               <div className="flex justify-between items-baseline">
                 <span className="text-muted-foreground">Subtotal</span>

package/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx

@@ -16,7 +16,7 @@ export function CartProvider({ children }) {
   const [isOpen, setIsOpen] = useState(false);
   const [loading, setLoading] = useState(false);
   // The cart helpers throw on refusal with a buyer-readable reason — an empty cart, or line items
-  // whose availability.status isn't AVAILABLE. Hold the message so the drawer can show it; without
+  // whose status isn't IN_STOCK. Hold the message so the drawer can show it; without
   // this the rejection is unhandled and the shopper sees the spinner stop with nothing said.
   const [error, setError] = useState(null);
 
@@ -28,7 +28,7 @@ export function CartProvider({ children }) {
     return () => document.removeEventListener("visibilitychange", onVisible);
   }, [refreshCart]);
 
-  const itemCount = (cart?.lineItems ?? []).reduce((n, li) => n + (li.quantity || 0), 0);
+  const itemCount = (cart?.lineItems ?? []).reduce((n, li) => n + (li.quantityInfo?.confirmedQuantity || 0), 0);
 
   // Every mutation runs through here so a rejection always lands somewhere visible. `run` keeps the
   // cart untouched on failure — the server stays the source of truth — and re-reads it for anything

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js

@@ -7,20 +7,22 @@ import { wixApiRequest } from "./wix-client.js";
 const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
 
 /**
- * Wix eCom Cart — key fields for building a cart UI.
+ * Wix eCom Cart V2 — key fields for building a cart UI.
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md
  *
- *   id {string}, currency {string},
+ *   id {string} — the cart id IS the checkout id (currency lives under businessInfo.currencyCode / customerInfo.currencyCode, not at the cart root),
  *   lineItems[].id {string} — lineItemId for update/remove (NOT catalogItemId),
- *   lineItems[].quantity {number},
- *   lineItems[].catalogReference.catalogItemId {string},
- *   lineItems[].productName.original {string},
- *   lineItems[].price.formattedAmount {string} — after discounts with currency symbol,
- *   lineItems[].fullPrice.formattedAmount {string} — before discount (strikethrough),
- *   lineItems[].descriptionLines {array} — human-readable option/modifier labels:
+ *   lineItems[].quantityInfo.confirmedQuantity {number},
+ *   lineItems[].source.catalogReference.catalogItemId {string} — NOT top-level in V2,
+ *   lineItems[].name.original {string},
+ *   lineItems[].pricing.unitPrice {ConvertedMoney} — per-unit price after discounts,
+ *   lineItems[].pricing.totalPrice {ConvertedMoney} — line total after discounts,
+ *     ConvertedMoney is { amount, convertedAmount } with NO formatted string — `amount` is in the
+ *     site currency, `convertedAmount` in the display currency; format the number client-side.
+ *   lineItems[].attributes.descriptionLines {array} — human-readable option/modifier labels:
  *     [{ name: { original }, plainText: { original } OR colorInfo: { original, code } }],
- *   lineItems[].image.url {string},
- *   lineItems[].availability.status {string} — "AVAILABLE"|"NOT_AVAILABLE"|"PARTIALLY_AVAILABLE"|"NOT_FOUND"
+ *   lineItems[].attributes.image {object} — { id, url, height, width, altText } (use .url),
+ *   lineItems[].status {string} — "IN_STOCK"|"PARTIALLY_IN_STOCK"|"OUT_OF_STOCK"|"REMOVED_FROM_CATALOG"
  */
 
 /**
@@ -52,20 +54,22 @@ export async function addToCart(catalogItemId, variantId, quantity = 1, { modifi
 
   const catalogReference = { appId: STORES_APP_ID, catalogItemId };
   if (Object.keys(catalogReferenceOptions).length) catalogReference.options = catalogReferenceOptions;
-  const res = await wixApiRequest("/ecom/v1/carts/current/add-to-cart", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/add-line-items", {
     method: "POST",
-    body: { lineItems: [{ catalogReference, quantity }] },
+    body: { catalogItems: [{ catalogReference, quantity }] },
   });
+  // V2 nests the reference under `source` — a top-level lineItem.catalogReference no longer exists.
   const line = (res?.cart?.lineItems ?? []).find(
-    (l) => l.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.catalogReference?.options?.variantId === variantId),
+    (l) => l.source?.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
   );
-  // Wix returns 200 even when the line is silently rejected — guard both signals:
-  // 1. availability.status set to something other than AVAILABLE
-  // 2. no matching line at all (quantity 0 / line absent)
-  if (line?.availability?.status && line.availability.status !== "AVAILABLE") {
-    throw new Error(`Item not available for sale (status: ${line.availability.status}). Is it in stock?`);
+  // Cart V2 rejects an unbuyable line with an explicit error rather than silently dropping it, but
+  // guard both signals defensively:
+  // 1. status set to something other than IN_STOCK
+  // 2. no matching line at all (confirmed quantity 0 / line absent)
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`Item not available for sale (status: ${line.status}). Is it in stock?`);
   }
-  if (!line || line.quantity === 0) {
+  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
     // A missing line usually means a required selection wasn't sent — a mandatory modifier
     // (pass modifierChoices/customTextFields) or the variantId for a product with options —
     // not necessarily out of stock. Verify every required choice is included in this call.
@@ -81,7 +85,7 @@ export async function addToCart(catalogItemId, variantId, quantity = 1, { modifi
 /** Read the visitor's current cart. Returns null if no cart exists yet. */
 export async function getCurrentCart() {
   try {
-    const res = await wixApiRequest("/ecom/v1/carts/current", { method: "GET" });
+    const res = await wixApiRequest("/ecom/v2/carts/current", { method: "GET" });
     return res?.cart ?? null;
   } catch {
     return null;
@@ -89,7 +93,9 @@ export async function getCurrentCart() {
 }
 
 /**
- * Create a checkout from the current cart and return the hosted checkout URL.
+ * Start the hosted checkout for the current cart and return its URL.
+ * In Cart V2 the cart id IS the checkout id — there is no separate checkout-creation call; the
+ * redirect session is created straight from the current cart's id.
  * Throws on empty cart, unavailable lines, or a missing redirect URL.
  * Usage: window.location.href = await checkout()
  * @returns {Promise<string>}
@@ -98,22 +104,16 @@ export async function checkout() {
   const cart = await getCurrentCart();
   const lines = cart?.lineItems ?? [];
   if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
-  const unavailable = lines.filter((l) => l.availability?.status && l.availability.status !== "AVAILABLE");
+  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
   if (unavailable.length) {
-    const names = unavailable.map((l) => l.productName?.original ?? l.catalogReference?.catalogItemId).join(", ");
+    const names = unavailable.map((l) => l.name?.original ?? l.source?.catalogReference?.catalogItemId).join(", ");
     throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
   }
-
-  const checkoutRes = await wixApiRequest("/ecom/v1/carts/current/create-checkout", {
-    method: "POST",
-    body: { channelType: "WEB" },
-  });
-  const checkoutId = checkoutRes?.checkoutId;
-  if (!checkoutId) throw new Error("Failed to create checkout from the current cart.");
+  if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");
 
   const redirect = await wixApiRequest("/headless/v1/redirect-session", {
     method: "POST",
-    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+    body: { ecomCheckout: { checkoutId: cart.id }, callbacks: { postFlowUrl: window.location.href } },
   });
   const url = redirect?.redirectSession?.fullUrl;
   if (!url) throw new Error("Failed to create the checkout redirect session.");
@@ -122,13 +122,13 @@ export async function checkout() {
 
 /**
  * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not catalogItemId.
- * Wix caps the result at remaining stock — returned quantity may be lower than requested.
+ * Cart V2 rejects an over-stock quantity with an explicit error rather than clamping it.
  * @returns {Promise<object>} Updated cart.
  */
 export async function updateCartItemQuantity(lineItemId, quantity) {
-  const res = await wixApiRequest("/ecom/v1/carts/current/update-line-items-quantity", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/update-line-items", {
     method: "POST",
-    body: { lineItems: [{ id: lineItemId, quantity }] },
+    body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] },
   });
   return res?.cart;
 }
@@ -139,7 +139,7 @@ export async function updateCartItemQuantity(lineItemId, quantity) {
  * @returns {Promise<object>} Updated cart.
  */
 export async function removeFromCart(lineItemId) {
-  const res = await wixApiRequest("/ecom/v1/carts/current/remove-line-items", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/remove-line-items", {
     method: "POST",
     body: { lineItemIds: [lineItemId] },
   });