From e70853ef763b753f86fcf9413a1a0f039a41b562 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Wed, 5 Aug 2026 19:37:57 +0300
Subject: [PATCH 01/31] docs(ecom): migrate storefront cart/checkout references
 to Cart V2

Cart V1 + Checkout V1 are replaced by the unified Cart V2 API (both V1 APIs
removed 2027-02-01). Updates the headless store recipe and the vibe-headless
storefront reference to Cart V2:

- currentCart -> currentCartV2; addToCurrentCart -> addLineItemsToCurrentCart
  (lineItems -> catalogItems)
- REST paths /ecom/v1/carts/current/* -> /ecom/v2/carts/current/*
- No checkout entity: drop createCheckoutFromCurrentCart; the cart id IS the
  checkout id, fed straight into the redirect session
- Line-item read shapes: quantity->quantityInfo.confirmedQuantity,
  productName->name, price->pricing, image->attributes.image,
  availability.status->status (IN_STOCK/PARTIALLY_IN_STOCK/OUT_OF_STOCK/REMOVED_FROM_CATALOG)
- update-line-items body now {lineItemId, quantity:{newQuantity}}

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../inline-recipes/how-to-code-a-store.md     | 41 +++++-----
 .../references/storefront/INSTRUCTIONS.md     |  8 +-
 .../references/storefront/wix-store-cart.js   | 75 ++++++++++---------
 3 files changed, 65 insertions(+), 59 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index 3023f8c3c..939ab1da4 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -24,7 +24,7 @@ A concise contract for writing the **frontend code** of a storefront against a C
 | Products (list, get, search, filter) | `@wix/stores` | `productsV3` |
 | Variants (to resolve `variantId`) | `@wix/stores` | `readOnlyVariantsV3` |
 | Categories | `@wix/stores` | `categories` |
-| Cart (add / get / checkout) | `@wix/ecom` | `currentCart` |
+| Cart (add / get / checkout) | `@wix/ecom` | `currentCartV2` |
 | Redirect to hosted checkout | `@wix/redirects` | `redirects` |
 
 **Never** import the V1 `products` or `collections` modules from `@wix/stores`.
@@ -35,11 +35,11 @@ A concise contract for writing the **frontend code** of a storefront against a C
   ```js
   import { createClient, OAuthStrategy } from '@wix/sdk';
   import { productsV3, readOnlyVariantsV3 } from '@wix/stores';
-  import { currentCart } from '@wix/ecom';
+  import { currentCartV2 } from '@wix/ecom';
   import { redirects } from '@wix/redirects';
 
   const client = createClient({
-    modules: { productsV3, readOnlyVariantsV3, currentCart, redirects },
+    modules: { productsV3, readOnlyVariantsV3, currentCartV2, redirects },
     auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
   });
   ```
@@ -49,7 +49,7 @@ A concise contract for writing the **frontend code** of a storefront against a C
 
 ## The shapes you read (field cheat-sheet)
 
-The exact field paths the storefront reads, and the **plausible-wrong sibling** each is mistaken for — the sections below reference these instead of re-describing them. All `amount`s are **strings**. These are **read** shapes; the cart-add body (under *Adding to cart*) is a separate **write** shape, and the `_id` rule applies to read **entities**, not to method-return wrappers (note `checkoutId`).
+The exact field paths the storefront reads, and the **plausible-wrong sibling** each is mistaken for — the sections below reference these instead of re-describing them. All `amount`s are **strings**. These are **read** shapes; the cart-add body (under *Adding to cart*) is a separate **write** shape, and the `_id` rule applies to read **entities**, not to request params (note the redirect session's `checkoutId`, which is just the cart's `_id`).
 
 ```jsonc
 // productsV3.queryProducts().…find()  →  result.items[]
@@ -72,11 +72,12 @@ variant = {
   inventoryStatus: { inStock },                   // variant-level stock (boolean)
 }
 
-// currentCart.getCurrentCart()  →  { lineItems: [...] }
-lineItem = { quantity, price: { amount }, image }  // price is HERE (NOT actualPriceRange); image is wix:image:// too → resolve
+// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: wrapped in { cart } (V1 returned the cart directly)
+lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
+// price → pricing.unitPrice.amount (raw string, NO currency symbol in V2 — format it yourself); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
-// currentCart.createCheckoutFromCurrentCart({ channelType })  →  { checkoutId }   // a STRING — NOT { checkout }, NOT _id
-// redirects.createRedirectSession({ ecomCheckout: { checkoutId }, callbacks })  →  { redirectSession: { fullUrl } }
+// Cart V2 has NO checkout entity — the cart's _id IS the checkout id; there is no createCheckout call:
+// redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }
 ```
 
 ---
@@ -94,7 +95,7 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v
 
 **⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** The SDK normalizes every entity's id to **`_id`**. `product.id` is `undefined` in SDK code. This is the cart-killer: feeding `product.id` into the cart's `catalogItemId` sends an empty string and the add returns **HTTP 500** (`"catalogItemId" has size 0`). Use `product._id` everywhere — in links, as the cart `catalogItemId`, and as the variant-query filter value. (If a field name surprises you, you are probably reading the REST doc view — re-open it with `?apiView=SDK`.)
 
-**Scope of the `_id` rule — entity reads only.** `_id` is the id of a read **entity** (product, variant, cart line item). It is **not** a universal "every id field is `_id`" rule: method results name their own fields (e.g. `createCheckoutFromCurrentCart` returns `checkoutId`, *not* `_id` — see Checkout). Don't assume a method's return wrapper exposes `_id`.
+**Scope of the `_id` rule — entity reads only.** `_id` is the id of a read **entity** (product, variant, cart line item). It is **not** a universal "every id field is `_id`" rule: request params name their own fields (e.g. the redirect session takes `ecomCheckout.checkoutId`, *not* `_id` — see Checkout — even though the value you pass is the cart's `_id`). Don't assume every id-shaped field is spelled `_id`.
 
 **Visibility:** only `visible: true` products are returned to a visitor token, so a missing product usually means it wasn't seeded visible — not a query bug.
 
@@ -149,11 +150,11 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v
 
 Each `variant` carries `variant.optionChoices[].optionChoiceNames` — `{ optionName, choiceName }`. Match the buyer's selected options (Size = "Small", Color = "Red", …) against those names to pick the variant. For a **single-variant** product, use the only item. Fall back to `items[0]` if matching yields nothing. The id to send to the cart is **`variant.variantId ?? variant._id`**.
 
-**2 · Add it.** Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/add-to-current-cart.md?apiView=SDK> · catalogReference contract: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md?apiView=SDK>
+**2 · Add it.** Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md?apiView=SDK> · catalogReference contract: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md?apiView=SDK>
 
 ```js
-await currentCart.addToCurrentCart({
-  lineItems: [{
+await currentCartV2.addLineItemsToCurrentCart({
+  catalogItems: [{                                // Cart V2: `catalogItems`, NOT V1's `lineItems`
     quantity,
     catalogReference: {
       catalogItemId: product._id,                 // the product's _id (the `_id` rule above)
@@ -170,19 +171,21 @@ await currentCart.addToCurrentCart({
 
 ### Checkout
 
-Create a checkout from the current cart, then redirect the buyer to the hosted checkout.
-Docs: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/create-checkout-from-current-cart.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/get-current-cart.md?apiView=SDK>
+Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout id. Read the current cart, then hand its id to a redirect session, which carries the visitor/member session across to the hosted checkout on its own domain.
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
 
 ```js
-const checkout = await currentCart.createCheckoutFromCurrentCart({ channelType: currentCart.ChannelType.WEB });
+const { cart } = await currentCartV2.getCurrentCart();   // NOTE: wrapped in { cart } (V1 returned the cart directly)
 const session = await redirects.createRedirectSession({
-  ecomCheckout: { checkoutId: checkout.checkoutId },   // checkout.checkoutId — NOT checkout._id
+  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id — there is no createCheckout call
   callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
 });
 window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL
 ```
 
-**⚠️ Return shapes are in the cheat-sheet** — `createCheckoutFromCurrentCart` gives **`checkout.checkoutId`** (a string), not `checkout._id`. Reading `checkout._id` (over-applying the `_id` rule) throws *"Cannot read properties of undefined (reading '_id')"* — the silent checkout crash.
+**⚠️ There is no `createCheckoutFromCurrentCart` in Cart V2.** The V1 flow created a checkout entity and returned a `checkoutId`; V2 unifies cart + checkout, so you pass the cart's own `_id` straight into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` now returns **`{ cart }`** (V1 returned the cart directly) — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
+
+> **Simpler alternative (see PR note):** `cartV2.getCheckoutUrl(cartId)` returns a hosted-checkout URL directly, letting you drop `@wix/redirects`. It isn't used here because the redirect session is what carries the visitor/member session across domains; whether the plain URL preserves that for a headless storefront is unverified.
 
 **⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats **`http://<same host>` as a different, unlisted origin**. When the buyer returns from the hosted checkout (e.g. clicks "Continue Browsing"), the redirect goes through the allowlist — and an `http://` `postFlowUrl` **403s** with *"… isn't listed as an allowed redirect domain."* If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to **`http://`** behind Wix's TLS-terminating proxy → guaranteed 403 on return. So **pass `window.location.origin` from the client** into the route (don't read the origin off the request), or force the scheme to `https`. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
 
@@ -208,7 +211,7 @@ function imgSrc(mediaMain, w = 600, h = 600) {
 
 **Never hand-build a `static.wixstatic.com/.../v1/fit/...` URL** either — the format is easy to get wrong and the image then **403s**. Only `wix:image://` values need resolving; an already-absolute `https://` URL goes straight into `<img src>`. Doc: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>
 
-**This applies to cart line-item images too, not just product reads.** A cart `lineItem.image` is the same `wix:image://` identifier — run it through the same `imgSrc()` helper before `<img src>`. (If you build the cart over an API route, resolve there and return a ready URL so the component never sees a `wix:image://`.)
+**This applies to cart line-item images too, not just product reads.** A cart `lineItem.attributes.image` (Cart V2 nests it under `attributes`) is the same `wix:image://` identifier — run it through the same `imgSrc()` helper before `<img src>`. (If you build the cart over an API route, resolve there and return a ready URL so the component never sees a `wix:image://`.)
 
 ### Rendering product descriptions
 
@@ -230,7 +233,7 @@ Optional: render a `Product` schema.org JSON-LD `<script>` from the fetched prod
 
 ## Conclusion
 A correct Catalog V3 storefront frontend:
-- imports **`productsV3` / `readOnlyVariantsV3` / `categories` / `currentCart` / `redirects`** — never the V1 `products`/`collections` modules;
+- imports **`productsV3` / `readOnlyVariantsV3` / `categories` / `currentCartV2` / `redirects`** — never the V1 `products`/`collections` modules;
 - uses **`product._id`** (never `product.id`) as the cart's `catalogItemId`;
 - resolves the **mandatory `variantId`** via `readOnlyVariantsV3` and passes it as `options.variantId` (not `options.options`);
 - builds its category nav from a **live `categories.queryCategories()`** and filters category pages server-side with **`searchProducts` + `$matchItems: [{ id: categoryId }]`** keyed on the live `categoryId` — never a frozen seed-time `productIds` map, never `queryProducts` for category filtering, never `$hasSome`, never V1 `collectionIds`;
diff --git a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
index 69f601040..5add3bce7 100644
--- a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
@@ -64,7 +64,7 @@ reference for anything not shown.
   `product.modifiers` (TEXT_CHOICES → choice buttons/select; FREE_TEXT → a text input); render
   neither when the arrays are empty. Skipping modifiers is a common miss — a product with a
   **mandatory** modifier (e.g. "gift wrap?") whose control isn't rendered can never be added: the
-  buyer can't satisfy the requirement, so `add-to-cart` returns 200 with an **empty** `lineItems`
+  buyer can't satisfy the requirement, so `add-line-items` returns 200 with an **empty** `lineItems`
   and the add silently no-ops.
   Render `product.plainDescription` as **HTML** — despite the name it contains markup (`<p>`,
   `<br>`, `<strong>`), so `dangerouslySetInnerHTML={{ __html: product.plainDescription }}` (React)
@@ -112,8 +112,8 @@ reference for anything not shown.
   add products in their Wix dashboard. Never invent products.
 
 ## Hard rules (do not violate)
-- ✅ Checkout ONLY via `checkout()` (`create-checkout` → `/headless/v1/redirect-session`
-  `fullUrl`), then redirect.
+- ✅ Checkout ONLY via `checkout()` (current cart id → `/headless/v1/redirect-session`
+  `fullUrl`), then redirect. Cart V2 has no `create-checkout` step — the cart id is the checkout id.
 - ❌ Never hand-build `/checkout`, cart-add, or product permalinks for purchase.
 - ❌ Never mock products — render live Wix data or the empty state.
 - ❌ Never generate fake reviews, ratings, or testimonials. Empty review UI only.
@@ -122,7 +122,7 @@ reference for anything not shown.
 - ✅ On the PDP, render a control for **every** `product.options` entry **and** every `product.modifiers`
   entry — never only variants. Keep Add-to-cart disabled until a variant resolves and every
   `modifier.mandatory === true` has a value; a mandatory modifier with no rendered control makes the
-  product unbuyable (add-to-cart returns 200 with empty `lineItems`).
+  product unbuyable (add-line-items returns 200 with empty `lineItems`).
 - ✅ Pass `addToCart`'s `variantId` (`variantsInfo.variants[].id`) for products with variants; omit for products without.
 - ✅ Pass `modifierChoices` (`{ [modifier.key]: choiceKey }`) for TEXT_CHOICES modifiers; pass `customTextFields`
   (`{ [modifier.freeTextSettings.key]: userInput }`) for FREE_TEXT modifiers. Include mandatory modifiers.
diff --git a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
index 78dd232be..0cfd706db 100644
--- a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
+++ b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
@@ -7,20 +7,25 @@ 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.
- * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/get-cart.md
+ * 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-cart.md
  *
- *   id {string}, currency {string},
+ *   id {string}, businessInfo.currencyCode {string} (site currency), customerInfo.currencyCode {string} (display currency),
  *   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} — quantity that will actually be purchased,
+ *   lineItems[].quantityInfo.requestedQuantity {number}, lineItems[].quantityInfo.availableQuantity {number},
+ *   lineItems[].source.catalogReference.catalogItemId {string},
+ *   lineItems[].name.original {string} (name.translated for buyer's language),
+ *   lineItems[].pricing.unitPrice.amount {string} — raw decimal, after discounts (NO currency symbol in V2 — format client-side),
+ *   lineItems[].pricing.totalPrice.amount {string} — line total (unit x qty),
+ *   lineItems[].pricing.breakdown.fullPrice.amount {string} — before discount (strikethrough),
+ *   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.url {string},
+ *   lineItems[].status {string} — "IN_STOCK"|"PARTIALLY_IN_STOCK"|"OUT_OF_STOCK"|"REMOVED_FROM_CATALOG"
+ *
+ * Note: display totals (subtotal, tax, formatted amounts) are NOT stored on the cart in V2.
+ * Call Calculate/Estimate Cart to get a summary — see checkout() for the flow.
  */
 
 /**
@@ -52,20 +57,21 @@ 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 }] },
   });
   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 reports invalid items as explicit errors, but partial stock still returns a
+  // reduced confirmedQuantity — guard both signals:
+  // 1. status set to something other than IN_STOCK
+  // 2. no matching line at all (confirmedQuantity 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 +87,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,31 +95,28 @@ export async function getCurrentCart() {
 }
 
 /**
- * Create a checkout from the current cart and return the hosted checkout URL.
+ * Send the current cart to the hosted Wix checkout and return the redirect URL.
  * Throws on empty cart, unavailable lines, or a missing redirect URL.
  * Usage: window.location.href = await checkout()
+ *
+ * Cart V2 has no separate checkout entity — the cart id IS the checkout id, so there is no
+ * "create checkout" step. We still create a redirect session so the visitor/member session
+ * carries across to the Wix-hosted checkout page on its own domain.
  * @returns {Promise<string>}
  */
 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.");
-
   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 +125,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.
+ * Wix caps the result at remaining stock — returned confirmedQuantity may be lower than requested.
  * @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 +142,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] },
   });

From d0a3d04f380cb3e22ff2d3fe7a2f4f486c3436f1 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 10:26:19 +0300
Subject: [PATCH 02/31] docs(ecom): fix residual currentCart -> currentCartV2
 in store recipe

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-a-store.md            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index 939ab1da4..92644481f 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -30,7 +30,7 @@ A concise contract for writing the **frontend code** of a storefront against a C
 **Never** import the V1 `products` or `collections` modules from `@wix/stores`.
 
 **Auth / client — framework split:**
-- **Astro (Wix-managed):** authentication is ambient. Call `currentCart` / `productsV3` / `readOnlyVariantsV3` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
+- **Astro (Wix-managed):** authentication is ambient. Call `currentCartV2` / `productsV3` / `readOnlyVariantsV3` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
 - **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
   ```js
   import { createClient, OAuthStrategy } from '@wix/sdk';

From c3647d1e92608d805669fcc66aee7de3279109b7 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 10:50:58 +0300
Subject: [PATCH 03/31] docs(ecom): migrate remaining cart/checkout references
 to Cart V2

Extends the Cart V2 migration to every remaining Cart V1 / Checkout V1
reference across the skills repo (mappings verified against the ecom
CartV1Proxy Scala V1<->V2 mappers):

- inline-recipes: how-to-code-restaurant-orders (full cart+checkout flow),
  how-to-code-pricing-plans (membership moved to line-item selectedMembership)
- wix-vibe-headless: restaurants (REST client + INSTRUCTIONS), bookings
  (checkouts -> carts create/place-order)
- wix-manage: bookings integration + end-to-end flow, cms catalog integration
  (checkout/cart V1 REST -> cart-v2 create/calculate/place-order)
- wix-app: SITE_PLUGIN currentCart example, backend-event cart.onCart* -> cartV2
- SDK_HANDOFF + rp-mapper taxonomy: stale V1 references/links -> cart-v2

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../wix-business-solutions-taxonomy.md        |  2 +-
 skills/wix-app/references/SITE_PLUGIN.md      |  4 +-
 .../references/backend-event/COMMON-EVENTS.md |  4 +-
 skills/wix-headless/references/SDK_HANDOFF.md |  2 +-
 .../how-to-code-pricing-plans.md              | 14 ++---
 .../how-to-code-restaurant-orders.md          | 41 ++++++-------
 .../booking-system-integration-gaps.md        | 27 +++++----
 .../bookings/end-to-end-booking-flow.md       | 35 +++++++----
 .../cms/cms-ecommerce-catalog-integration.md  |  8 +--
 .../bookings/wix-bookings-checkout.js         | 18 +++---
 .../references/restaurants/INSTRUCTIONS.md    |  2 +-
 .../restaurants/wix-restaurants-ordering.js   | 59 +++++++++----------
 12 files changed, 118 insertions(+), 98 deletions(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index b24630f40..3c69ebb7b 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -96,7 +96,7 @@ Primary entities:
 
 | Entity | What it does | Docs |
 | --- | --- | --- |
-| `cart` | First phase of the purchase flow; holds line items, buyer references, discounts, and pricing context before checkout | [About the eCommerce Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart/cart/introduction) |
+| `cart` | First phase of the purchase flow; holds line items, buyer references, discounts, and pricing context before checkout | [About the eCommerce Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `current-cart` | Visitor/member scoped cart used in live purchase flows | [About the eCommerce Current Cart API](https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/introduction) |
 | `checkout` | Second phase of purchase flow; holds calculated prices, tax, billing, shipping, and discount state before order creation | [About the eCommerce Checkout API](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
diff --git a/skills/wix-app/references/SITE_PLUGIN.md b/skills/wix-app/references/SITE_PLUGIN.md
index 85c20be7d..3f6207968 100644
--- a/skills/wix-app/references/SITE_PLUGIN.md
+++ b/skills/wix-app/references/SITE_PLUGIN.md
@@ -324,14 +324,14 @@ Site plugins can import and use Wix SDK modules directly — you do NOT need `cr
 ```typescript
 // ✅ CORRECT — Import SDK modules directly
 import { items } from "@wix/data";
-import { currentCart } from "@wix/ecom";
+import { currentCartV2 } from "@wix/ecom";
 import { products } from "@wix/stores";
 
 class MyPlugin extends HTMLElement {
   async loadData() {
     // Call SDK methods directly — no createClient needed
     const result = await items.query("MyCollection").find();
-    const cart = await currentCart.getCurrentCart();
+    const { cart } = await currentCartV2.getCurrentCart();
     const productList = await products.queryProducts().limit(10).find();
   }
 }
diff --git a/skills/wix-app/references/backend-event/COMMON-EVENTS.md b/skills/wix-app/references/backend-event/COMMON-EVENTS.md
index 24d21e88b..7b7d0d5b9 100644
--- a/skills/wix-app/references/backend-event/COMMON-EVENTS.md
+++ b/skills/wix-app/references/backend-event/COMMON-EVENTS.md
@@ -21,8 +21,8 @@ Order events use **`@wix/ecom`** (namespace `orders`). Order **refund** events a
 | Order canceled | `import { orders } from "@wix/ecom"` | `orders.onOrderCanceled(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCanceled](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-canceled?apiView=SDK) |
 | Refund created | `import { refunds } from "@wix/payments"` | `refunds.onRefundCreated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundCreated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-created?apiView=SDK) |
 | Refund updated | `import { refunds } from "@wix/payments"` | `refunds.onRefundUpdated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundUpdated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-updated?apiView=SDK) |
-| Cart created | `import { cart } from "@wix/ecom"` | `cart.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-created?apiView=SDK) |
-| Cart updated | `import { cart } from "@wix/ecom"` | `cart.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-updated?apiView=SDK) |
+| Cart created | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-created.md?apiView=SDK) |
+| Cart updated | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-updated.md?apiView=SDK) |
 
 ## Bookings Events
 
diff --git a/skills/wix-headless/references/SDK_HANDOFF.md b/skills/wix-headless/references/SDK_HANDOFF.md
index 7b26ce04f..64620c2ee 100644
--- a/skills/wix-headless/references/SDK_HANDOFF.md
+++ b/skills/wix-headless/references/SDK_HANDOFF.md
@@ -68,7 +68,7 @@ Everything else the host resolves live from the queries in §3. (Static platform
 - Frontend CMS access is **read**; visitor writes go through **Forms** submissions.
 - **Blog comments are member-gated — read public, write authenticated.** Querying/rendering comments is public, so list them server-side in SSR. **Submitting** needs a logged-in member, so don't gate the form behind an upfront login check (that branch is what burns deliberation): render the form always and resolve identity at submit — POST to a backend endpoint (`src/pages/api/*.ts`) that calls `createComment` with the request session; if the caller isn't a member, redirect to the built-in `/api/auth/login?returnUrl=…`. **Do not build the comment form as a client island** — the API-endpoint + session path is the documented shape and avoids the browser-auth detour. The comment API keys (post `referenceId`, Blog appDefId, author lookup via `post.memberId`) are in `how-to-code-a-blog.md`.
 - **Member auth is one mechanism split on the frontend axis (the §3 members note routes to the right recipe), and orthogonal to elevation.** Sign-up and log-in are the *same* flow (the Wix login page logs in **or** registers); log-out is its inverse. Two layers stay separate: **identity** (logged-in vs not — no app install) vs **profile** (name/photo/roles — needs the **Wix Members Area app** installed, `SETUP.md`). **pricing-plans is a hard dependency**: subscribing requires a logged-in member; for the other verticals, member login is a soft add-on for their "my …" surfaces only. **A member reading their own data (own orders/bookings/subscriptions, plan-gated content) uses the member token with NO `auth.elevate`** — elevation is the separate admin/permission axis (site-wide reads, server-side only), not something member features need.
-- **Gating is a LIVE signal, never a hardcoded id list.** Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read **at request time** — a queryable flag carried on the content (a `members-only` blog category/tag or a boolean CMS field) and live coverage/eligibility (`checkout.membershipOptions.eligibleMemberships`, or the member's active-order `planId`s matched against **live** Benefit-Program coverage). **Never** gate on a frozen set of "premium" slugs/ids or a seed-time `plan→service` map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See `how-to-code-a-blog.md` (member features) and `how-to-code-pricing-plans.md` (coverage read).
+- **Gating is a LIVE signal, never a hardcoded id list.** Whenever content is gated (members-only articles, plan-eligible class booking, any "premium" surface), decide eligibility from a signal read **at request time** — a queryable flag carried on the content (a `members-only` blog category/tag or a boolean CMS field) and live coverage/eligibility (Cart V2's `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships`, or the member's active-order `planId`s matched against **live** Benefit-Program coverage). **Never** gate on a frozen set of "premium" slugs/ids or a seed-time `plan→service` map: a gated post or a newly-covered service the owner adds later would silently read as public/ineligible. See `how-to-code-a-blog.md` (member features) and `how-to-code-pricing-plans.md` (coverage read).
 
 ### 6 · What a complete site must include (per loaded capability)
 For each loaded capability, carry its **Required site features** and **Implementation checklist** from `references/CAPABILITIES.md` into the guide — in plain product language, lightly tailored to what was seeded. **This is the build spec, not optional polish:** the host should build every *required feature* and cover every *checklist* item. For example, a blog must show the **author** (name + photo), the publish date and reading time, the cover image, and the **full formatted content** (not flattened text) — a posts-list-plus-plain-text-body is incomplete. The host maps these onto its own components using the packages/docs in §3 and the seeded schema in §4.
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index fc116f64d..f5bd6c97e 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -23,7 +23,7 @@ A contract for the **frontend code** of a pricing-plans site: showing the plans
 | List / read plans (the grid) | `@wix/pricing-plans` | `plansV3` (Plans V3 — `queryPlans`, `getPlan`) |
 | Order a plan + read a member's orders | `@wix/pricing-plans` | `orders` (`createOnlineOrder`, `memberListOrders`, `memberGetOrder`) |
 | Member login / current member | `@wix/members` + `@wix/sdk` auth | see the members recipe (`getCurrentMember`, `loggedIn()`) |
-| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `checkout` (`membershipOptions`) — see *Booking with a membership* |
+| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `currentCartV2` (line-item `selectedMembership`) — see *Booking with a membership* |
 
 **Never** import `@wix/site-pricing-plans` in headless code, and don't reach for a V1 `plans`-collection query — Plans V3 (`queryPlans` → `pricingVariants`) is the shape the seed creates.
 
@@ -98,13 +98,13 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
-3. **The booking still rides the ecom checkout** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the checkout**, not on the booking object. The eligible plan surfaces on the **ecom Checkout** entity's `membershipOptions`:
-   - `membershipOptions.eligibleMemberships[]` — the member's plans that can cover the line item (each `{ _id, appId, name, credits }`).
-   - apply one via `checkout.updateCheckout(...)` setting `membershipOptions.selectedMemberships.memberships = [{ _id, appId, lineItemIds: [<booking line item id>] }]`. When the membership covers the full price, `payNow` drops to `0`.
-   Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/get-checkout.md?apiView=SDK>
+3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Cart V2 unified cart + checkout, so membership selection moved off the old checkout-entity `membershipOptions` and onto the line item's `selectedMembership`:
+   - **Eligible memberships** — the member's plans that can cover the line item — come from `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships[]`. **⚠️ VERIFY IN A LIVE BUILD:** confirm this is the field a headless member token reads (in Checkout V1 the equivalent `membershipOptions.eligibleMemberships` was tagged "reserved for internal use"; use the fallback below if it comes back empty).
+   - **Apply one** by setting the line item's `selectedMembership` (`{ id, appId }`) via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, selectedMembership: { id, appId } }] })`. When the membership covers the full price, the calculated `payNow`/total drops to `0`. **⚠️ VERIFY the exact request nesting in a live build** — the mapping places it under the line item's `paymentConfig.selectedMembership`.
+   Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md?apiView=SDK>
 4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
 
-- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. **Preferred:** read `checkout.membershipOptions.eligibleMemberships` — the plans that can cover *this* line item, computed server-side from live coverage. (It's tagged "reserved for internal use" in the schema, so **VERIFY IN A LIVE BUILD** whether a headless member token reads it client-side.) **Fallback if that field comes back empty for a member token:** list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` + `selectedMemberships` from whichever read succeeds.
+- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. **Preferred:** read the eligible plans from `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships` — the plans that can cover *this* line item, computed server-side from live coverage. (**VERIFY IN A LIVE BUILD** whether a headless member token reads it client-side.) **Fallback if that comes back empty for a member token:** list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `selectedMembership` from whichever read succeeds.
 - **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
 - **Credit/session plans:** for a limited (non-unlimited) plan, `eligibleMemberships[].credits.remaining` matters — `0` remaining is not eligible. An unlimited plan (seed `price:"0"`) has no credit ceiling.
 
@@ -121,4 +121,4 @@ A correct Pricing Plans frontend:
 - imports **`@wix/pricing-plans`** (`plansV3`, `orders`) — **never** `@wix/site-pricing-plans` (its `startOnlinePurchase` is Wix-site page-code, not headless);
 - lists the grid publicly with **`plansV3.queryPlans().eq('visibility','PUBLIC')`**, reads **`plan._id`** and price from **`pricingVariants[].pricingStrategies[].flatRate.amount`** (decimal string) — never a top-level `price` — and only shows a buy button on `buyable` plans;
 - treats **subscribe and my-subscription as login-gated** (the hard members dependency), orders with **`orders.createOnlineOrder(planId)`** (no `onBehalf`, no elevate), renders free plans as `ACTIVE` immediately, and drives paid plans through a payment redirect (**exact headless redirect to be confirmed in a live build**) — and **stops at the redirect**: no payments-account connect, no order activation / mark-as-paid from code (see *Out of scope*);
-- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom checkout** (`membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the checkout eligibility field isn't readable client-side.
+- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom Cart V2 line item** (`selectedMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index 7da73dee5..6aa581410 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -26,14 +26,14 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 | Menus / sections / items (display) | `@wix/restaurants` | `menus` / `sections` / `items` — see `how-to-code-restaurants.md` |
 | The ordering operation (for `operationId`) | `@wix/restaurants` | `operations` |
 | Fulfillment methods (pickup/delivery to show) | `@wix/restaurants` | `fulfillmentMethods` |
-| Cart (add / get / checkout) | `@wix/ecom` | `currentCart` |
+| Cart (add / get / checkout) | `@wix/ecom` | `currentCartV2` |
 | Redirect to hosted checkout | `@wix/redirects` | `redirects` |
 
 **Auth / client — framework split:**
 - **Astro (Wix-managed):** authentication is ambient. Call `operations` / `fulfillmentMethods` / `currentCart` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
   ```js
   import { operations, fulfillmentMethods } from '@wix/restaurants';
-  import { currentCart } from '@wix/ecom';
+  import { currentCartV2 } from '@wix/ecom';
   const { operations: ops } = await operations.listOperations();
   ```
 - **Non-Astro (Vite/React/Vue/static):** build one manual visitor client and reuse it:
@@ -44,10 +44,10 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
   import { redirects } from '@wix/redirects';
 
   const client = createClient({
-    modules: { menus, sections, items, operations, fulfillmentMethods, currentCart, redirects },
+    modules: { menus, sections, items, operations, fulfillmentMethods, currentCartV2, redirects },
     auth: OAuthStrategy({ clientId: /* the project's PUBLIC OAuth client id */ }),
   });
-  // then: await client.operations.listOperations(), await client.currentCart.addToCurrentCart({...})
+  // then: await client.operations.listOperations(), await client.currentCartV2.addLineItemsToCurrentCart({...})
   ```
   The `clientId` is public, not a secret. A mis-wired public env var inlines as `undefined` and 400s every call.
 
@@ -55,7 +55,7 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 
 ## The shapes you read (field cheat-sheet)
 
-These are **SDK read shapes** (`?apiView=SDK`), so entity ids are **`_id`**. Prices/fees are decimal **strings**. The cart-add body (under *Adding a menu item to the cart*) is a separate **write** shape; the `_id` rule applies to read **entities**, not to method-return wrappers (note `checkoutId`).
+These are **SDK read shapes** (`?apiView=SDK`), so entity ids are **`_id`**. Prices/fees are decimal **strings**. The cart-add body (under *Adding a menu item to the cart*) is a separate **write** shape; the `_id` rule applies to read **entities**, not to request params (note the redirect session's `checkoutId`, which is just the cart's `_id`).
 
 ```jsonc
 // operations.listOperations()  →  { operations: [...] }   (no arguments)
@@ -79,11 +79,12 @@ fulfillmentMethod = {
 // item (from items.listItems — see how-to-code-restaurants.md)
 item = { _id, name, priceInfo: { price } }   // price is a decimal STRING; _id → cart catalogItemId
 
-// currentCart.getCurrentCart()  →  { lineItems: [...] }
-lineItem = { quantity, price: { amount }, image }   // amount is the string price; image is wix:image:// → resolve
+// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: wrapped in { cart } (V1 returned the cart directly)
+lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
+// price → pricing.unitPrice.amount (raw string, NO currency symbol in V2 — format it yourself); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
-// currentCart.createCheckoutFromCurrentCart({ channelType })  →  { checkoutId }   // a STRING — NOT { checkout }, NOT _id
-// redirects.createRedirectSession({ ecomCheckout: { checkoutId }, callbacks })  →  { redirectSession: { fullUrl } }
+// Cart V2 has NO checkout entity — the cart's _id IS the checkout id; there is no createCheckout call:
+// redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }
 ```
 
 ---
@@ -126,8 +127,8 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/restaurants/onli
 This is the one shape that differs materially from a Stores cart. Build a line item whose `catalogReference` names the **Orders app** and carries **`operationId` + `menuId` + `sectionId`** in `options`.
 
 ```js
-await currentCart.addToCurrentCart({
-  lineItems: [{
+await currentCartV2.addLineItemsToCurrentCart({
+  catalogItems: [{                                          // Cart V2: `catalogItems`, NOT V1's `lineItems`
     quantity,
     catalogReference: {
       catalogItemId: item._id,                              // the MENU ITEM's _id
@@ -141,7 +142,7 @@ await currentCart.addToCurrentCart({
   }],
 });
 ```
-Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/add-to-current-cart.md?apiView=SDK>
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md?apiView=SDK>
 
 **⚠️ CRITICAL: `options` MUST carry `operationId`, `menuId`, AND `sectionId` — all three.** A restaurant line item is identified by *where in the menu it was ordered from*, not by a variant. Omitting any of the three makes eCommerce unable to resolve the item against the Restaurants catalog — the add fails or the line can't be checked out. This is the restaurant analog of the store's mandatory `variantId`, and it fails the same quiet way.
 
@@ -153,19 +154,19 @@ Optional: `options.onlineOrderingPageUrl` (e.g. `"/online-ordering"`) lets the b
 
 ### Checkout
 
-Create a checkout from the current cart, then redirect the buyer to the hosted checkout (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout).
-Docs: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/create-checkout-from-current-cart.md?apiView=SDK> · <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/get-current-cart.md?apiView=SDK>
+Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout id. Read the current cart, then hand its id to a redirect session (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout).
+Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
 
 ```js
-const checkout = await currentCart.createCheckoutFromCurrentCart({ channelType: currentCart.ChannelType.WEB });
+const { cart } = await currentCartV2.getCurrentCart();   // NOTE: wrapped in { cart } (V1 returned the cart directly)
 const session = await redirects.createRedirectSession({
-  ecomCheckout: { checkoutId: checkout.checkoutId },   // checkout.checkoutId — NOT checkout._id
+  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id — there is no createCheckout call
   callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
 });
 window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL (fulfillment + time slot chosen here)
 ```
 
-**⚠️ `createCheckoutFromCurrentCart` returns `checkout.checkoutId`** (a string), **not** `checkout._id`. Reading `checkout._id` (over-applying the `_id` rule) throws *"Cannot read properties of undefined (reading '_id')"* — the silent checkout crash. The `_id` rule is for read **entities**, not method-return wrappers.
+**⚠️ There is no `createCheckoutFromCurrentCart` in Cart V2.** V2 unifies cart + checkout, so you pass the cart's own `_id` into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` now returns **`{ cart }`** (V1 returned the cart directly) — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
 
 **⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats `http://<same host>` as a different, unlisted origin. If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to `http://` behind Wix's TLS-terminating proxy → the buyer's return redirect **403s** with *"… isn't listed as an allowed redirect domain."* Pass `window.location.origin` from the client into the route (or force the scheme to `https`). Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
 
@@ -173,16 +174,16 @@ window.location.href = session.redirectSession.fullUrl; // the hosted-checkout U
 
 ### Reading the price and the cart
 
-Menu item price is **`item.priceInfo.price`** — a decimal **string** with no currency symbol (see `how-to-code-restaurants.md`; the SDK `PriceInfo` type has only `price`, no `formattedPrice`). A cart line's price is **`lineItem.price.amount`** (also a string). Prefix your own currency in the UI. Cart line images are `wix:image://` identifiers — resolve them with `media.getScaledToFillImageUrl(id, w, h, {})` (4 args), never raw (see the store/menu recipes' image callout).
+Menu item price is **`item.priceInfo.price`** — a decimal **string** with no currency symbol (see `how-to-code-restaurants.md`; the SDK `PriceInfo` type has only `price`, no `formattedPrice`). A cart line's price is **`lineItem.pricing.unitPrice.amount`** (also a raw decimal string — Cart V2 dropped the preformatted line-item price). Prefix your own currency in the UI. Cart line images are `wix:image://` identifiers — resolve them with `media.getScaledToFillImageUrl(id, w, h, {})` (4 args), never raw (see the store/menu recipes' image callout).
 
 ---
 
 ## Conclusion
 A correct Restaurants ordering frontend:
-- imports **`operations` / `fulfillmentMethods` from `@wix/restaurants`** (plus `menus`/`sections`/`items` for display) and **`currentCart` / `redirects`** from `@wix/ecom` / `@wix/redirects`;
+- imports **`operations` / `fulfillmentMethods` from `@wix/restaurants`** (plus `menus`/`sections`/`items` for display) and **`currentCartV2` / `redirects`** from `@wix/ecom` / `@wix/redirects`;
 - uses **`_id`** (never `id`) for the operation, menu, section, and item;
 - reads the **`operationId`** once from `listOperations()` (the `ENABLED`/`default` operation) and reuses it;
 - adds menu items with the **Orders app id `9a5d83fd-…`** (never the Stores id) and `options` carrying **`operationId` + `menuId` + `sectionId`** (all three) — **no `variantId`**;
 - threads `menuId`/`sectionId` from the render context, not a re-lookup;
-- checks out via **`createCheckoutFromCurrentCart` → `checkout.checkoutId` → `redirects`**, with an **`https://` `window.location.origin`** for the callbacks; the hosted checkout collects fulfillment + payment (which needs a premium plan + payment method).
+- checks out by feeding the **current cart's `_id`** (the checkout id in Cart V2) to **`redirects`** — no `createCheckoutFromCurrentCart` step — with an **`https://` `window.location.origin`** for the callbacks; the hosted checkout collects fulfillment + payment (which needs a premium plan + payment method).
 </content>
diff --git a/skills/wix-manage/references/bookings/booking-system-integration-gaps.md b/skills/wix-manage/references/bookings/booking-system-integration-gaps.md
index 159beaa87..8a72cc750 100644
--- a/skills/wix-manage/references/bookings/booking-system-integration-gaps.md
+++ b/skills/wix-manage/references/bookings/booking-system-integration-gaps.md
@@ -125,7 +125,7 @@ Actual Required Flow: Booking API → Ecom Integration → Payment ✓
 
 **Universal Pattern** (Works for ALL Service Types):
 ```
-Create Booking → Extract Booking ID → Use as Catalog Item ID → Create Checkout → Create Order → Process Payment
+Create Booking → Extract Booking ID → Use as Catalog Item ID → Create Cart → Place Order → Process Payment
 ```
 
 ### 2. Identify Service Type-Specific Booking Patterns
@@ -266,26 +266,33 @@ Create calendar events using `POST https://www.wixapis.com/calendar/v3/bulk/even
 
 **MAJOR DISCOVERY**: ALL booking payments use identical ecommerce integration pattern.
 
-**Step 6A: Create Checkout with Booking ID as Catalog Item**
+**Step 6A: Create Cart with Booking ID as Catalog Item**
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout))
+Cart V2 unifies cart and checkout — there is no separate checkout entity, so the created cart's `id` is what later steps use as the cart/checkout id.
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts` ([REST](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart))
 
 ```json
 {
-  "lineItems": [{
+  "catalogItems": [{
     "catalogReference": {
       "catalogItemId": "<BOOKING_ID>",
       "appId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97"
     },
     "quantity": 1
-  }],
-  "channelType": "WEB"
+  }]
 }
 ```
 
-**Step 6B: Create Order for Payment Processing**
+**Step 6B: Place Order for Payment Processing**
+
+First calculate the cart to obtain a price-verification token:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/calculate` — read `summary.priceVerificationToken` from the response.
+
+Then place the order, passing that token:
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder`
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/place-order` (body `{ "priceVerificationToken": "<TOKEN>" }`)
 
 **Critical Architecture Discoveries**:
 - **Automatic ID Transformation**: Booking IDs automatically valid as catalog item IDs
@@ -297,7 +304,7 @@ Create calendar events using `POST https://www.wixapis.com/calendar/v3/bulk/even
 
 **Payment Processing Architecture**:
 ```
-Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
+Booking (CONFIRMED) → Cart → Place Order → Payment Processing (async)
                                               ↓
                                         Messaging System
                                               ↓
@@ -406,7 +413,7 @@ Booking (CONFIRMED) → Checkout → Order → Payment Processing (async)
 * [Standard Booking Flow](https://dev.wix.com/docs/api-reference/business-solutions/bookings/flow-single-service-booking) - Missing payment integration
 * [Create Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking) - No payment processing guidance
 * [Service Types](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/about-service-types) - Missing integration patterns
-* [Ecommerce Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/introduction) - No booking integration mention
+* [Ecommerce Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) - No booking integration mention
 
 **Completely Undocumented**:
 * **Booking→Ecom Integration**: Universal pattern affecting all booking payments
diff --git a/skills/wix-manage/references/bookings/end-to-end-booking-flow.md b/skills/wix-manage/references/bookings/end-to-end-booking-flow.md
index f0056e1a2..ee34be961 100644
--- a/skills/wix-manage/references/bookings/end-to-end-booking-flow.md
+++ b/skills/wix-manage/references/bookings/end-to-end-booking-flow.md
@@ -19,7 +19,7 @@ Step-by-step flow for implementing a complete booking experience using REST APIs
 - **Services API**: [Query Services](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/query-services)
 - **Time Slots V2 API**: [List Availability Time Slots](https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/time-slots-v2/list-availability-time-slots)
 - **Bookings API**: [Create Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking), [Confirm Booking](https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/confirm-booking)
-- **eCommerce API**: [Create Checkout](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/create-checkout)
+- **eCommerce API**: [Create Cart](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart)
 
 ---
 
@@ -226,15 +226,17 @@ Use the `id` and `revision` from the Create Booking response. Set `paymentStatus
 
 **Result**: Booking status changes to `CONFIRMED` and is visible in the booking calendar.
 
-### For online payments: Create checkout
+### For online payments: Create a cart
 
-**4a. Create Checkout**
+Cart V2 unifies cart and checkout — there is no separate checkout entity. The created cart's `id` is what you use for the checkout URL and for placing the order.
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts`
+**4a. Create Cart**
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts`
 
 ```json
 {
-  "lineItems": [
+  "catalogItems": [
     {
       "catalogReference": {
         "catalogItemId": "<BOOKING_ID>",
@@ -242,22 +244,33 @@ Use the `id` and `revision` from the Create Booking response. Set `paymentStatus
       },
       "quantity": 1
     }
-  ],
-  "channelType": "WEB"
+  ]
 }
 ```
 
-Use the booking ID as `catalogItemId` with the Wix Bookings app ID.
+Use the booking ID as `catalogItemId` with the Wix Bookings app ID. Save `cart.id` from the response.
 
 **4b. Get Checkout URL**
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/getCheckoutUrl`
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/get-checkout-url`
 
 Redirect the user to the returned `checkoutUrl`. After payment, the booking is automatically confirmed.
 
-**4c. Create Order (alternative, server-to-server)**
+**4c. Place Order (alternative, server-to-server)**
+
+First calculate the cart to get a price-verification token:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/calculate`
+
+Save `summary.priceVerificationToken` from the response, then place the order:
+
+**Endpoint**: `POST https://www.wixapis.com/ecom/v2/carts/{cartId}/place-order`
 
-**Endpoint**: `POST https://www.wixapis.com/ecom/v1/checkouts/{checkoutId}/createOrder`
+```json
+{
+  "priceVerificationToken": "<PRICE_VERIFICATION_TOKEN>"
+}
+```
 
 Creates an order directly without redirect.
 
diff --git a/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md b/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md
index e83035d4e..4e5d352c1 100644
--- a/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md
+++ b/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md
@@ -73,7 +73,7 @@ POST https://www.wixapis.com/wix-data/v2/collections/add-plugin
 Most Wix sites with Stores, Bookings, or similar apps already have eCommerce installed. Check by querying the Cart API:
 
 ```
-POST https://www.wixapis.com/ecom/v1/carts
+POST https://www.wixapis.com/ecom/v2/carts
 ```
 
 ## Step 3: Use Catalog Items in Cart
@@ -87,12 +87,12 @@ e593b0bd-b783-45b8-97c2-873d42aacaf4
 ### Add CMS Catalog Item to Cart
 
 ```
-POST https://www.wixapis.com/ecom/v1/carts/{cartId}/add-to-cart
+POST https://www.wixapis.com/ecom/v2/carts/{cartId}/add-line-items
 ```
 
 ```json
 {
-  "lineItems": [
+  "catalogItems": [
     {
       "catalogReference": {
         "appId": "e593b0bd-b783-45b8-97c2-873d42aacaf4",
@@ -133,4 +133,4 @@ CMS Catalogs are best for simple product catalogs. For complex eCommerce needs,
 
 - [CMS Schema Management](cms-schema-management.md)
 - [CMS Data Operations](cms-data-items-crud.md)
-- [Wix Cart API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/introduction)
+- [Wix Cart API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/introduction)
diff --git a/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js b/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js
index 78853d243..6e4201559 100644
--- a/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js
+++ b/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js
@@ -101,31 +101,33 @@ export async function createBooking(slot, contactDetails, { totalParticipants =
 }
 
 /**
- * Create an eCommerce checkout for a created booking and return the hosted checkout URL.
+ * Create an eCommerce cart for a created booking and return the hosted checkout URL.
  * Redirect the buyer there (window.location.href = ...). On return, the booking is confirmed.
  * Throws if no redirect URL is produced.
- * https://dev.wix.com/docs/rest/business-solutions/e-commerce/checkout/create-checkout.md
+ *
+ * Cart V2 unifies cart + checkout: there is no separate checkout entity, so the created
+ * cart's id IS the checkout id fed to the redirect session.
+ * https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
  * @param {string} bookingId  booking.id from createBooking().
  * @returns {Promise<string>} The hosted-checkout URL to redirect to.
  */
 export async function checkoutBooking(bookingId) {
   if (!bookingId) throw new Error("checkoutBooking requires a bookingId.");
 
-  const checkoutRes = await wixApiRequest("/ecom/v1/checkouts", {
+  const cartRes = await wixApiRequest("/ecom/v2/carts", {
     method: "POST",
     body: {
-      channelType: "WEB",
-      lineItems: [
+      catalogItems: [
         { quantity: 1, catalogReference: { appId: BOOKINGS_APP_ID, catalogItemId: bookingId } },
       ],
     },
   });
-  const checkoutId = checkoutRes?.checkout?.id;
-  if (!checkoutId) throw new Error("Failed to create a checkout for the booking.");
+  const cartId = cartRes?.cart?.id;
+  if (!cartId) throw new Error("Failed to create a cart for the booking.");
 
   const redirect = await wixApiRequest("/headless/v1/redirect-session", {
     method: "POST",
-    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+    body: { ecomCheckout: { checkoutId: cartId }, callbacks: { postFlowUrl: window.location.href } },
   });
   const url = redirect?.redirectSession?.fullUrl;
   if (!url) throw new Error("Failed to create the checkout redirect session.");
diff --git a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
index 89f8b9f99..119fa77bf 100644
--- a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
@@ -83,7 +83,7 @@ building the UI — they describe the key fields and link to the full reference
   a menu in their Wix dashboard. Never invent menu items.
 
 ## Hard rules (do not violate)
-- ✅ Order ONLY through the cart: `addItemToCart()` → `checkout()` (`create-checkout` →
+- ✅ Order ONLY through the cart: `addItemToCart()` → `checkout()` (cart id IS the checkout id →
   `/headless/v1/redirect-session` `fullUrl`), then redirect.
 - ❌ Never hand-build `/checkout`, ordering, or reservation URLs.
 - ❌ Never mock menus, items, prices, operations, locations, or time slots — render live Wix data or
diff --git a/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js b/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
index c7ac7fa2a..5a319ec28 100644
--- a/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
+++ b/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
@@ -11,15 +11,15 @@ 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} — also the checkout id in V2 (pass straight into the redirect session),
  *   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} — quantity that will actually be purchased,
+ *   lineItems[].source.catalogReference.catalogItemId {string} — the ordered item's GUID,
+ *   lineItems[].name.original {string},
+ *   lineItems[].pricing.unitPrice.amount {string} — raw decimal, after discounts (NO currency symbol in V2 — format 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-cart.md
  */
 
 // Wix Restaurants Orders app id — required in catalogReference when adding menu items to the eCom cart.
@@ -61,7 +61,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 +74,15 @@ 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}).`);
+  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 +90,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 +99,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,31 +124,28 @@ export async function removeFromCart(lineItemId) {
 }
 
 /**
- * Create a checkout from the current cart and return the Wix-hosted checkout URL.
+ * Send the current cart to the hosted Wix checkout and return the redirect URL.
  * Throws on empty cart, unavailable lines, or a missing redirect URL.
  * Redirect with: window.location.href = await checkout()
+ *
+ * Cart V2 has no separate checkout entity — the cart id IS the checkout id, so there is no
+ * "create checkout" step. We still create a redirect session so the visitor/member session
+ * carries across to the Wix-hosted checkout page on its own domain.
  * @returns {Promise<string>}
  */
 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.");
-
   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.");

From ced9373ac2a90c427ee118bd99159e8ff7816b41 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 10:55:51 +0300
Subject: [PATCH 04/31] docs(ecom): fix missed currentCart import in
 restaurant-orders non-Astro example

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-restaurant-orders.md  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index 6aa581410..cc413e9ad 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -40,7 +40,7 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
   ```js
   import { createClient, OAuthStrategy } from '@wix/sdk';
   import { menus, sections, items, operations, fulfillmentMethods } from '@wix/restaurants';
-  import { currentCart } from '@wix/ecom';
+  import { currentCartV2 } from '@wix/ecom';
   import { redirects } from '@wix/redirects';
 
   const client = createClient({

From 50a89fb497dfe0fbc50137d18131239ae6e5075b Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 11:12:56 +0300
Subject: [PATCH 05/31] docs(ecom): fix membership shape + money-format notes
 from independent review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- pricing-plans: apply membership via membershipPayment.existingMembership
  { appId, membershipId } (selectedMembership is deprecated); correct the
  eligibility source (paymentSummary.memberships = applied, not eligible —
  use member active-orders + live coverage)
- clarify Cart V2 has NO preformatted money (summary is ConvertedMoney too);
  amount=site currency, convertedAmount=display

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-a-store.md |  2 +-
 .../inline-recipes/how-to-code-pricing-plans.md      | 12 ++++++------
 .../inline-recipes/how-to-code-restaurant-orders.md  |  2 +-
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index 92644481f..8c332010e 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -74,7 +74,7 @@ variant = {
 
 // currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: wrapped in { cart } (V1 returned the cart directly)
 lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
-// price → pricing.unitPrice.amount (raw string, NO currency symbol in V2 — format it yourself); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
+// price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
 // Cart V2 has NO checkout entity — the cart's _id IS the checkout id; there is no createCheckout call:
 // redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index f5bd6c97e..591cb6c5f 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -23,7 +23,7 @@ A contract for the **frontend code** of a pricing-plans site: showing the plans
 | List / read plans (the grid) | `@wix/pricing-plans` | `plansV3` (Plans V3 — `queryPlans`, `getPlan`) |
 | Order a plan + read a member's orders | `@wix/pricing-plans` | `orders` (`createOnlineOrder`, `memberListOrders`, `memberGetOrder`) |
 | Member login / current member | `@wix/members` + `@wix/sdk` auth | see the members recipe (`getCurrentMember`, `loggedIn()`) |
-| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `currentCartV2` (line-item `selectedMembership`) — see *Booking with a membership* |
+| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `currentCartV2` (line-item `membershipPayment`) — see *Booking with a membership* |
 
 **Never** import `@wix/site-pricing-plans` in headless code, and don't reach for a V1 `plans`-collection query — Plans V3 (`queryPlans` → `pricingVariants`) is the shape the seed creates.
 
@@ -98,13 +98,13 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
-3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Cart V2 unified cart + checkout, so membership selection moved off the old checkout-entity `membershipOptions` and onto the line item's `selectedMembership`:
-   - **Eligible memberships** — the member's plans that can cover the line item — come from `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships[]`. **⚠️ VERIFY IN A LIVE BUILD:** confirm this is the field a headless member token reads (in Checkout V1 the equivalent `membershipOptions.eligibleMemberships` was tagged "reserved for internal use"; use the fallback below if it comes back empty).
-   - **Apply one** by setting the line item's `selectedMembership` (`{ id, appId }`) via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, selectedMembership: { id, appId } }] })`. When the membership covers the full price, the calculated `payNow`/total drops to `0`. **⚠️ VERIFY the exact request nesting in a live build** — the mapping places it under the line item's `paymentConfig.selectedMembership`.
+3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Cart V2 unified cart + checkout, so membership selection moved off the old checkout-entity `membershipOptions` and onto the line item, set via `updateLineItemsInCurrentCart`:
+   - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { appId, membershipId } } }] })`. (Use `membershipPayment` — the older `selectedMembership` field is **deprecated**.) When the membership covers the full price, the calculated total drops to `0`.
+   - **Which plan to apply / eligibility:** there is **no** dedicated "eligible memberships for this line item" read on the current cart in V2 (the Checkout V1 `membershipOptions.eligibleMemberships` list has no direct analog — `calculateCurrentCart` → `summary.paymentSummary.memberships` reports memberships **already applied/charged**, not candidates). Determine eligibility from the member's active plans + live coverage instead — see the LIVE-read note below. **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
    Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md?apiView=SDK>
 4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
 
-- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. **Preferred:** read the eligible plans from `currentCartV2.calculateCurrentCart()` → `summary.paymentSummary.memberships` — the plans that can cover *this* line item, computed server-side from live coverage. (**VERIFY IN A LIVE BUILD** whether a headless member token reads it client-side.) **Fallback if that comes back empty for a member token:** list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `selectedMembership` from whichever read succeeds.
+- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `membershipPayment.existingMembership` from the matched plan.
 - **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
 - **Credit/session plans:** for a limited (non-unlimited) plan, `eligibleMemberships[].credits.remaining` matters — `0` remaining is not eligible. An unlimited plan (seed `price:"0"`) has no credit ceiling.
 
@@ -121,4 +121,4 @@ A correct Pricing Plans frontend:
 - imports **`@wix/pricing-plans`** (`plansV3`, `orders`) — **never** `@wix/site-pricing-plans` (its `startOnlinePurchase` is Wix-site page-code, not headless);
 - lists the grid publicly with **`plansV3.queryPlans().eq('visibility','PUBLIC')`**, reads **`plan._id`** and price from **`pricingVariants[].pricingStrategies[].flatRate.amount`** (decimal string) — never a top-level `price` — and only shows a buy button on `buyable` plans;
 - treats **subscribe and my-subscription as login-gated** (the hard members dependency), orders with **`orders.createOnlineOrder(planId)`** (no `onBehalf`, no elevate), renders free plans as `ACTIVE` immediately, and drives paid plans through a payment redirect (**exact headless redirect to be confirmed in a live build**) — and **stops at the redirect**: no payments-account connect, no order activation / mark-as-paid from code (see *Out of scope*);
-- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom Cart V2 line item** (`selectedMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.
+- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom Cart V2 line item** (`membershipPayment.existingMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index cc413e9ad..14824128f 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -81,7 +81,7 @@ item = { _id, name, priceInfo: { price } }   // price is a decimal STRING; _id 
 
 // currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: wrapped in { cart } (V1 returned the cart directly)
 lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
-// price → pricing.unitPrice.amount (raw string, NO currency symbol in V2 — format it yourself); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
+// price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
 // Cart V2 has NO checkout entity — the cart's _id IS the checkout id; there is no createCheckout call:
 // redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }

From 9b19a0172652f1c9d4f3163f30d070d5939b207b Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 11:41:50 +0300
Subject: [PATCH 06/31] docs(ecom): fix attributes.image doc shape (2nd review)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

V2 attributes.image is a scalar wix:image:// string, not { url } — the doc
comment in wix-store-cart.js kept the V1 .url accessor. Confirmed against
ItemAttributes typing + CartV2ToV1Mappers.scala.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../wix-vibe-headless/references/storefront/wix-store-cart.js   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
index 0cfd706db..59914a00c 100644
--- a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
+++ b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
@@ -21,7 +21,7 @@ const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
  *   lineItems[].pricing.breakdown.fullPrice.amount {string} — before discount (strikethrough),
  *   lineItems[].attributes.descriptionLines {array} — human-readable option/modifier labels:
  *     [{ name: { original }, plainText: { original } OR colorInfo: { original, code } }],
- *   lineItems[].attributes.image.url {string},
+ *   lineItems[].attributes.image {string} — a wix:image:// identifier (resolve client-side; V2 has no nested .url),
  *   lineItems[].status {string} — "IN_STOCK"|"PARTIALLY_IN_STOCK"|"OUT_OF_STOCK"|"REMOVED_FROM_CATALOG"
  *
  * Note: display totals (subtotal, tax, formatted amounts) are NOT stored on the cart in V2.

From a34b1bfa78d02ac0bb94e20da7d8b9456f7d0a5c Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 11:54:32 +0300
Subject: [PATCH 07/31] =?UTF-8?q?docs(ecom):=203rd-review=20minors=20?=
 =?UTF-8?q?=E2=80=94=20currentCart=20prose=20+=20membership=20caveat?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- restaurant-orders: last V1 `currentCart` in Astro prose -> currentCartV2
- pricing-plans: note both membership-apply fields are unstable in the SDK
  typings (selectedMembership deprecated/past-removal; membershipPayment @internal)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-pricing-plans.md      | 2 +-
 .../references/inline-recipes/how-to-code-restaurant-orders.md  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 591cb6c5f..88c6f400c 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -99,7 +99,7 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
 3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Cart V2 unified cart + checkout, so membership selection moved off the old checkout-entity `membershipOptions` and onto the line item, set via `updateLineItemsInCurrentCart`:
-   - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { appId, membershipId } } }] })`. (Use `membershipPayment` — the older `selectedMembership` field is **deprecated**.) When the membership covers the full price, the calculated total drops to `0`.
+   - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { appId, membershipId } } }] })`. When the membership covers the full price, the calculated total drops to `0`. **⚠️ Both membership-apply fields are currently unstable in the SDK typings** — the older `selectedMembership` is **deprecated** (past its removal date) and `membershipPayment` is marked **`@internal`** — so confirm the supported public field with the eCom team / in a live build before shipping this path.
    - **Which plan to apply / eligibility:** there is **no** dedicated "eligible memberships for this line item" read on the current cart in V2 (the Checkout V1 `membershipOptions.eligibleMemberships` list has no direct analog — `calculateCurrentCart` → `summary.paymentSummary.memberships` reports memberships **already applied/charged**, not candidates). Determine eligibility from the member's active plans + live coverage instead — see the LIVE-read note below. **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
    Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md?apiView=SDK>
 4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index 14824128f..34b125d9d 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -30,7 +30,7 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 | Redirect to hosted checkout | `@wix/redirects` | `redirects` |
 
 **Auth / client — framework split:**
-- **Astro (Wix-managed):** authentication is ambient. Call `operations` / `fulfillmentMethods` / `currentCart` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
+- **Astro (Wix-managed):** authentication is ambient. Call `operations` / `fulfillmentMethods` / `currentCartV2` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
   ```js
   import { operations, fulfillmentMethods } from '@wix/restaurants';
   import { currentCartV2 } from '@wix/ecom';

From 00961ecf525b9a8e602fc610cded6f31cb7c01e4 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 12:05:10 +0300
Subject: [PATCH 08/31] =?UTF-8?q?docs(ecom):=204th-review=20nit=20?=
 =?UTF-8?q?=E2=80=94=20match=20sibling=20doc-link=20style=20(drop=20.md)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

COMMON-EVENTS cart rows used .md?apiView=SDK; siblings use ?apiView=SDK.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 skills/wix-app/references/backend-event/COMMON-EVENTS.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/skills/wix-app/references/backend-event/COMMON-EVENTS.md b/skills/wix-app/references/backend-event/COMMON-EVENTS.md
index 7b7d0d5b9..4cdba5b7f 100644
--- a/skills/wix-app/references/backend-event/COMMON-EVENTS.md
+++ b/skills/wix-app/references/backend-event/COMMON-EVENTS.md
@@ -21,8 +21,8 @@ Order events use **`@wix/ecom`** (namespace `orders`). Order **refund** events a
 | Order canceled | `import { orders } from "@wix/ecom"` | `orders.onOrderCanceled(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCanceled](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-canceled?apiView=SDK) |
 | Refund created | `import { refunds } from "@wix/payments"` | `refunds.onRefundCreated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundCreated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-created?apiView=SDK) |
 | Refund updated | `import { refunds } from "@wix/payments"` | `refunds.onRefundUpdated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundUpdated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-updated?apiView=SDK) |
-| Cart created | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-created.md?apiView=SDK) |
-| Cart updated | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-updated.md?apiView=SDK) |
+| Cart created | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-created?apiView=SDK) |
+| Cart updated | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-updated?apiView=SDK) |
 
 ## Bookings Events
 

From 70c32e3c40568ea7747beece9388767d73109f68 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 14:46:59 +0300
Subject: [PATCH 09/31] docs(ecom): membership uses public selectedMembership
 (compiler-verified)

A type harness compiled against the PUBLIC @wix/ecom types shows membershipPayment
is @internal (absent from public LineItemUpdate). selectedMembership { newMembership:
{ _id, appId } } is the only public (deprecated) field. Reverted the recipe to it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../inline-recipes/how-to-code-pricing-plans.md           | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 88c6f400c..4e829ead5 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -23,7 +23,7 @@ A contract for the **frontend code** of a pricing-plans site: showing the plans
 | List / read plans (the grid) | `@wix/pricing-plans` | `plansV3` (Plans V3 — `queryPlans`, `getPlan`) |
 | Order a plan + read a member's orders | `@wix/pricing-plans` | `orders` (`createOnlineOrder`, `memberListOrders`, `memberGetOrder`) |
 | Member login / current member | `@wix/members` + `@wix/sdk` auth | see the members recipe (`getCurrentMember`, `loggedIn()`) |
-| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `currentCartV2` (line-item `membershipPayment`) — see *Booking with a membership* |
+| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `currentCartV2` (line-item `selectedMembership`) — see *Booking with a membership* |
 
 **Never** import `@wix/site-pricing-plans` in headless code, and don't reach for a V1 `plans`-collection query — Plans V3 (`queryPlans` → `pricingVariants`) is the shape the seed creates.
 
@@ -99,12 +99,12 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
 3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Cart V2 unified cart + checkout, so membership selection moved off the old checkout-entity `membershipOptions` and onto the line item, set via `updateLineItemsInCurrentCart`:
-   - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { appId, membershipId } } }] })`. When the membership covers the full price, the calculated total drops to `0`. **⚠️ Both membership-apply fields are currently unstable in the SDK typings** — the older `selectedMembership` is **deprecated** (past its removal date) and `membershipPayment` is marked **`@internal`** — so confirm the supported public field with the eCom team / in a live build before shipping this path.
+   - **Apply one** by setting the line item's `selectedMembership` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, selectedMembership: { newMembership: { _id, appId } } }] })`. When the membership covers the full price, the calculated total drops to `0`. **⚠️ Membership-on-cart is unstable in the SDK typings:** `selectedMembership` is the only field present in the **public** `@wix/ecom` types (verified: it type-checks; the shape is `{ newMembership: { _id, appId } }`) but is marked **deprecated**; its intended replacement `membershipPayment` is **`@internal`** and does NOT exist on the public `LineItemUpdate` (it fails to type-check for consumers). Use `selectedMembership` for now, and confirm the supported public field with the eCom team before shipping.
    - **Which plan to apply / eligibility:** there is **no** dedicated "eligible memberships for this line item" read on the current cart in V2 (the Checkout V1 `membershipOptions.eligibleMemberships` list has no direct analog — `calculateCurrentCart` → `summary.paymentSummary.memberships` reports memberships **already applied/charged**, not candidates). Determine eligibility from the member's active plans + live coverage instead — see the LIVE-read note below. **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
    Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md?apiView=SDK>
 4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
 
-- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `membershipPayment.existingMembership` from the matched plan.
+- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `selectedMembership.newMembership` from the matched plan.
 - **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
 - **Credit/session plans:** for a limited (non-unlimited) plan, `eligibleMemberships[].credits.remaining` matters — `0` remaining is not eligible. An unlimited plan (seed `price:"0"`) has no credit ceiling.
 
@@ -121,4 +121,4 @@ A correct Pricing Plans frontend:
 - imports **`@wix/pricing-plans`** (`plansV3`, `orders`) — **never** `@wix/site-pricing-plans` (its `startOnlinePurchase` is Wix-site page-code, not headless);
 - lists the grid publicly with **`plansV3.queryPlans().eq('visibility','PUBLIC')`**, reads **`plan._id`** and price from **`pricingVariants[].pricingStrategies[].flatRate.amount`** (decimal string) — never a top-level `price` — and only shows a buy button on `buyable` plans;
 - treats **subscribe and my-subscription as login-gated** (the hard members dependency), orders with **`orders.createOnlineOrder(planId)`** (no `onBehalf`, no elevate), renders free plans as `ACTIVE` immediately, and drives paid plans through a payment redirect (**exact headless redirect to be confirmed in a live build**) — and **stops at the redirect**: no payments-account connect, no order activation / mark-as-paid from code (see *Out of scope*);
-- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom Cart V2 line item** (`membershipPayment.existingMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.
+- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom Cart V2 line item** (`selectedMembership.newMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.

From f940698f07b464473fba0e44592b5f32caec6ae6 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 6 Aug 2026 16:16:56 +0300
Subject: [PATCH 10/31] docs(replatform): fully align eCommerce taxonomy to
 Cart V2
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Not just the doc link — the conceptual model. Cart V2 unifies cart + checkout,
so:
- `cart` row now describes the unified Cart V2 entity (whole purchase flow)
- `checkout` row: no longer a separate Wix entity; folded into the cart, map
  source checkout state onto `cart` (Checkout V1 removed 2027-02-01)
- `current-cart` -> Cart V2 (session-scoped), link to cart-v2
- entity/state bullets + "canonical target" prose updated to reflect unification

Keeps checkout as a taxonomy concept (source systems still have it) but points
it at Cart V2, so the replatform mapper stays usable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../rp-mapper/wix-business-solutions-taxonomy.md   | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index 3c69ebb7b..649b4c854 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -25,15 +25,15 @@ This distinction must stay explicit in mapper output.
 It owns the purchase flow and operational commerce entities that are reused across multiple vertical apps.
 
 Typical `eCommerce` entities:
-- carts
-- checkouts
+- carts (Cart V2 — the unified cart+checkout entity)
+- checkouts (folded into the cart in Cart V2; map onto `cart`)
 - orders
 - order billing / refunds
 - payment and fulfillment state tied to orders
 
 Use `eCommerce` when the source data is about:
 - cart contents
-- checkout state
+- checkout state (part of the cart in Cart V2)
 - order lifecycle
 - fulfillment and payment operations
 - cross-vertical commerce operations that are not specific to a single catalog app
@@ -90,15 +90,15 @@ Main page:
 - [Integrating with Wix's Business Solutions](https://dev.wix.com/docs/build-apps/get-started/overview/integrating-with-wix-s-business-solutions)
 
 Short description:
-- Shared commerce platform for purchase flow and order operations. It is the canonical target for carts, checkouts, and orders, even when catalog data originates in a vertical app such as Stores or Bookings.
+- Shared commerce platform for purchase flow and order operations. It is the canonical target for carts (Cart V2, which now also covers checkout) and orders, even when catalog data originates in a vertical app such as Stores or Bookings.
 
 Primary entities:
 
 | Entity | What it does | Docs |
 | --- | --- | --- |
-| `cart` | First phase of the purchase flow; holds line items, buyer references, discounts, and pricing context before checkout | [About the eCommerce Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
-| `current-cart` | Visitor/member scoped cart used in live purchase flows | [About the eCommerce Current Cart API](https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/introduction) |
-| `checkout` | Second phase of purchase flow; holds calculated prices, tax, billing, shipping, and discount state before order creation | [About the eCommerce Checkout API](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/introduction) |
+| `cart` | The unified purchase-flow entity (Cart V2): holds line items, buyer/contact info, discounts, delivery, billing, and payment context all the way through placing the order. Cart V2 replaces the old separate Cart V1 + Checkout V1 model. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
+| `current-cart` | Visitor/member (session) scoped Cart V2 used in live purchase flows — same entity as `cart`, addressed by the shopper's session instead of a cart id. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
+| `checkout` | Not a separate entity in Wix's current model: Cart V2 folds checkout (calculated prices, tax, billing, shipping, discount state) into the cart. Map a source system's checkout state onto `cart`. Legacy Checkout V1 still exists but is removed on 2027-02-01. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 

From 33fb5253659906ffacb93bbc2dad092a8c90763f Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 15:45:22 +0300
Subject: [PATCH 11/31] docs(ecom): add price-formatting guidance for Cart V2
 (no preformatted amount)

V1 gave a ready `formattedAmount`; V2 cart money is raw ConvertedMoney, so the
recipes now tell users HOW to format, not just "format it yourself":
- how-to-code-a-store: new "Formatting cart prices" section with an
  Intl.NumberFormat helper keyed off the cart's currencyCode
- how-to-code-restaurant-orders: concrete formatting example + cross-ref
- wix-vibe-headless/SKILL.md: Cart V2 ConvertedMoney caveat in the canonical
  "Money/price fields" note (distinguish from the {value,currency,formattedValue}
  shape used by Stores/Bookings/Events)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../inline-recipes/how-to-code-a-store.md        | 16 ++++++++++++++++
 .../how-to-code-restaurant-orders.md             |  2 +-
 skills/wix-vibe-headless/SKILL.md                |  1 +
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index 8c332010e..3c0a458a6 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -189,6 +189,22 @@ window.location.href = session.redirectSession.fullUrl; // the hosted-checkout U
 
 **⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats **`http://<same host>` as a different, unlisted origin**. When the buyer returns from the hosted checkout (e.g. clicks "Continue Browsing"), the redirect goes through the allowlist — and an `http://` `postFlowUrl` **403s** with *"… isn't listed as an allowed redirect domain."* If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to **`http://`** behind Wix's TLS-terminating proxy → guaranteed 403 on return. So **pass `window.location.origin` from the client** into the route (don't read the origin off the request), or force the scheme to `https`. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
 
+### Formatting cart prices (Cart V2 has no preformatted amount)
+
+**Product** prices from `productsV3` still carry a ready-to-show `actualPriceRange.minValue.formattedAmount` — use it directly. But **Cart V2 money does not**: every cart amount — line-item `pricing.unitPrice` / `pricing.totalPrice` **and** the `estimateCurrentCart`/`calculateCart` `summary.priceSummary.*` — is a `ConvertedMoney` `{ amount, convertedAmount }` with **no** formatted string. So once items are in the cart, you format the price yourself. The currency isn't on the money object; read it from the cart (`cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode`), and use `convertedAmount` (buyer's display currency) when present, else `amount` (site currency):
+
+```js
+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));
+}
+// e.g. line item: formatCartMoney(item.pricing.totalPrice, cart)
+//      subtotal:  formatCartMoney(estimate.summary.priceSummary.subtotal, cart)
+```
+
+Never hardcode `$` or assume USD — stores run in EUR/GBP too.
+
 ### Showing stock state
 
 Read the **V3** inventory fields: product-level in-stock is `product.inventory.availabilityStatus` (`"IN_STOCK"`); variant-level is `variant.inventoryStatus.inStock`. Reading the V1 inventory field on V3 data returns `undefined` → everything renders out-of-stock (the all-OOS bug). These come from `productsV3` / `readOnlyVariantsV3`, not the V1 module.
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index 34b125d9d..e2feef2ab 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -174,7 +174,7 @@ window.location.href = session.redirectSession.fullUrl; // the hosted-checkout U
 
 ### Reading the price and the cart
 
-Menu item price is **`item.priceInfo.price`** — a decimal **string** with no currency symbol (see `how-to-code-restaurants.md`; the SDK `PriceInfo` type has only `price`, no `formattedPrice`). A cart line's price is **`lineItem.pricing.unitPrice.amount`** (also a raw decimal string — Cart V2 dropped the preformatted line-item price). Prefix your own currency in the UI. Cart line images are `wix:image://` identifiers — resolve them with `media.getScaledToFillImageUrl(id, w, h, {})` (4 args), never raw (see the store/menu recipes' image callout).
+Menu item price is **`item.priceInfo.price`** — a decimal **string** with no currency symbol (see `how-to-code-restaurants.md`; the SDK `PriceInfo` type has only `price`, no `formattedPrice`). A cart line's price is **`lineItem.pricing.unitPrice`** / **`pricing.totalPrice`** — a `ConvertedMoney` `{ amount, convertedAmount }`; Cart V2 dropped the preformatted line-item price, so format it yourself. The currency lives on the cart, not the money object — format from `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode` (see the *Formatting cart prices* section of `how-to-code-a-store.md` for the exact `Intl.NumberFormat` helper), e.g. `new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(Number(pricing.totalPrice.convertedAmount ?? pricing.totalPrice.amount))`. Cart line images are `wix:image://` identifiers — resolve them with `media.getScaledToFillImageUrl(id, w, h, {})` (4 args), never raw (see the store/menu recipes' image callout).
 
 ---
 
diff --git a/skills/wix-vibe-headless/SKILL.md b/skills/wix-vibe-headless/SKILL.md
index f1a899d15..0298fc89b 100644
--- a/skills/wix-vibe-headless/SKILL.md
+++ b/skills/wix-vibe-headless/SKILL.md
@@ -46,6 +46,7 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
   formattedValue }`. Render **`formattedValue`** (it already includes the currency symbol), or
   fall back to building from `value` + `currency`. **Never** drop the object straight into the UI
   or treat it as a number/string — that renders `[object Object]` or a bare unformatted number.
+  - **Cart V2 is the exception** — its money is a different shape, `ConvertedMoney { amount, convertedAmount }`, with **no `formattedValue`** and **no currency on the object**. Read the currency from the cart (`cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode`) and format the amount yourself: `new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(Number(money.convertedAmount ?? money.amount))`. Applies to line-item `pricing.*` and the calculate/estimate `summary.priceSummary.*`.
 - **Visitor token = identity.** `wix-client.js` mints an anonymous visitor token, persists the
   **refresh token to `localStorage`**, and refreshes on expiry. That token IS the identity of
   the cart / reservation / member session — **never re-mint anonymously per load** or the cart

From 56772ee5878a49ddcaed8f3f0b49636aaab9ac4b Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 16:53:47 +0300
Subject: [PATCH 12/31] docs(ecom): fix calculateCart -> calculateCurrentCart
 in store recipe

The store recipe is a current-cart (visitor-session) flow on currentCartV2,
which exposes calculateCurrentCart; calculateCart is the cartId-based method on
the separate cartV2 module. Caught by independent review against the public types.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-a-store.md            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index 3c0a458a6..c0cc2743a 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -191,7 +191,7 @@ window.location.href = session.redirectSession.fullUrl; // the hosted-checkout U
 
 ### Formatting cart prices (Cart V2 has no preformatted amount)
 
-**Product** prices from `productsV3` still carry a ready-to-show `actualPriceRange.minValue.formattedAmount` — use it directly. But **Cart V2 money does not**: every cart amount — line-item `pricing.unitPrice` / `pricing.totalPrice` **and** the `estimateCurrentCart`/`calculateCart` `summary.priceSummary.*` — is a `ConvertedMoney` `{ amount, convertedAmount }` with **no** formatted string. So once items are in the cart, you format the price yourself. The currency isn't on the money object; read it from the cart (`cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode`), and use `convertedAmount` (buyer's display currency) when present, else `amount` (site currency):
+**Product** prices from `productsV3` still carry a ready-to-show `actualPriceRange.minValue.formattedAmount` — use it directly. But **Cart V2 money does not**: every cart amount — line-item `pricing.unitPrice` / `pricing.totalPrice` **and** the `estimateCurrentCart`/`calculateCurrentCart` `summary.priceSummary.*` — is a `ConvertedMoney` `{ amount, convertedAmount }` with **no** formatted string. So once items are in the cart, you format the price yourself. The currency isn't on the money object; read it from the cart (`cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode`), and use `convertedAmount` (buyer's display currency) when present, else `amount` (site currency):
 
 ```js
 function formatCartMoney(money, cart) {

From 6d70f4131d151285370b4e0695a1fa6f835ec468 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 17:12:11 +0300
Subject: [PATCH 13/31] docs(ecom): name the entity "cart", not "checkout" (V2
 unification)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Editorial pass so the docs stop invoking the old two-entity model:
- add a "One entity now" note to the reader-facing recipes + vibe INSTRUCTIONS
  (cart V2 is the evolution of cart+checkout; say "cart" for the entity,
  "checkout" only for the hosted checkout page)
- rp-mapper taxonomy: drop the phantom `checkout` PRIMARY-ENTITY row (it's not a
  separate Wix entity in V2); move source-checkout→cart guidance to Mapper notes
- wix-manage booking/cms: retire stale "create checkout and order" /
  "checkout/order pattern" / "Cart and Checkout APIs" entity phrasing -> cart
Kept: the hosted-checkout page/redirect wording, literal identifiers
(getCheckoutUrl, ecomCheckout, checkout()), and intentional V1->V2 contrast.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 replatform/rp-mapper/wix-business-solutions-taxonomy.md     | 5 ++---
 .../references/inline-recipes/how-to-code-a-store.md        | 2 ++
 .../references/inline-recipes/how-to-code-pricing-plans.md  | 2 ++
 .../inline-recipes/how-to-code-restaurant-orders.md         | 2 ++
 .../references/bookings/booking-system-integration-gaps.md  | 6 +++---
 .../references/cms/cms-ecommerce-catalog-integration.md     | 2 +-
 skills/wix-vibe-headless/SKILL.md                           | 4 ++++
 .../wix-vibe-headless/references/bookings/INSTRUCTIONS.md   | 5 +++++
 .../references/restaurants/INSTRUCTIONS.md                  | 5 +++++
 .../wix-vibe-headless/references/storefront/INSTRUCTIONS.md | 5 +++++
 10 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index 649b4c854..0dfdebb62 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -26,14 +26,13 @@ It owns the purchase flow and operational commerce entities that are reused acro
 
 Typical `eCommerce` entities:
 - carts (Cart V2 — the unified cart+checkout entity)
-- checkouts (folded into the cart in Cart V2; map onto `cart`)
 - orders
 - order billing / refunds
 - payment and fulfillment state tied to orders
 
 Use `eCommerce` when the source data is about:
 - cart contents
-- checkout state (part of the cart in Cart V2)
+- checkout state (maps onto the cart — unified into Cart V2)
 - order lifecycle
 - fulfillment and payment operations
 - cross-vertical commerce operations that are not specific to a single catalog app
@@ -98,11 +97,11 @@ Primary entities:
 | --- | --- | --- |
 | `cart` | The unified purchase-flow entity (Cart V2): holds line items, buyer/contact info, discounts, delivery, billing, and payment context all the way through placing the order. Cart V2 replaces the old separate Cart V1 + Checkout V1 model. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `current-cart` | Visitor/member (session) scoped Cart V2 used in live purchase flows — same entity as `cart`, addressed by the shopper's session instead of a cart id. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
-| `checkout` | Not a separate entity in Wix's current model: Cart V2 folds checkout (calculated prices, tax, billing, shipping, discount state) into the cart. Map a source system's checkout state onto `cart`. Legacy Checkout V1 still exists but is removed on 2027-02-01. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
 Mapper notes:
+- **A source system's separate "checkout" has no distinct Wix target.** Cart V2 unifies cart and checkout into one entity, so map source checkout state (calculated prices, tax, billing, shipping, discounts) onto `cart`, not a separate entity.
 - If the source platform exposes products and orders in one model, split catalog entities into the vertical app and transaction entities into `ecommerce`.
 - If the source has historical orders but no cart or checkout history, map directly to `order` and document missing pre-purchase state.
 
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index c0cc2743a..adfc9f043 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -10,6 +10,8 @@ A concise contract for writing the **frontend code** of a storefront against a C
 
 > **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the single most common source of the cart-killing `product.id` bug (see the `_id` rule under *Listing products*). Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
 
+> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+
 ---
 
 ## The modules and the client (read this first)
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 4e829ead5..bd28ad850 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -96,6 +96,8 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/or
 
 This is the payoff of the seed's STEP 2: a member who holds a plan that **covers** a service books it **with the membership** instead of paying per booking. Build the normal Bookings flow from **`how-to-code-bookings.md`** (list services → pick a slot → collect the form → `createBooking` → ecom cart/checkout); the membership is a **delta on that flow**, not a separate path:
 
+> **One entity now.** The ecom Cart V2 this integration rides is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order); this is why membership selection moved off the old checkout-entity `membershipOptions` and onto the cart line item (below). This section says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
 3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Cart V2 unified cart + checkout, so membership selection moved off the old checkout-entity `membershipOptions` and onto the line item, set via `updateLineItemsInCurrentCart`:
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index e2feef2ab..1b22a9e50 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -12,6 +12,8 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 
 > **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of the `entity.id`-is-`undefined` cart bug. Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
 
+> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+
 ---
 
 ## The modules and the client (read this first)
diff --git a/skills/wix-manage/references/bookings/booking-system-integration-gaps.md b/skills/wix-manage/references/bookings/booking-system-integration-gaps.md
index 8a72cc750..02f5e929f 100644
--- a/skills/wix-manage/references/bookings/booking-system-integration-gaps.md
+++ b/skills/wix-manage/references/bookings/booking-system-integration-gaps.md
@@ -51,7 +51,7 @@ The Wix Bookings system contains **fundamental undocumented integration patterns
 - ❌ **NOT** documented booking status vs order status separation
 - ❌ **NOT** documented service properties preservation in checkout
 - ❌ **NO** mention of `BACKOFFICE_MERCHANT` channel requirement
-- ❌ **NO** explanation of why checkout/order APIs are needed for bookings
+- ❌ **NO** explanation of why the cart/order APIs are needed for bookings
 
 **Additional Service-Specific Gaps**:
 - ❌ **Courses**: Dual API requirement (booking + calendar events) completely undocumented
@@ -69,7 +69,7 @@ The Wix Bookings system contains **fundamental undocumented integration patterns
 - Create booking → Booking system creates reservation only
 - Use booking ID as catalog item in ecom system
 - Ecom system handles all pricing, tax, discount calculations
-- Create checkout and order for actual payment processing
+- Create a cart and place the order for actual payment processing
 - Async messaging system handles payment confirmation
 - Booking status (CONFIRMED) independent of payment status
 
@@ -329,7 +329,7 @@ Booking (CONFIRMED) → Cart → Place Order → Payment Processing (async)
 **Service Packages**: Multi-service booking + ecom integration
 
 **Universal Integration Considerations**:
-- All service types use same checkout/order creation pattern
+- All service types use the same cart/order creation pattern
 - Pricing calculations always handled by ecom system
 - Async payment confirmation applies to all booking types
 - Service properties preserved across all integration points
diff --git a/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md b/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md
index 4e5d352c1..c908ceead 100644
--- a/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md
+++ b/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md
@@ -10,7 +10,7 @@ This recipe documents how to convert CMS collections into sellable product catal
 
 Converting a CMS collection to a catalog enables:
 - Items in the collection become purchasable products
-- Integration with Wix Cart and Checkout APIs
+- Integration with the Wix Cart API (Cart V2, which unifies cart and checkout)
 - Real-time price and availability from your CMS data
 
 ## Prerequisites
diff --git a/skills/wix-vibe-headless/SKILL.md b/skills/wix-vibe-headless/SKILL.md
index 0298fc89b..252d520c9 100644
--- a/skills/wix-vibe-headless/SKILL.md
+++ b/skills/wix-vibe-headless/SKILL.md
@@ -75,6 +75,10 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
   collection is empty, show the empty state — never fabricate data, reviews, ratings, or counts.
 - **Purchases go through Wix.** Checkout/ticketing/plan purchase always complete via the Wix
   redirect-session / Wix-hosted form — **never hand-build a `/checkout` or purchase URL**.
+- **One cart entity, one checkout page.** Cart V2 is the evolution of the old two-entity model —
+  what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole
+  purchase flow (items → delivery/billing/payment → placing the order). These docs say **"cart"**
+  for that entity; **"checkout"** refers only to the hosted checkout *page* the buyer is redirected to.
 - **Fail loudly.** The helpers throw on out-of-stock, empty carts, unbookable slots, expired
   holds, and payment-still-owed. A green path means it really worked — don't swallow the error.
 - **Copy the shipped helpers as-is — don't rewrite their internals.** Wire your UI to the *exported*
diff --git a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
index 346dff32a..7656c8961 100644
--- a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
@@ -12,6 +12,11 @@ Builds a real, client-only Wix Bookings front end. The browser talks to Wix dire
 public `WIX_CLIENT_ID`. Never mock services or slots; never hand-build a `/checkout` URL —
 always create the booking through the API and complete it via the eCom checkout + redirect-session.
 
+> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a
+> separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
+> (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
+> that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+
 This skill ships the single-service booking flow for **APPOINTMENT and CLASS** services: browse
 services → pick a service → pick an available slot → enter details → book → hosted checkout.
 Appointments and classes differ only in the availability call (`listAvailableSlots` vs
diff --git a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
index 119fa77bf..d1dcdf9ad 100644
--- a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
@@ -13,6 +13,11 @@ Builds a real, client-only Wix restaurant experience. The browser talks to Wix d
 public `WIX_CLIENT_ID`. Never mock the menu; never hand-build `/checkout` or reservation URLs —
 always go through the official cart + redirect-session and the reservations hold/reserve flow.
 
+> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a
+> separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
+> (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
+> that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+
 ## When to use
 - User wants a Wix restaurant site, an online food-ordering page, or a table-reservation page.
 - User asks to "connect Wix Restaurants" or replace placeholder menu/ordering/booking UI with live data.
diff --git a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
index 5add3bce7..3553ff6f7 100644
--- a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
@@ -12,6 +12,11 @@ Builds a real, client-only Wix storefront. The browser talks to Wix directly ove
 public `WIX_CLIENT_ID`. Never mock products; never hand-build `/checkout` URLs — always
 go through the eCom cart + redirect-session.
 
+> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a
+> separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
+> (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
+> that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+
 ## When to use
 - User wants a Wix eCommerce store or asks to "connect Wix".
 - Replacing placeholder/mock products with live Wix data.

From aa06d5e304147e96239f5cf586df7db01a80753b Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 17:20:58 +0300
Subject: [PATCH 14/31] docs(ecom): tidy "Cart V2" -> "cart" where already
 established

Say the version once (intros/contrast/version-specific facts keep "Cart V2");
use plain "cart" for ordinary entity references. Here: current-cart taxonomy
row + the pricing-plans conclusion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 replatform/rp-mapper/wix-business-solutions-taxonomy.md         | 2 +-
 .../references/inline-recipes/how-to-code-pricing-plans.md      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index 0dfdebb62..c21c4de06 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -96,7 +96,7 @@ Primary entities:
 | Entity | What it does | Docs |
 | --- | --- | --- |
 | `cart` | The unified purchase-flow entity (Cart V2): holds line items, buyer/contact info, discounts, delivery, billing, and payment context all the way through placing the order. Cart V2 replaces the old separate Cart V1 + Checkout V1 model. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
-| `current-cart` | Visitor/member (session) scoped Cart V2 used in live purchase flows — same entity as `cart`, addressed by the shopper's session instead of a cart id. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
+| `current-cart` | The current cart for a visitor/member session — the same entity as `cart`, addressed by the shopper's session rather than a cart id. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index bd28ad850..1ce296032 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -123,4 +123,4 @@ A correct Pricing Plans frontend:
 - imports **`@wix/pricing-plans`** (`plansV3`, `orders`) — **never** `@wix/site-pricing-plans` (its `startOnlinePurchase` is Wix-site page-code, not headless);
 - lists the grid publicly with **`plansV3.queryPlans().eq('visibility','PUBLIC')`**, reads **`plan._id`** and price from **`pricingVariants[].pricingStrategies[].flatRate.amount`** (decimal string) — never a top-level `price` — and only shows a buy button on `buyable` plans;
 - treats **subscribe and my-subscription as login-gated** (the hard members dependency), orders with **`orders.createOnlineOrder(planId)`** (no `onBehalf`, no elevate), renders free plans as `ACTIVE` immediately, and drives paid plans through a payment redirect (**exact headless redirect to be confirmed in a live build**) — and **stops at the redirect**: no payments-account connect, no order activation / mark-as-paid from code (see *Out of scope*);
-- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom Cart V2 line item** (`selectedMembership.newMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.
+- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom cart line item** (`selectedMembership.newMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.

From 8494521ed7e3f5404fbd302df50f30946c03382b Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 17:30:54 +0300
Subject: [PATCH 15/31] =?UTF-8?q?docs(replatform):=20correct=20=E2=80=94?=
 =?UTF-8?q?=20calculated=20totals=20are=20NOT=20stored=20on=20the=20cart?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fix an inaccurate mapper note: a source checkout's INPUT state (billing,
shipping, coupons) maps onto the cart; calculated prices/tax/totals are not
stored on the cart in V2 (computed via Calculate/Estimate -> CartSummary; final
figures live on the order). Also tightened the 'checkout state' trigger bullet.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 replatform/rp-mapper/wix-business-solutions-taxonomy.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index c21c4de06..ef2cd1d1f 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -32,7 +32,7 @@ Typical `eCommerce` entities:
 
 Use `eCommerce` when the source data is about:
 - cart contents
-- checkout state (maps onto the cart — unified into Cart V2)
+- checkout input state — billing / shipping / coupons (maps onto the cart; unified into Cart V2. Calculated totals are not stored on the cart — see Mapper notes)
 - order lifecycle
 - fulfillment and payment operations
 - cross-vertical commerce operations that are not specific to a single catalog app
@@ -101,7 +101,7 @@ Primary entities:
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
 Mapper notes:
-- **A source system's separate "checkout" has no distinct Wix target.** Cart V2 unifies cart and checkout into one entity, so map source checkout state (calculated prices, tax, billing, shipping, discounts) onto `cart`, not a separate entity.
+- **A source system's separate "checkout" has no distinct Wix target.** Cart V2 unifies cart and checkout, so map a source checkout's *input* state onto `cart`: billing → `paymentInfo.billingAddress`, shipping/delivery → `deliveryInfo`, applied coupons → cart `coupons`. **Calculated prices, tax, and totals are NOT stored on the cart** — in V2 they're computed on demand via Calculate/Estimate Cart (returned as a `CartSummary`), and the final figures live on the `order` after placement — so don't try to persist a source checkout's computed totals on the cart.
 - If the source platform exposes products and orders in one model, split catalog entities into the vertical app and transaction entities into `ecommerce`.
 - If the source has historical orders but no cart or checkout history, map directly to `order` and document missing pre-purchase state.
 

From 7c40d85029e35ca180603e5447be84d9437d77d9 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 17:34:22 +0300
Subject: [PATCH 16/31] docs(replatform): keep the 'checkout state' trigger
 terse

It's a routing-trigger list item (like 'cart contents'/'order lifecycle'); the
mapping mechanics + calculated-totals caveat live in Mapper notes, not here.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 replatform/rp-mapper/wix-business-solutions-taxonomy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index ef2cd1d1f..41001e262 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -32,7 +32,7 @@ Typical `eCommerce` entities:
 
 Use `eCommerce` when the source data is about:
 - cart contents
-- checkout input state — billing / shipping / coupons (maps onto the cart; unified into Cart V2. Calculated totals are not stored on the cart — see Mapper notes)
+- checkout state
 - order lifecycle
 - fulfillment and payment operations
 - cross-vertical commerce operations that are not specific to a single catalog app

From 952256461f1c240829e9d78ee8313c9a3fcae547 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 17:52:25 +0300
Subject: [PATCH 17/31] docs(ecom): de-clutter per-line V1 asides; add one
 migration-guide link
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per review: teach V2 on its own terms. Keep the single "One entity now" note
and add a migration-guide link there; drop the repeated "(V1 returned the cart
directly)" / "NOT V1's lineItems" / "The V1 flow created a checkout entity"
asides, restating the bug-prevention as pure V2 ("returns { cart } — destructure
it"; "the cart's _id is the checkout id"). Stores Catalog-V1 warnings left intact.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-a-store.md   | 10 +++++-----
 .../inline-recipes/how-to-code-restaurant-orders.md    | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index adfc9f043..c03bb31b3 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -10,7 +10,7 @@ A concise contract for writing the **frontend code** of a storefront against a C
 
 > **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the single most common source of the cart-killing `product.id` bug (see the `_id` rule under *Listing products*). Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
 
-> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to. Migrating an existing Cart V1 / Checkout V1 integration? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
 
 ---
 
@@ -74,7 +74,7 @@ variant = {
   inventoryStatus: { inStock },                   // variant-level stock (boolean)
 }
 
-// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: wrapped in { cart } (V1 returned the cart directly)
+// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: returns { cart } — destructure it
 lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
 // price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
@@ -156,7 +156,7 @@ Each `variant` carries `variant.optionChoices[].optionChoiceNames` — `{ option
 
 ```js
 await currentCartV2.addLineItemsToCurrentCart({
-  catalogItems: [{                                // Cart V2: `catalogItems`, NOT V1's `lineItems`
+  catalogItems: [{                                // the write shape uses `catalogItems`
     quantity,
     catalogReference: {
       catalogItemId: product._id,                 // the product's _id (the `_id` rule above)
@@ -177,7 +177,7 @@ Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
 
 ```js
-const { cart } = await currentCartV2.getCurrentCart();   // NOTE: wrapped in { cart } (V1 returned the cart directly)
+const { cart } = await currentCartV2.getCurrentCart();   // NOTE: returns { cart } — destructure it
 const session = await redirects.createRedirectSession({
   ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id — there is no createCheckout call
   callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
@@ -185,7 +185,7 @@ const session = await redirects.createRedirectSession({
 window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL
 ```
 
-**⚠️ There is no `createCheckoutFromCurrentCart` in Cart V2.** The V1 flow created a checkout entity and returned a `checkoutId`; V2 unifies cart + checkout, so you pass the cart's own `_id` straight into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` now returns **`{ cart }`** (V1 returned the cart directly) — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
+**⚠️ The cart's `_id` is the checkout id.** There's no separate checkout to create — pass `cart._id` straight into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
 
 > **Simpler alternative (see PR note):** `cartV2.getCheckoutUrl(cartId)` returns a hosted-checkout URL directly, letting you drop `@wix/redirects`. It isn't used here because the redirect session is what carries the visitor/member session across domains; whether the plain URL preserves that for a headless storefront is unverified.
 
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index 1b22a9e50..9ccb15c0f 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -12,7 +12,7 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 
 > **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of the `entity.id`-is-`undefined` cart bug. Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
 
-> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to. Migrating an existing Cart V1 / Checkout V1 integration? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
 
 ---
 
@@ -81,7 +81,7 @@ fulfillmentMethod = {
 // item (from items.listItems — see how-to-code-restaurants.md)
 item = { _id, name, priceInfo: { price } }   // price is a decimal STRING; _id → cart catalogItemId
 
-// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: wrapped in { cart } (V1 returned the cart directly)
+// currentCartV2.getCurrentCart()  →  { cart: { _id, lineItems: [...] } }   // NOTE: returns { cart } — destructure it
 lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
 // price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
@@ -130,7 +130,7 @@ This is the one shape that differs materially from a Stores cart. Build a line i
 
 ```js
 await currentCartV2.addLineItemsToCurrentCart({
-  catalogItems: [{                                          // Cart V2: `catalogItems`, NOT V1's `lineItems`
+  catalogItems: [{                                          // the write shape uses `catalogItems`
     quantity,
     catalogReference: {
       catalogItemId: item._id,                              // the MENU ITEM's _id
@@ -160,7 +160,7 @@ Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
 
 ```js
-const { cart } = await currentCartV2.getCurrentCart();   // NOTE: wrapped in { cart } (V1 returned the cart directly)
+const { cart } = await currentCartV2.getCurrentCart();   // NOTE: returns { cart } — destructure it
 const session = await redirects.createRedirectSession({
   ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id — there is no createCheckout call
   callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
@@ -168,7 +168,7 @@ const session = await redirects.createRedirectSession({
 window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL (fulfillment + time slot chosen here)
 ```
 
-**⚠️ There is no `createCheckoutFromCurrentCart` in Cart V2.** V2 unifies cart + checkout, so you pass the cart's own `_id` into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` now returns **`{ cart }`** (V1 returned the cart directly) — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
+**⚠️ The cart's `_id` is the checkout id.** There's no separate checkout to create — pass `cart._id` into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
 
 **⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats `http://<same host>` as a different, unlisted origin. If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to `http://` behind Wix's TLS-terminating proxy → the buyer's return redirect **403s** with *"… isn't listed as an allowed redirect domain."* Pass `window.location.origin` from the client into the route (or force the scheme to `https`). Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
 

From 9d233423e274539711c19d039829139edbb0574e Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 17:52:58 +0300
Subject: [PATCH 18/31] docs(ecom): drop remaining
 createCheckoutFromCurrentCart aside in restaurant-orders conclusion

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-restaurant-orders.md  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index 9ccb15c0f..ade05631b 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -187,5 +187,5 @@ A correct Restaurants ordering frontend:
 - reads the **`operationId`** once from `listOperations()` (the `ENABLED`/`default` operation) and reuses it;
 - adds menu items with the **Orders app id `9a5d83fd-…`** (never the Stores id) and `options` carrying **`operationId` + `menuId` + `sectionId`** (all three) — **no `variantId`**;
 - threads `menuId`/`sectionId` from the render context, not a re-lookup;
-- checks out by feeding the **current cart's `_id`** (the checkout id in Cart V2) to **`redirects`** — no `createCheckoutFromCurrentCart` step — with an **`https://` `window.location.origin`** for the callbacks; the hosted checkout collects fulfillment + payment (which needs a premium plan + payment method).
+- checks out by feeding the **current cart's `_id`** (the checkout id) to **`redirects`**, with an **`https://` `window.location.origin`** for the callbacks; the hosted checkout collects fulfillment + payment (which needs a premium plan + payment method).
 </content>

From 922f5611e6637069860c1e5e06642625c17ad7d9 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 17:58:59 +0300
Subject: [PATCH 19/31] docs(ecom): add migration-guide link to remaining 'One
 entity now' notes

Consistency: pricing-plans recipe, the 3 vibe INSTRUCTIONS, and vibe SKILL.md
now point migrators to the migration guide (matches the store/restaurant recipes).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-pricing-plans.md      | 2 +-
 skills/wix-vibe-headless/SKILL.md                               | 2 +-
 skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md    | 1 +
 skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md | 1 +
 skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md  | 1 +
 5 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 1ce296032..673ca51a1 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -96,7 +96,7 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/or
 
 This is the payoff of the seed's STEP 2: a member who holds a plan that **covers** a service books it **with the membership** instead of paying per booking. Build the normal Bookings flow from **`how-to-code-bookings.md`** (list services → pick a slot → collect the form → `createBooking` → ecom cart/checkout); the membership is a **delta on that flow**, not a separate path:
 
-> **One entity now.** The ecom Cart V2 this integration rides is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order); this is why membership selection moved off the old checkout-entity `membershipOptions` and onto the cart line item (below). This section says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+> **One entity now.** The ecom Cart V2 this integration rides is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order); this is why membership selection moved off the old checkout-entity `membershipOptions` and onto the cart line item (below). This section says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to. Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
 
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
diff --git a/skills/wix-vibe-headless/SKILL.md b/skills/wix-vibe-headless/SKILL.md
index 252d520c9..12add443c 100644
--- a/skills/wix-vibe-headless/SKILL.md
+++ b/skills/wix-vibe-headless/SKILL.md
@@ -78,7 +78,7 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
 - **One cart entity, one checkout page.** Cart V2 is the evolution of the old two-entity model —
   what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole
   purchase flow (items → delivery/billing/payment → placing the order). These docs say **"cart"**
-  for that entity; **"checkout"** refers only to the hosted checkout *page* the buyer is redirected to.
+  for that entity; **"checkout"** refers only to the hosted checkout *page* the buyer is redirected to. Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
 - **Fail loudly.** The helpers throw on out-of-stock, empty carts, unbookable slots, expired
   holds, and payment-still-owed. A green path means it really worked — don't swallow the error.
 - **Copy the shipped helpers as-is — don't rewrite their internals.** Wire your UI to the *exported*
diff --git a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
index 7656c8961..fc922e3d6 100644
--- a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
@@ -16,6 +16,7 @@ always create the booking through the API and complete it via the eCom checkout
 > separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
 > (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
 > that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+> Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
 
 This skill ships the single-service booking flow for **APPOINTMENT and CLASS** services: browse
 services → pick a service → pick an available slot → enter details → book → hosted checkout.
diff --git a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
index d1dcdf9ad..c01222fe9 100644
--- a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
@@ -17,6 +17,7 @@ always go through the official cart + redirect-session and the reservations hold
 > separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
 > (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
 > that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+> Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
 
 ## When to use
 - User wants a Wix restaurant site, an online food-ordering page, or a table-reservation page.
diff --git a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
index 3553ff6f7..94e7468a8 100644
--- a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
@@ -16,6 +16,7 @@ go through the eCom cart + redirect-session.
 > separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
 > (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
 > that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
+> Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
 
 ## When to use
 - User wants a Wix eCommerce store or asks to "connect Wix".

From 12b36a929fc2b5dd364975ac8485787a0d78e136 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 9 Aug 2026 18:19:37 +0300
Subject: [PATCH 20/31] docs(ecom): disambiguate the Checkout step (heading +
 cross-ref)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 'Checkout' section documents the checkout STEP (redirect to the hosted
checkout page), not a checkout entity. Rename heading -> 'Checkout — redirect to
the hosted checkout page' and change the bare 'see Checkout' pointer to 'see the
Checkout section below', so neither reads as a reference to a checkout entity.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-a-store.md          | 4 ++--
 .../inline-recipes/how-to-code-restaurant-orders.md           | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index c03bb31b3..0576c3118 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -97,7 +97,7 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v
 
 **⚠️ CRITICAL: the entity id is `_id`, NOT `id`.** The SDK normalizes every entity's id to **`_id`**. `product.id` is `undefined` in SDK code. This is the cart-killer: feeding `product.id` into the cart's `catalogItemId` sends an empty string and the add returns **HTTP 500** (`"catalogItemId" has size 0`). Use `product._id` everywhere — in links, as the cart `catalogItemId`, and as the variant-query filter value. (If a field name surprises you, you are probably reading the REST doc view — re-open it with `?apiView=SDK`.)
 
-**Scope of the `_id` rule — entity reads only.** `_id` is the id of a read **entity** (product, variant, cart line item). It is **not** a universal "every id field is `_id`" rule: request params name their own fields (e.g. the redirect session takes `ecomCheckout.checkoutId`, *not* `_id` — see Checkout — even though the value you pass is the cart's `_id`). Don't assume every id-shaped field is spelled `_id`.
+**Scope of the `_id` rule — entity reads only.** `_id` is the id of a read **entity** (product, variant, cart line item). It is **not** a universal "every id field is `_id`" rule: request params name their own fields (e.g. the redirect session takes `ecomCheckout.checkoutId`, *not* `_id` — see the *Checkout* section below — even though the value you pass is the cart's `_id`). Don't assume every id-shaped field is spelled `_id`.
 
 **Visibility:** only `visible: true` products are returned to a visitor token, so a missing product usually means it wasn't seeded visible — not a query bug.
 
@@ -171,7 +171,7 @@ await currentCartV2.addLineItemsToCurrentCart({
 
 **⚠️ CRITICAL: `options.options` is for MODIFIERS, not variant selection.** Product option selections (Size/Color) are resolved to a **variant** and referenced by `variantId`. `options.options` is only for free-text / TEXT_CHOICES add-on **modifiers**. Do **not** encode Size/Color as `options.options` — that is the coffee-grind bug (`200` + empty cart).
 
-### Checkout
+### Checkout — redirect to the hosted checkout page
 
 Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout id. Read the current cart, then hand its id to a redirect session, which carries the visitor/member session across to the hosted checkout on its own domain.
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index ade05631b..663a43fe9 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -154,7 +154,7 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purch
 
 Optional: `options.onlineOrderingPageUrl` (e.g. `"/online-ordering"`) lets the buyer click the cart line to return to the item — include it only if your site has such a page.
 
-### Checkout
+### Checkout — redirect to the hosted checkout page
 
 Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout id. Read the current cart, then hand its id to a redirect session (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout).
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>

From 74583ed0bc8e935cb7e5f7453f0912695d7716d0 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Mon, 10 Aug 2026 16:26:19 +0300
Subject: [PATCH 21/31] docs(ecom): payment figures come from CartSummary; drop
 stray asides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- taxonomy Mapper note: state that BOTH price totals (summary.priceSummary) and
  payment figures (summary.paymentSummary — amount due, gift-card deductions) are
  computed by Calculate/Estimate Cart's CartSummary, not stored on the cart
- how-to-code-a-store: remove the "Simpler alternative (see PR note)" block (a
  PR-review artifact, meaningless in the shipped doc) and the redundant
  "(Cart V2 nests it under attributes)" parenthetical (the code already shows it)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 replatform/rp-mapper/wix-business-solutions-taxonomy.md       | 2 +-
 .../references/inline-recipes/how-to-code-a-store.md          | 4 +---
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index 41001e262..86e4288f0 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -101,7 +101,7 @@ Primary entities:
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
 Mapper notes:
-- **A source system's separate "checkout" has no distinct Wix target.** Cart V2 unifies cart and checkout, so map a source checkout's *input* state onto `cart`: billing → `paymentInfo.billingAddress`, shipping/delivery → `deliveryInfo`, applied coupons → cart `coupons`. **Calculated prices, tax, and totals are NOT stored on the cart** — in V2 they're computed on demand via Calculate/Estimate Cart (returned as a `CartSummary`), and the final figures live on the `order` after placement — so don't try to persist a source checkout's computed totals on the cart.
+- **A source system's separate "checkout" has no distinct Wix target.** Cart V2 unifies cart and checkout, so map a source checkout's *input* state onto `cart`: billing → `paymentInfo.billingAddress`, shipping/delivery → `deliveryInfo`, applied coupons → cart `coupons`. **Calculated price *and* payment figures are NOT stored on the cart** — both the price totals (`summary.priceSummary`) and the payment breakdown (`summary.paymentSummary` — amount due, gift-card deductions, and the like) are computed on demand by Calculate/Estimate Cart (returned in a `CartSummary`), and the final figures live on the `order` after placement — so don't try to persist a source checkout's computed totals on the cart.
 - If the source platform exposes products and orders in one model, split catalog entities into the vertical app and transaction entities into `ecommerce`.
 - If the source has historical orders but no cart or checkout history, map directly to `order` and document missing pre-purchase state.
 
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index 0576c3118..94e5f5642 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -187,8 +187,6 @@ window.location.href = session.redirectSession.fullUrl; // the hosted-checkout U
 
 **⚠️ The cart's `_id` is the checkout id.** There's no separate checkout to create — pass `cart._id` straight into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
 
-> **Simpler alternative (see PR note):** `cartV2.getCheckoutUrl(cartId)` returns a hosted-checkout URL directly, letting you drop `@wix/redirects`. It isn't used here because the redirect session is what carries the visitor/member session across domains; whether the plain URL preserves that for a headless storefront is unverified.
-
 **⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats **`http://<same host>` as a different, unlisted origin**. When the buyer returns from the hosted checkout (e.g. clicks "Continue Browsing"), the redirect goes through the allowlist — and an `http://` `postFlowUrl` **403s** with *"… isn't listed as an allowed redirect domain."* If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to **`http://`** behind Wix's TLS-terminating proxy → guaranteed 403 on return. So **pass `window.location.origin` from the client** into the route (don't read the origin off the request), or force the scheme to `https`. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
 
 ### Formatting cart prices (Cart V2 has no preformatted amount)
@@ -229,7 +227,7 @@ function imgSrc(mediaMain, w = 600, h = 600) {
 
 **Never hand-build a `static.wixstatic.com/.../v1/fit/...` URL** either — the format is easy to get wrong and the image then **403s**. Only `wix:image://` values need resolving; an already-absolute `https://` URL goes straight into `<img src>`. Doc: <https://dev.wix.com/docs/sdk/core-modules/sdk/media>
 
-**This applies to cart line-item images too, not just product reads.** A cart `lineItem.attributes.image` (Cart V2 nests it under `attributes`) is the same `wix:image://` identifier — run it through the same `imgSrc()` helper before `<img src>`. (If you build the cart over an API route, resolve there and return a ready URL so the component never sees a `wix:image://`.)
+**This applies to cart line-item images too, not just product reads.** A cart `lineItem.attributes.image` is the same `wix:image://` identifier — run it through the same `imgSrc()` helper before `<img src>`. (If you build the cart over an API route, resolve there and return a ready URL so the component never sees a `wix:image://`.)
 
 ### Rendering product descriptions
 

From 1a50d5a3932c4452d1f6c891fb43beccf8c91c52 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 13 Aug 2026 15:24:33 +0300
Subject: [PATCH 22/31] docs(ecom): finish Cart V2-only pass + explicit-error
 semantics + membership field

- Strip remaining Cart V1 / Checkout V1 references and V1<->V2 contrasts; keep exactly one migration-guide referral per doc where ecom types are introduced.

- Correct add-to-cart failure mode to V2: an unresolved/invalid line item or an over-stock quantity is rejected with an explicit error (was the V1 silent 200-with-empty-lineItems / silent quantity clamp).

- pricing-plans: apply membership via membershipPayment.existingMembership (read back as membership) instead of the deprecated selectedMembership.newMembership.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../wix-business-solutions-taxonomy.md         |  6 +++---
 .../inline-recipes/how-to-code-a-store.md      | 18 +++++++++---------
 .../how-to-code-pricing-plans.md               | 16 ++++++++--------
 .../how-to-code-restaurant-orders.md           | 16 ++++++++--------
 skills/wix-vibe-headless/SKILL.md              |  7 +++----
 .../references/bookings/INSTRUCTIONS.md        | 10 +++++-----
 .../bookings/wix-bookings-checkout.js          |  4 ++--
 .../references/restaurants/INSTRUCTIONS.md     | 10 +++++-----
 .../restaurants/wix-restaurants-ordering.js    |  6 +++---
 .../references/storefront/INSTRUCTIONS.md      | 18 +++++++++---------
 .../references/storefront/wix-store-cart.js    | 16 +++++++++-------
 11 files changed, 64 insertions(+), 63 deletions(-)

diff --git a/replatform/rp-mapper/wix-business-solutions-taxonomy.md b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
index 86e4288f0..d41f35b8f 100644
--- a/replatform/rp-mapper/wix-business-solutions-taxonomy.md
+++ b/replatform/rp-mapper/wix-business-solutions-taxonomy.md
@@ -25,7 +25,7 @@ This distinction must stay explicit in mapper output.
 It owns the purchase flow and operational commerce entities that are reused across multiple vertical apps.
 
 Typical `eCommerce` entities:
-- carts (Cart V2 — the unified cart+checkout entity)
+- carts (the unified cart + checkout entity)
 - orders
 - order billing / refunds
 - payment and fulfillment state tied to orders
@@ -95,13 +95,13 @@ Primary entities:
 
 | Entity | What it does | Docs |
 | --- | --- | --- |
-| `cart` | The unified purchase-flow entity (Cart V2): holds line items, buyer/contact info, discounts, delivery, billing, and payment context all the way through placing the order. Cart V2 replaces the old separate Cart V1 + Checkout V1 model. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
+| `cart` | The unified purchase-flow entity — holds line items, buyer/contact info, discounts, delivery, billing, and payment context all the way through placing the order. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `current-cart` | The current cart for a visitor/member session — the same entity as `cart`, addressed by the shopper's session rather than a cart id. | [About the Cart API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/introduction) |
 | `order` | Final commerce record for completed or externally recorded purchases | [About the Orders API](https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/introduction) |
 | `order-billing` | Payment capture, void, and refund operations for eCommerce orders | [About the Order Billing API](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/introduction) |
 
 Mapper notes:
-- **A source system's separate "checkout" has no distinct Wix target.** Cart V2 unifies cart and checkout, so map a source checkout's *input* state onto `cart`: billing → `paymentInfo.billingAddress`, shipping/delivery → `deliveryInfo`, applied coupons → cart `coupons`. **Calculated price *and* payment figures are NOT stored on the cart** — both the price totals (`summary.priceSummary`) and the payment breakdown (`summary.paymentSummary` — amount due, gift-card deductions, and the like) are computed on demand by Calculate/Estimate Cart (returned in a `CartSummary`), and the final figures live on the `order` after placement — so don't try to persist a source checkout's computed totals on the cart.
+- **A source system's separate "checkout" has no distinct Wix target.** The cart is the unified purchase-flow entity (there's no separate checkout), so map a source checkout's *input* state onto `cart`: billing → `paymentInfo.billingAddress`, shipping/delivery → `deliveryInfo`, applied coupons → cart `coupons`. **Calculated price *and* payment figures are NOT stored on the cart** — both the price totals (`summary.priceSummary`) and the payment breakdown (`summary.paymentSummary` — amount due, gift-card deductions, and the like) are computed on demand by Calculate/Estimate Cart (returned in a `CartSummary`), and the final figures live on the `order` after placement — so don't try to persist a source checkout's computed totals on the cart.
 - If the source platform exposes products and orders in one model, split catalog entities into the vertical app and transaction entities into `ecommerce`.
 - If the source has historical orders but no cart or checkout history, map directly to `order` and document missing pre-purchase state.
 
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
index 94e5f5642..416a16b3b 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-a-store.md
@@ -10,8 +10,6 @@ A concise contract for writing the **frontend code** of a storefront against a C
 
 > **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the single most common source of the cart-killing `product.id` bug (see the `_id` rule under *Listing products*). Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
 
-> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to. Migrating an existing Cart V1 / Checkout V1 integration? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
-
 ---
 
 ## The modules and the client (read this first)
@@ -29,6 +27,8 @@ A concise contract for writing the **frontend code** of a storefront against a C
 | Cart (add / get / checkout) | `@wix/ecom` | `currentCartV2` |
 | Redirect to hosted checkout | `@wix/redirects` | `redirects` |
 
+> Migrating from Cart V1 / Checkout V1? The code below is 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.
+
 **Never** import the V1 `products` or `collections` modules from `@wix/stores`.
 
 **Auth / client — framework split:**
@@ -78,7 +78,7 @@ variant = {
 lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
 // price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
-// Cart V2 has NO checkout entity — the cart's _id IS the checkout id; there is no createCheckout call:
+// the cart's _id is the checkout id → pass to the redirect session:
 // redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }
 ```
 
@@ -167,29 +167,29 @@ await currentCartV2.addLineItemsToCurrentCart({
 });
 ```
 
-**⚠️ CRITICAL: `options.variantId` is MANDATORY for any product that has variants.** Adding by `catalogItemId` alone returns **HTTP 200 but adds nothing** — the silent empty cart. The cart method's required-params list omits `variantId`, so this fails quietly and looks like success. Always resolve and include it (part 1 above).
+**⚠️ CRITICAL: `options.variantId` is MANDATORY for any product that has variants.** Adding by `catalogItemId` alone **fails** — the catalog can't resolve a variant-bearing product without it, and Cart V2 **rejects the add with an explicit error** rather than accepting an invalid line. The cart method's required-params list omits `variantId`, so it's an easy one to miss. Always resolve and include it (part 1 above).
 
-**⚠️ CRITICAL: `options.options` is for MODIFIERS, not variant selection.** Product option selections (Size/Color) are resolved to a **variant** and referenced by `variantId`. `options.options` is only for free-text / TEXT_CHOICES add-on **modifiers**. Do **not** encode Size/Color as `options.options` — that is the coffee-grind bug (`200` + empty cart).
+**⚠️ CRITICAL: `options.options` is for MODIFIERS, not variant selection.** Product option selections (Size/Color) are resolved to a **variant** and referenced by `variantId`. `options.options` is only for free-text / TEXT_CHOICES add-on **modifiers**. Do **not** encode Size/Color as `options.options` — that is the coffee-grind bug: the variant never resolves, so Cart V2 rejects the add with an explicit error.
 
 ### Checkout — redirect to the hosted checkout page
 
-Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout id. Read the current cart, then hand its id to a redirect session, which carries the visitor/member session across to the hosted checkout on its own domain.
+The cart's `_id` **is** the checkout id — pass it into the redirect session's `ecomCheckout.checkoutId`. Read the current cart, then hand its id to a redirect session, which carries the visitor/member session across to the hosted checkout on its own domain.
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
 
 ```js
 const { cart } = await currentCartV2.getCurrentCart();   // NOTE: returns { cart } — destructure it
 const session = await redirects.createRedirectSession({
-  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id — there is no createCheckout call
+  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id
   callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
 });
 window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL
 ```
 
-**⚠️ The cart's `_id` is the checkout id.** There's no separate checkout to create — pass `cart._id` straight into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
+**⚠️ The cart's `_id` is the checkout id.** Pass `cart._id` straight into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
 
 **⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats **`http://<same host>` as a different, unlisted origin**. When the buyer returns from the hosted checkout (e.g. clicks "Continue Browsing"), the redirect goes through the allowlist — and an `http://` `postFlowUrl` **403s** with *"… isn't listed as an allowed redirect domain."* If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to **`http://`** behind Wix's TLS-terminating proxy → guaranteed 403 on return. So **pass `window.location.origin` from the client** into the route (don't read the origin off the request), or force the scheme to `https`. Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
 
-### Formatting cart prices (Cart V2 has no preformatted amount)
+### Formatting cart prices
 
 **Product** prices from `productsV3` still carry a ready-to-show `actualPriceRange.minValue.formattedAmount` — use it directly. But **Cart V2 money does not**: every cart amount — line-item `pricing.unitPrice` / `pricing.totalPrice` **and** the `estimateCurrentCart`/`calculateCurrentCart` `summary.priceSummary.*` — is a `ConvertedMoney` `{ amount, convertedAmount }` with **no** formatted string. So once items are in the cart, you format the price yourself. The currency isn't on the money object; read it from the cart (`cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode`), and use `convertedAmount` (buyer's display currency) when present, else `amount` (site currency):
 
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 673ca51a1..385b758b5 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -23,7 +23,9 @@ A contract for the **frontend code** of a pricing-plans site: showing the plans
 | List / read plans (the grid) | `@wix/pricing-plans` | `plansV3` (Plans V3 — `queryPlans`, `getPlan`) |
 | Order a plan + read a member's orders | `@wix/pricing-plans` | `orders` (`createOnlineOrder`, `memberListOrders`, `memberGetOrder`) |
 | Member login / current member | `@wix/members` + `@wix/sdk` auth | see the members recipe (`getCurrentMember`, `loggedIn()`) |
-| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `currentCartV2` (line-item `selectedMembership`) — see *Booking with a membership* |
+| Book a service with a membership (integration) | `@wix/bookings` + `@wix/ecom` (+ `@wix/redirects`) | `bookings` (`createBooking`), ecom `currentCartV2` (line-item `membershipPayment`) — see *Booking with a membership* |
+
+> Migrating from Cart V1 / Checkout V1? The code below is 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.
 
 **Never** import `@wix/site-pricing-plans` in headless code, and don't reach for a V1 `plans`-collection query — Plans V3 (`queryPlans` → `pricingVariants`) is the shape the seed creates.
 
@@ -96,17 +98,15 @@ Doc: <https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/or
 
 This is the payoff of the seed's STEP 2: a member who holds a plan that **covers** a service books it **with the membership** instead of paying per booking. Build the normal Bookings flow from **`how-to-code-bookings.md`** (list services → pick a slot → collect the form → `createBooking` → ecom cart/checkout); the membership is a **delta on that flow**, not a separate path:
 
-> **One entity now.** The ecom Cart V2 this integration rides is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order); this is why membership selection moved off the old checkout-entity `membershipOptions` and onto the cart line item (below). This section says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to. Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
-
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
-3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Cart V2 unified cart + checkout, so membership selection moved off the old checkout-entity `membershipOptions` and onto the line item, set via `updateLineItemsInCurrentCart`:
-   - **Apply one** by setting the line item's `selectedMembership` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, selectedMembership: { newMembership: { _id, appId } } }] })`. When the membership covers the full price, the calculated total drops to `0`. **⚠️ Membership-on-cart is unstable in the SDK typings:** `selectedMembership` is the only field present in the **public** `@wix/ecom` types (verified: it type-checks; the shape is `{ newMembership: { _id, appId } }`) but is marked **deprecated**; its intended replacement `membershipPayment` is **`@internal`** and does NOT exist on the public `LineItemUpdate` (it fails to type-check for consumers). Use `selectedMembership` for now, and confirm the supported public field with the eCom team before shipping.
-   - **Which plan to apply / eligibility:** there is **no** dedicated "eligible memberships for this line item" read on the current cart in V2 (the Checkout V1 `membershipOptions.eligibleMemberships` list has no direct analog — `calculateCurrentCart` → `summary.paymentSummary.memberships` reports memberships **already applied/charged**, not candidates). Determine eligibility from the member's active plans + live coverage instead — see the LIVE-read note below. **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
+3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Set membership selection on the line item via `updateLineItemsInCurrentCart`:
+   - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { membershipId, appId } } }] })` — `membershipId`/`appId` identify the member's existing plan membership (the Pricing Plans app); the line item reads it back as `membership`. When the membership covers the full price, the calculated total drops to `0`.
+   - **Which plan to apply / eligibility:** there is **no** dedicated "eligible memberships for this line item" read on the current cart in V2 (`calculateCurrentCart` → `summary.paymentSummary.memberships` reports memberships **already applied**, not candidates). Determine eligibility from the member's active plans + live coverage instead — see the LIVE-read note below. **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
    Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md?apiView=SDK>
 4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
 
-- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `selectedMembership.newMembership` from the matched plan.
+- **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `membershipPayment.existingMembership` from the matched plan.
 - **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
 - **Credit/session plans:** for a limited (non-unlimited) plan, `eligibleMemberships[].credits.remaining` matters — `0` remaining is not eligible. An unlimited plan (seed `price:"0"`) has no credit ceiling.
 
@@ -123,4 +123,4 @@ A correct Pricing Plans frontend:
 - imports **`@wix/pricing-plans`** (`plansV3`, `orders`) — **never** `@wix/site-pricing-plans` (its `startOnlinePurchase` is Wix-site page-code, not headless);
 - lists the grid publicly with **`plansV3.queryPlans().eq('visibility','PUBLIC')`**, reads **`plan._id`** and price from **`pricingVariants[].pricingStrategies[].flatRate.amount`** (decimal string) — never a top-level `price` — and only shows a buy button on `buyable` plans;
 - treats **subscribe and my-subscription as login-gated** (the hard members dependency), orders with **`orders.createOnlineOrder(planId)`** (no `onBehalf`, no elevate), renders free plans as `ACTIVE` immediately, and drives paid plans through a payment redirect (**exact headless redirect to be confirmed in a live build**) — and **stops at the redirect**: no payments-account connect, no order activation / mark-as-paid from code (see *Out of scope*);
-- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom cart line item** (`selectedMembership.newMembership` via `updateLineItemsInCurrentCart`, not the old checkout `membershipOptions`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.
+- for the Bookings integration, books a covered service by setting **`selectedPaymentOption: "MEMBERSHIP"`** on `createBooking`, applies the membership on the **ecom cart line item** (`membershipPayment.existingMembership` via `updateLineItemsInCurrentCart`), never calls `confirmBooking`, and falls back to matching the member's active-order `planId`s to the service's coverage when the cart eligibility field isn't readable client-side.
diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
index 663a43fe9..81a496419 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-restaurant-orders.md
@@ -12,8 +12,6 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 
 > **⚠️ Reading rule — always append `.md?apiView=SDK` to every doc link below.** The Wix docs render two views of the same page. The **bare / REST view shows `id`**; the **`?apiView=SDK` view shows `_id`** — and the SDK is what your frontend calls. Reading the REST view by mistake is the most common source of the `entity.id`-is-`undefined` cart bug. Fetch the `.md?apiView=SDK` form directly; don't re-discover these with search.
 
-> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow (items → delivery/billing/payment → placing the order). This recipe says **"cart"** for that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to. Migrating an existing Cart V1 / Checkout V1 integration? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
-
 ---
 
 ## The modules and the client (read this first)
@@ -31,6 +29,8 @@ A contract for the **frontend code** that lets a visitor **order** from a Wix Re
 | Cart (add / get / checkout) | `@wix/ecom` | `currentCartV2` |
 | Redirect to hosted checkout | `@wix/redirects` | `redirects` |
 
+> Migrating from Cart V1 / Checkout V1? The code below is 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.
+
 **Auth / client — framework split:**
 - **Astro (Wix-managed):** authentication is ambient. Call `operations` / `fulfillmentMethods` / `currentCartV2` directly from server components and backend routes (`src/pages/api/*.ts`) — **no `createClient`, no `OAuthStrategy`, no `clientId`.**
   ```js
@@ -85,7 +85,7 @@ item = { _id, name, priceInfo: { price } }   // price is a decimal STRING; _id 
 lineItem = { _id, name: { original }, quantityInfo: { confirmedQuantity }, pricing: { unitPrice: { amount } }, attributes: { image } }
 // price → pricing.unitPrice (ConvertedMoney, NO formatted string in V2 — format it yourself; .amount is site currency, .convertedAmount the buyer's display currency); qty → quantityInfo.confirmedQuantity; image → attributes.image (wix:image:// → resolve)
 
-// Cart V2 has NO checkout entity — the cart's _id IS the checkout id; there is no createCheckout call:
+// the cart's _id is the checkout id → pass to the redirect session:
 // redirects.createRedirectSession({ ecomCheckout: { checkoutId: cart._id }, callbacks })  →  { redirectSession: { fullUrl } }
 ```
 
@@ -146,7 +146,7 @@ await currentCartV2.addLineItemsToCurrentCart({
 ```
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md?apiView=SDK>
 
-**⚠️ CRITICAL: `options` MUST carry `operationId`, `menuId`, AND `sectionId` — all three.** A restaurant line item is identified by *where in the menu it was ordered from*, not by a variant. Omitting any of the three makes eCommerce unable to resolve the item against the Restaurants catalog — the add fails or the line can't be checked out. This is the restaurant analog of the store's mandatory `variantId`, and it fails the same quiet way.
+**⚠️ CRITICAL: `options` MUST carry `operationId`, `menuId`, AND `sectionId` — all three.** A restaurant line item is identified by *where in the menu it was ordered from*, not by a variant. Omitting any of the three makes eCommerce unable to resolve the item against the Restaurants catalog — Cart V2 rejects the add with an explicit error rather than accepting an invalid line. This is the restaurant analog of the store's mandatory `variantId`.
 
 **⚠️ CRITICAL: there is NO `variantId` here.** `options.variantId` is a **Stores** concept — menu items have no variants in this flow. Don't copy the store recipe's `variantId` resolution; a restaurant line uses `operationId`/`menuId`/`sectionId` instead. (Menu item *modifiers* — "extra cheese" — are a separate concern and out of scope for the basic order flow.)
 
@@ -156,19 +156,19 @@ Optional: `options.onlineOrderingPageUrl` (e.g. `"/online-ordering"`) lets the b
 
 ### Checkout — redirect to the hosted checkout page
 
-Cart V2 has no separate checkout entity — the cart's `_id` **is** the checkout id. Read the current cart, then hand its id to a redirect session (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout).
+The cart's `_id` **is** the checkout id — pass it into the redirect session's `ecomCheckout.checkoutId`. Read the current cart, then hand its id to a redirect session (identical to the storefront flow — restaurant orders ride on the same eCommerce checkout).
 Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md?apiView=SDK>
 
 ```js
 const { cart } = await currentCartV2.getCurrentCart();   // NOTE: returns { cart } — destructure it
 const session = await redirects.createRedirectSession({
-  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id — there is no createCheckout call
+  ecomCheckout: { checkoutId: cart._id },   // the cart's _id IS the checkout id
   callbacks: { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` },
 });
 window.location.href = session.redirectSession.fullUrl; // the hosted-checkout URL (fulfillment + time slot chosen here)
 ```
 
-**⚠️ The cart's `_id` is the checkout id.** There's no separate checkout to create — pass `cart._id` into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
+**⚠️ The cart's `_id` is the checkout id.** Pass `cart._id` into the redirect session's `ecomCheckout.checkoutId`. And `getCurrentCart()` returns **`{ cart }`** — destructure it, or `cart` is `undefined` and `cart._id` throws *"Cannot read properties of undefined (reading '_id')"*.
 
 **⚠️ CRITICAL: `origin` for `postFlowUrl`/`thankYouPageUrl` MUST be the `https://` published host — derive it from `window.location.origin`, NEVER `new URL(request.url).origin`.** The Headless redirect allowlist registers the site's **`https://`** host and treats `http://<same host>` as a different, unlisted origin. If you build the redirect session in a **server route** (`src/pages/api/*`), `new URL(request.url).origin` resolves to `http://` behind Wix's TLS-terminating proxy → the buyer's return redirect **403s** with *"… isn't listed as an allowed redirect domain."* Pass `window.location.origin` from the client into the route (or force the scheme to `https`). Doc: <https://dev.wix.com/docs/go-headless/getting-started/setup/manage-urls/add-allowed-redirect-domains>.
 
@@ -176,7 +176,7 @@ window.location.href = session.redirectSession.fullUrl; // the hosted-checkout U
 
 ### Reading the price and the cart
 
-Menu item price is **`item.priceInfo.price`** — a decimal **string** with no currency symbol (see `how-to-code-restaurants.md`; the SDK `PriceInfo` type has only `price`, no `formattedPrice`). A cart line's price is **`lineItem.pricing.unitPrice`** / **`pricing.totalPrice`** — a `ConvertedMoney` `{ amount, convertedAmount }`; Cart V2 dropped the preformatted line-item price, so format it yourself. The currency lives on the cart, not the money object — format from `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode` (see the *Formatting cart prices* section of `how-to-code-a-store.md` for the exact `Intl.NumberFormat` helper), e.g. `new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(Number(pricing.totalPrice.convertedAmount ?? pricing.totalPrice.amount))`. Cart line images are `wix:image://` identifiers — resolve them with `media.getScaledToFillImageUrl(id, w, h, {})` (4 args), never raw (see the store/menu recipes' image callout).
+Menu item price is **`item.priceInfo.price`** — a decimal **string** with no currency symbol (see `how-to-code-restaurants.md`; the SDK `PriceInfo` type has only `price`, no `formattedPrice`). A cart line's price is **`lineItem.pricing.unitPrice`** / **`pricing.totalPrice`** — a `ConvertedMoney` `{ amount, convertedAmount }`; Cart V2 line items carry no preformatted price, so format it yourself. The currency lives on the cart, not the money object — format from `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode` (see the *Formatting cart prices* section of `how-to-code-a-store.md` for the exact `Intl.NumberFormat` helper), e.g. `new Intl.NumberFormat(undefined, { style: 'currency', currency }).format(Number(pricing.totalPrice.convertedAmount ?? pricing.totalPrice.amount))`. Cart line images are `wix:image://` identifiers — resolve them with `media.getScaledToFillImageUrl(id, w, h, {})` (4 args), never raw (see the store/menu recipes' image callout).
 
 ---
 
diff --git a/skills/wix-vibe-headless/SKILL.md b/skills/wix-vibe-headless/SKILL.md
index 12add443c..230822994 100644
--- a/skills/wix-vibe-headless/SKILL.md
+++ b/skills/wix-vibe-headless/SKILL.md
@@ -75,10 +75,9 @@ This skill is the deliberately **client-only, REST-only** path. It is independen
   collection is empty, show the empty state — never fabricate data, reviews, ratings, or counts.
 - **Purchases go through Wix.** Checkout/ticketing/plan purchase always complete via the Wix
   redirect-session / Wix-hosted form — **never hand-build a `/checkout` or purchase URL**.
-- **One cart entity, one checkout page.** Cart V2 is the evolution of the old two-entity model —
-  what used to be a separate *cart* and *checkout* is now a single **cart** that carries the whole
-  purchase flow (items → delivery/billing/payment → placing the order). These docs say **"cart"**
-  for that entity; **"checkout"** refers only to the hosted checkout *page* the buyer is redirected to. Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
+- **One cart entity, one checkout page.** A single **cart** carries the whole purchase flow
+  (items → delivery/billing/payment → placing the order). These docs say **"cart"** for that
+  entity; **"checkout"** refers only to the hosted checkout *page* the buyer is redirected to.
 - **Fail loudly.** The helpers throw on out-of-stock, empty carts, unbookable slots, expired
   holds, and payment-still-owed. A green path means it really worked — don't swallow the error.
 - **Copy the shipped helpers as-is — don't rewrite their internals.** Wire your UI to the *exported*
diff --git a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
index fc922e3d6..3418baed5 100644
--- a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
@@ -12,11 +12,9 @@ Builds a real, client-only Wix Bookings front end. The browser talks to Wix dire
 public `WIX_CLIENT_ID`. Never mock services or slots; never hand-build a `/checkout` URL —
 always create the booking through the API and complete it via the eCom checkout + redirect-session.
 
-> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a
-> separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
-> (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
-> that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
-> Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
+> **One entity.** A single **cart** carries the whole purchase flow (items →
+> delivery/billing/payment → placing the order). These instructions say **"cart"** for that
+> entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
 
 This skill ships the single-service booking flow for **APPOINTMENT and CLASS** services: browse
 services → pick a service → pick an available slot → enter details → book → hosted checkout.
@@ -57,6 +55,8 @@ adjust import paths:
 - `src/rest/wix-bookings-checkout.js` — **Booking & checkout:**
   `createBooking`, `checkoutBooking`, `bookAndCheckout`
 
+> 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.
+
 The `Service`, `TimeSlot`, and `Booking` shapes are documented as JSDoc comments at the top of
 each helper file. Read them before building the UI — they describe the key fields and link to
 the full API reference for anything not shown.
diff --git a/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js b/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js
index 6e4201559..3799e9879 100644
--- a/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js
+++ b/skills/wix-vibe-headless/references/bookings/wix-bookings-checkout.js
@@ -105,8 +105,8 @@ export async function createBooking(slot, contactDetails, { totalParticipants =
  * Redirect the buyer there (window.location.href = ...). On return, the booking is confirmed.
  * Throws if no redirect URL is produced.
  *
- * Cart V2 unifies cart + checkout: there is no separate checkout entity, so the created
- * cart's id IS the checkout id fed to the redirect session.
+ * The created cart's id is the checkout id — pass it as ecomCheckout.checkoutId to the
+ * redirect session.
  * https://dev.wix.com/docs/rest/business-solutions/e-commerce/purchase-flow/cart-v2/create-cart.md
  * @param {string} bookingId  booking.id from createBooking().
  * @returns {Promise<string>} The hosted-checkout URL to redirect to.
diff --git a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
index c01222fe9..f448d0663 100644
--- a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
@@ -13,11 +13,9 @@ Builds a real, client-only Wix restaurant experience. The browser talks to Wix d
 public `WIX_CLIENT_ID`. Never mock the menu; never hand-build `/checkout` or reservation URLs —
 always go through the official cart + redirect-session and the reservations hold/reserve flow.
 
-> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a
-> separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
-> (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
-> that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
-> Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
+> **One entity.** A single **cart** carries the whole purchase flow (items →
+> delivery/billing/payment → placing the order). These instructions say **"cart"** for that
+> entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
 
 ## When to use
 - User wants a Wix restaurant site, an online food-ordering page, or a table-reservation page.
@@ -56,6 +54,8 @@ adjust import paths:
 - `src/rest/wix-restaurants-reservations.js` — **Reservations:**
   `listReservationLocations`, `getTimeSlots`, `createHeldReservation`, `reserveReservation`
 
+> 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.
+
 The Menu, Item, ModifierGroup, Operation, Cart, ReservationLocation, TimeSlot, and Reservation
 shapes are documented as JSDoc at the top of each helper file. Read the relevant file(s) before
 building the UI — they describe the key fields and link to the full reference for anything not shown.
diff --git a/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js b/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
index 5a319ec28..dcc50f65f 100644
--- a/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
+++ b/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
@@ -128,9 +128,9 @@ export async function removeFromCart(lineItemId) {
  * Throws on empty cart, unavailable lines, or a missing redirect URL.
  * Redirect with: window.location.href = await checkout()
  *
- * Cart V2 has no separate checkout entity — the cart id IS the checkout id, so there is no
- * "create checkout" step. We still create a redirect session so the visitor/member session
- * carries across to the Wix-hosted checkout page on its own domain.
+ * The cart id is the checkout id — pass it as ecomCheckout.checkoutId to the redirect session.
+ * We create a redirect session so the visitor/member session carries across to the Wix-hosted
+ * checkout page on its own domain.
  * @returns {Promise<string>}
  */
 export async function checkout() {
diff --git a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
index 94e7468a8..e2eeb9908 100644
--- a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
@@ -12,11 +12,9 @@ Builds a real, client-only Wix storefront. The browser talks to Wix directly ove
 public `WIX_CLIENT_ID`. Never mock products; never hand-build `/checkout` URLs — always
 go through the eCom cart + redirect-session.
 
-> **One entity now.** Cart V2 is the evolution of the old two-entity model — what used to be a
-> separate *cart* and *checkout* is now a single **cart** that carries the whole purchase flow
-> (items → delivery/billing/payment → placing the order). These instructions say **"cart"** for
-> that entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
-> Migrating from Cart V1 / Checkout V1? See the [migration guide](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/migration-guide).
+> **One entity.** A single **cart** carries the whole purchase flow (items →
+> delivery/billing/payment → placing the order). These instructions say **"cart"** for that
+> entity; **"checkout"** appears only for the hosted checkout *page* the buyer is sent to.
 
 ## When to use
 - User wants a Wix eCommerce store or asks to "connect Wix".
@@ -50,6 +48,8 @@ however the project wants; wire it to these two snippets. Copy them into the app
 - `src/rest/wix-store-cart.js` — **Cart & checkout:**
   `addToCart`, `getCurrentCart`, `updateCartItemQuantity`, `removeFromCart`, `checkout`
 
+> 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.
+
 The Product and Cart shapes are documented as JSDoc comments at the top of each helper file.
 Read them before building the UI — they describe the key fields and link to the full API
 reference for anything not shown.
@@ -70,8 +70,8 @@ reference for anything not shown.
   `product.modifiers` (TEXT_CHOICES → choice buttons/select; FREE_TEXT → a text input); render
   neither when the arrays are empty. Skipping modifiers is a common miss — a product with a
   **mandatory** modifier (e.g. "gift wrap?") whose control isn't rendered can never be added: the
-  buyer can't satisfy the requirement, so `add-line-items` returns 200 with an **empty** `lineItems`
-  and the add silently no-ops.
+  buyer can't supply the required value, the catalog can't resolve the line, and Cart V2 **rejects
+  the add** (the `add-line-items` call errors) rather than silently accepting an invalid line.
   Render `product.plainDescription` as **HTML** — despite the name it contains markup (`<p>`,
   `<br>`, `<strong>`), so `dangerouslySetInnerHTML={{ __html: product.plainDescription }}` (React)
   or `el.innerHTML = product.plainDescription`, never as a plain text node (that shows raw `<p>`
@@ -119,7 +119,7 @@ reference for anything not shown.
 
 ## Hard rules (do not violate)
 - ✅ Checkout ONLY via `checkout()` (current cart id → `/headless/v1/redirect-session`
-  `fullUrl`), then redirect. Cart V2 has no `create-checkout` step — the cart id is the checkout id.
+  `fullUrl`), then redirect. The cart id is the checkout id — pass it straight to the redirect session.
 - ❌ Never hand-build `/checkout`, cart-add, or product permalinks for purchase.
 - ❌ Never mock products — render live Wix data or the empty state.
 - ❌ Never generate fake reviews, ratings, or testimonials. Empty review UI only.
@@ -128,7 +128,7 @@ reference for anything not shown.
 - ✅ On the PDP, render a control for **every** `product.options` entry **and** every `product.modifiers`
   entry — never only variants. Keep Add-to-cart disabled until a variant resolves and every
   `modifier.mandatory === true` has a value; a mandatory modifier with no rendered control makes the
-  product unbuyable (add-line-items returns 200 with empty `lineItems`).
+  product unbuyable — Cart V2 rejects the add (the call errors) rather than accepting an invalid line.
 - ✅ Pass `addToCart`'s `variantId` (`variantsInfo.variants[].id`) for products with variants; omit for products without.
 - ✅ Pass `modifierChoices` (`{ [modifier.key]: choiceKey }`) for TEXT_CHOICES modifiers; pass `customTextFields`
   (`{ [modifier.freeTextSettings.key]: userInput }`) for FREE_TEXT modifiers. Include mandatory modifiers.
diff --git a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
index 59914a00c..1b60fe120 100644
--- a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
+++ b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
@@ -64,9 +64,9 @@ export async function addToCart(catalogItemId, variantId, quantity = 1, { modifi
   const line = (res?.cart?.lineItems ?? []).find(
     (l) => l.source?.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
   );
-  // Cart V2 reports invalid items as explicit errors, but partial stock still returns a
-  // reduced confirmedQuantity — guard both signals:
-  // 1. status set to something other than IN_STOCK
+  // Cart V2 rejects an invalid add with an explicit error (so wixApiRequest throws above).
+  // As a backstop, inspect the returned line and fail loudly on either signal:
+  // 1. a status other than IN_STOCK (OUT_OF_STOCK / PARTIALLY_IN_STOCK / REMOVED_FROM_CATALOG)
   // 2. no matching line at all (confirmedQuantity 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?`);
@@ -99,9 +99,9 @@ export async function getCurrentCart() {
  * Throws on empty cart, unavailable lines, or a missing redirect URL.
  * Usage: window.location.href = await checkout()
  *
- * Cart V2 has no separate checkout entity — the cart id IS the checkout id, so there is no
- * "create checkout" step. We still create a redirect session so the visitor/member session
- * carries across to the Wix-hosted checkout page on its own domain.
+ * The cart id is the checkout id — pass it as ecomCheckout.checkoutId to the redirect session.
+ * We create a redirect session so the visitor/member session carries across to the Wix-hosted
+ * checkout page on its own domain.
  * @returns {Promise<string>}
  */
 export async function checkout() {
@@ -125,7 +125,9 @@ 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 confirmedQuantity may be lower than requested.
+ * In Cart V2 a quantity above remaining stock is rejected with an explicit error — V2 no longer
+ * silently reduces it to the available amount (the V1 behavior), so handle the throw and show
+ * the buyer what's in stock.
  * @returns {Promise<object>} Updated cart.
  */
 export async function updateCartItemQuantity(lineItemId, quantity) {

From 9b0ce3c25e714b960b005989c19b9c7965d693a4 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Thu, 13 Aug 2026 16:27:34 +0300
Subject: [PATCH 23/31] docs(ecom): address independent-review findings on
 pricing-plans + vibe helpers

- pricing-plans: drop the non-existent `eligibleMemberships[].credits.remaining` cart read (contradicted the "no eligible-memberships read on the V2 cart" note); fold the credit-exhaustion check into the member-plan eligibility path. Specify the membership read-back field as `paymentConfig.membership`.

- wix-store-cart.js: drop stray "(the V1 behavior)" contrast from the quantity-update note.

- wix-restaurants-ordering.js: fix doc comment "not AVAILABLE" -> status not IN_STOCK (matches the ItemStatus enum and the code's check).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-pricing-plans.md   | 4 ++--
 .../references/restaurants/wix-restaurants-ordering.js       | 2 +-
 .../references/storefront/wix-store-cart.js                  | 5 ++---
 3 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 385b758b5..9204b14ca 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -101,14 +101,14 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 1. **Require login** — membership payment resolves against the member identity (a covered service booked anonymously just falls back to pay-per-booking).
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
 3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Set membership selection on the line item via `updateLineItemsInCurrentCart`:
-   - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { membershipId, appId } } }] })` — `membershipId`/`appId` identify the member's existing plan membership (the Pricing Plans app); the line item reads it back as `membership`. When the membership covers the full price, the calculated total drops to `0`.
+   - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { membershipId, appId } } }] })` — `membershipId`/`appId` identify the member's existing plan membership (the Pricing Plans app); the line item reads it back as `paymentConfig.membership`. When the membership covers the full price, the calculated total drops to `0`.
    - **Which plan to apply / eligibility:** there is **no** dedicated "eligible memberships for this line item" read on the current cart in V2 (`calculateCurrentCart` → `summary.paymentSummary.memberships` reports memberships **already applied**, not candidates). Determine eligibility from the member's active plans + live coverage instead — see the LIVE-read note below. **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
    Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md?apiView=SDK>
 4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
 
 - **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `membershipPayment.existingMembership` from the matched plan.
 - **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
-- **Credit/session plans:** for a limited (non-unlimited) plan, `eligibleMemberships[].credits.remaining` matters — `0` remaining is not eligible. An unlimited plan (seed `price:"0"`) has no credit ceiling.
+- **Credit/session plans:** a limited (non-unlimited) plan has a finite credit/session balance and stops covering bookings once it's used up — fold "is it exhausted?" into the eligibility decision above and treat an out-of-credits plan as not eligible. Don't try to read this off the cart: Cart V2 exposes no per-line eligible-memberships/credits field. An unlimited plan (seed `price:"0"`) has no credit ceiling.
 
 ### Out of scope (do not build these)
 - **Completing/activating payment from code** — connecting a payments account, marking orders paid, forcing an order `ACTIVE`, "activating" a subscription server-side. Payment is the member's hosted-flow step or a merchant dashboard/config task, never frontend code (see the SCOPE callout under *Subscribing*).
diff --git a/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js b/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
index dcc50f65f..ce34d868e 100644
--- a/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
+++ b/skills/wix-vibe-headless/references/restaurants/wix-restaurants-ordering.js
@@ -54,7 +54,7 @@ export async function getDefaultOperation() {
  * Add a restaurant menu item to the visitor's current eCom cart.
  *
  * Requires operationId (from listOperations/getDefaultOperation), menuId, and sectionId.
- * Throws if any is missing, or if the added line is not AVAILABLE.
+ * Throws if any is missing, or if the added line's status is not IN_STOCK.
  *
  * Variant selection and modifier up-charges on the cart line are not covered here — the
  * restaurants catalogReference.options shape for those is not documented for client add-to-cart.
diff --git a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
index 1b60fe120..07d010667 100644
--- a/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
+++ b/skills/wix-vibe-headless/references/storefront/wix-store-cart.js
@@ -125,9 +125,8 @@ export async function checkout() {
 
 /**
  * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not catalogItemId.
- * In Cart V2 a quantity above remaining stock is rejected with an explicit error — V2 no longer
- * silently reduces it to the available amount (the V1 behavior), so handle the throw and show
- * the buyer what's in stock.
+ * In Cart V2 a quantity above remaining stock is rejected with an explicit error rather than
+ * silently reduced to the available amount, so handle the throw and show the buyer what's in stock.
  * @returns {Promise<object>} Updated cart.
  */
 export async function updateCartItemQuantity(lineItemId, quantity) {

From b47bf753f2a1b55389a8a092b1fdd6e6b6be47e3 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 16 Aug 2026 10:34:48 +0300
Subject: [PATCH 24/31] docs(ecom): de-duplicate pricing-plans
 membership-eligibility guidance

Trim the step-3 'which plan to apply' bullet to the evidence (paymentSummary.memberships = already-applied, not candidates) + a pointer; the full member-plans/live-coverage recipe stays in the single LIVE-read note below.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-pricing-plans.md      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 9204b14ca..b21420c1c 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -102,7 +102,7 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 2. **On `createBooking`, set `selectedPaymentOption: "MEMBERSHIP"`** (instead of `ONLINE`/`OFFLINE`). Enum values: `ONLINE`, `OFFLINE`, **`MEMBERSHIP`** (pay with a pricing plan), `MEMBERSHIP_OFFLINE`. Doc: <https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-writer-v2/create-booking.md?apiView=SDK>
 3. **The booking still rides the ecom cart** (Bookings is an ecom catalog, appId `13d21c63-b5ec-5912-8397-c3a5ddb27a97`) — the membership is applied **on the cart line item**, not on the booking object. Set membership selection on the line item via `updateLineItemsInCurrentCart`:
    - **Apply one** by setting the line item's `membershipPayment` via `currentCartV2.updateLineItemsInCurrentCart({ lineItems: [{ lineItemId: <booking line item id>, membershipPayment: { existingMembership: { membershipId, appId } } }] })` — `membershipId`/`appId` identify the member's existing plan membership (the Pricing Plans app); the line item reads it back as `paymentConfig.membership`. When the membership covers the full price, the calculated total drops to `0`.
-   - **Which plan to apply / eligibility:** there is **no** dedicated "eligible memberships for this line item" read on the current cart in V2 (`calculateCurrentCart` → `summary.paymentSummary.memberships` reports memberships **already applied**, not candidates). Determine eligibility from the member's active plans + live coverage instead — see the LIVE-read note below. **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
+   - **Which plan to apply / eligibility:** the cart has **no** candidate-memberships read in V2 — `calculateCurrentCart` → `summary.paymentSummary.memberships` lists memberships **already applied**, not candidates — so which plan to apply comes from the member's plans + live coverage (see the LIVE-read note below). **⚠️ VERIFY IN A LIVE BUILD** which `appId`/`membershipId` a headless member token must pass.
    Doc: <https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/update-line-items.md?apiView=SDK>
 4. **⚠️ Do NOT call `confirmBooking`** — for a membership payment Wix **auto-confirms** the booking on redemption (the same "no confirmBooking" rule as `how-to-code-bookings.md`; the membership drives confirmation).
 

From 99b883b24fceda5fdf29985f4328a0ab3ca9a34a Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 16 Aug 2026 12:00:32 +0300
Subject: [PATCH 25/31] docs(ecom): lead credit/session eligibility with the
 CartSummary/calculate signals

Rewrite the pricing-plans credit-plan note to surface what calculate/estimate DOES expose (summary.paymentSummary.memberships; the line's paymentConfig.membership.redemptionCost + redemptionType; over-limit as a summary.violations entry) before noting the one gap (remaining-balance/candidate read lives only on the deprecated legacy eligibleMemberships flow).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-pricing-plans.md      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index b21420c1c..1b33bfeeb 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -108,7 +108,7 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 
 - **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `membershipPayment.existingMembership` from the matched plan.
 - **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
-- **Credit/session plans:** a limited (non-unlimited) plan has a finite credit/session balance and stops covering bookings once it's used up — fold "is it exhausted?" into the eligibility decision above and treat an out-of-credits plan as not eligible. Don't try to read this off the cart: Cart V2 exposes no per-line eligible-memberships/credits field. An unlimited plan (seed `price:"0"`) has no credit ceiling.
+- **Credit/session plans:** for a limited (non-unlimited) plan, don't pre-read a balance — apply the membership, then `calculateCurrentCart`/`estimateCurrentCart`. The summary lists the applied memberships (`summary.paymentSummary.memberships`), the covered line's `paymentConfig.membership` carries `redemptionCost` (balance deducted for this booking; `0` = unlimited) + `redemptionType` (`CREDITS`/`SESSIONS`), and an exhausted/over-limit plan surfaces **explicitly** as a `summary.violations` entry (or an error at place-order) — treat that as "not eligible." What the cart does **not** expose is a remaining-balance/candidate read: `credits.remaining` lives only on the deprecated legacy `eligibleMemberships` flow. An unlimited plan (seed `price:"0"`) has no ceiling.
 
 ### Out of scope (do not build these)
 - **Completing/activating payment from code** — connecting a payments account, marking orders paid, forcing an order `ACTIVE`, "activating" a subscription server-side. Payment is the member's hosted-flow step or a merchant dashboard/config task, never frontend code (see the SCOPE callout under *Subscribing*).

From 01c20d41397645db2d00398f04bddba51333437d Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Sun, 16 Aug 2026 13:30:28 +0300
Subject: [PATCH 26/31] docs(ecom): credit balance is a Benefit-Program domain
 read, not an ecom-cart field

Point the remaining-balance note at the plan's Benefit-Program domain (same source as the coverage check) instead of the deprecated legacy eligibleMemberships; keep apply+calculate->violation as the primary path. The membership SPI is provider/server-side and stays out of this frontend recipe.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/inline-recipes/how-to-code-pricing-plans.md      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
index 1b33bfeeb..e0147ea89 100644
--- a/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
+++ b/skills/wix-headless/references/inline-recipes/how-to-code-pricing-plans.md
@@ -108,7 +108,7 @@ This is the payoff of the seed's STEP 2: a member who holds a plan that **covers
 
 - **⚠️ Eligibility / coverage is a LIVE read, never a hardcoded plan→service map.** A new eligible plan, or a service newly added to a plan's coverage in the backoffice, **must be honored with no code change** — so never freeze the seed-time `{ planId → serviceIds }` map into the frontend. Since Cart V2 has no per-line "eligible memberships" read, compute eligibility from the member's own plans against live coverage: list the member's active orders (`orders.memberListOrders`, `status: ACTIVE` within the date window) and match each `planId` against the plan's **live** Benefit-Program coverage (query the program's items — the same API `setup-pricing-plans.md` STEP 2 wrote to — at request time; do **not** read a coverage map baked into code). Set `selectedPaymentOption: "MEMBERSHIP"` on the booking + the line item's `membershipPayment.existingMembership` from the matched plan.
 - **⚠️ A `MEMBERSHIP` booking on a service the plan does NOT cover fails at checkout** (unless `skipSelectedPaymentOptionValidation`, which needs elevation — don't use in a member flow). Only offer "book with membership" for services actually covered by one of the member's active plans; otherwise fall back to the normal paid booking (`how-to-code-bookings.md`).
-- **Credit/session plans:** for a limited (non-unlimited) plan, don't pre-read a balance — apply the membership, then `calculateCurrentCart`/`estimateCurrentCart`. The summary lists the applied memberships (`summary.paymentSummary.memberships`), the covered line's `paymentConfig.membership` carries `redemptionCost` (balance deducted for this booking; `0` = unlimited) + `redemptionType` (`CREDITS`/`SESSIONS`), and an exhausted/over-limit plan surfaces **explicitly** as a `summary.violations` entry (or an error at place-order) — treat that as "not eligible." What the cart does **not** expose is a remaining-balance/candidate read: `credits.remaining` lives only on the deprecated legacy `eligibleMemberships` flow. An unlimited plan (seed `price:"0"`) has no ceiling.
+- **Credit/session plans:** for a limited (non-unlimited) plan, don't pre-read a balance — apply the membership, then `calculateCurrentCart`/`estimateCurrentCart`. The summary lists the applied memberships (`summary.paymentSummary.memberships`), the covered line's `paymentConfig.membership` carries `redemptionCost` (balance deducted for this booking; `0` = unlimited) + `redemptionType` (`CREDITS`/`SESSIONS`), and an exhausted/over-limit plan surfaces **explicitly** as a `summary.violations` entry (or an error at place-order) — treat that as "not eligible." The ecom cart itself carries no remaining-balance read; the balance is owned by the plan's **Benefit-Program** domain (the same source as the coverage check above), so if you need the actual number read it there — not off the cart. An unlimited plan (seed `price:"0"`) has no ceiling.
 
 ### Out of scope (do not build these)
 - **Completing/activating payment from code** — connecting a payments account, marking orders paid, forcing an order `ACTIVE`, "activating" a subscription server-side. Payment is the member's hosted-flow step or a merchant dashboard/config task, never frontend code (see the SCOPE callout under *Subscribing*).

From 4dbc6088e58e5b8b724fdae70375979fef62dd94 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Mon, 17 Aug 2026 11:03:20 +0300
Subject: [PATCH 27/31] docs(ecom): re-apply Cart V2 migration to main's
 rebuilt vibe-headless
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

main rebuilt wix-vibe-headless (new hooks/components, files moved to app/rest/) but left the REST layer on Cart V1 / Checkout V1. Migrate the storefront/restaurants/bookings REST helpers to Cart V2 — add-line-items/catalogItems, get current cart -> { cart }, update-line-items { lineItemId, quantity: { newQuantity } }, remove { lineItemIds }, and drop create-checkout in favor of the cart-id-is-checkout-id redirect-session. Align the 3 INSTRUCTIONS to V2 (ConvertedMoney money, status enum, attributes.*) with one migration-guide referral each. Exported function signatures unchanged, so main's hooks/context ride V2 unchanged; main's structure/components/Orders API untouched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../references/bookings/INSTRUCTIONS.md       |  2 +
 .../app/rest/wix-bookings-checkout.js         | 17 +++---
 .../references/restaurants/INSTRUCTIONS.md    |  5 +-
 .../app/rest/wix-restaurants-ordering.js      | 51 ++++++++--------
 .../references/storefront/INSTRUCTIONS.md     | 14 +++--
 .../storefront/app/rest/wix-store-cart.js     | 59 +++++++++----------
 6 files changed, 77 insertions(+), 71 deletions(-)

diff --git a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
index d142d223d..de5a7289a 100644
--- a/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md
@@ -165,6 +165,8 @@ stale render.
 ## Using the client from your own UI
 The two shipped hooks are the whole flow. If you build a custom surface, drive it the same way:
 
+> 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
 // LIST — every list helper returns an OBJECT, not a bare array. Destructure it:
 const { services, total, nextOffset } = await queryServices({ limit: 24 });   // total 0 → empty state
diff --git a/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js b/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js
index 1b844f42f..480bfd9be 100644
--- a/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js
+++ b/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js
@@ -3,7 +3,7 @@ import { wixApiRequest } from "./wix-client.js";
 // Data model reference: see INSTRUCTIONS.md
 // Service and TimeSlot shapes: see wix-bookings-services.js
 
-// Wix Bookings app id — required inside catalogReference for the eCommerce checkout.
+// Wix Bookings app id — required inside catalogReference when adding the booking to the eCom cart.
 const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97";
 
 /**
@@ -101,27 +101,28 @@ export async function createBooking(slot, contactDetails, { totalParticipants =
 }
 
 /**
- * Create an eCommerce checkout for a created booking and return the hosted checkout URL.
+ * Add a created booking to the current eCom cart and return the hosted checkout URL.
+ * In Cart V2 the cart id IS the checkout id — add the booking line to the current cart, then create
+ * the redirect session straight from that cart's id (there is no separate checkout-creation call).
  * Redirect the buyer there (window.location.href = ...). On return, the booking is confirmed.
  * Throws if no redirect URL is produced.
- * https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout.md
+ * https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items.md
  * @param {string} bookingId  booking.id from createBooking().
  * @returns {Promise<string>} The hosted-checkout URL to redirect to.
  */
 export async function checkoutBooking(bookingId) {
   if (!bookingId) throw new Error("checkoutBooking requires a bookingId.");
 
-  const checkoutRes = await wixApiRequest("/ecom/v1/checkouts", {
+  const cartRes = await wixApiRequest("/ecom/v2/carts/current/add-line-items", {
     method: "POST",
     body: {
-      channelType: "WEB",
-      lineItems: [
+      catalogItems: [
         { quantity: 1, catalogReference: { appId: BOOKINGS_APP_ID, catalogItemId: bookingId } },
       ],
     },
   });
-  const checkoutId = checkoutRes?.checkout?.id;
-  if (!checkoutId) throw new Error("Failed to create a checkout for the booking.");
+  const checkoutId = cartRes?.cart?.id;
+  if (!checkoutId) throw new Error("Failed to add the booking to the cart for checkout.");
 
   const redirect = await wixApiRequest("/headless/v1/redirect-session", {
     method: "POST",
diff --git a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
index 8fa140984..df5636620 100644
--- a/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/restaurants/INSTRUCTIONS.md
@@ -170,6 +170,8 @@ render.
 
 ## Using the client from your own UI (menu, order cart)
 
+> 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 { getFullMenu } from "@/rest/wix-restaurants-menu";
 import { useOrderCart } from "@/context/OrderCartContext";
@@ -188,7 +190,8 @@ const { menus } = await getFullMenu();            // [] when no menus → show t
 // Load-bearing field paths (the shipped components already do these):
 // - item.image / section.image / label.icon are OBJECTS → render `.url`, never the object; //-urls → https:
 // - MENU prices are plain decimal strings with NO currency symbol ("12.50") — format in the UI.
-//   The eCom cart line price (line.price.formattedAmount) DOES include the symbol.
+//   The eCom cart line price (line.pricing.unitPrice / line.pricing.totalPrice) is a ConvertedMoney
+//   { amount, convertedAmount } with NO symbol either — format the number yourself.
 // - an item is priced by EITHER item.price (single) OR item.variants[] (one-of, each { name, price }).
 // - a cart mutation uses cart.lineItems[].id (the lineItemId), NOT the menu item id.
 ```
diff --git a/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js b/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
index c7ac7fa2a..f0dd1e871 100644
--- a/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
+++ b/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, currency {string},
  *   lineItems[].id {string} — lineItemId for update/remove (NOT the item id),
- *   lineItems[].quantity {number},
+ *   lineItems[].quantityInfo.confirmedQuantity {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[].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,15 @@ 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}).`);
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`Item not available to order (status: ${line.status}).`);
   }
   return res?.cart;
 }
@@ -90,7 +91,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 +100,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 +125,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 +136,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(", ");
     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.");
diff --git a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
index 356ef6b1d..c89a10577 100644
--- a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
+++ b/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,17 @@ 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 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 cart.currency) so the symbol and grouping match the locale. 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.
+// 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 +298,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
 ```
 
 Fallback only — when you hit an error or need something not shown here (coupons, members, a field
diff --git a/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js b/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
index 28caf7cd9..778b754e4 100644
--- a/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
+++ b/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 {string},
  *   lineItems[].id {string} — lineItemId for update/remove (NOT catalogItemId),
- *   lineItems[].quantity {number},
+ *   lineItems[].quantityInfo.confirmedQuantity {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[].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[].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 {string},
+ *   lineItems[].status {string} — "IN_STOCK"|"PARTIALLY_IN_STOCK"|"OUT_OF_STOCK"|"REMOVED_FROM_CATALOG"
  */
 
 /**
@@ -52,20 +54,21 @@ 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 }] },
   });
   const line = (res?.cart?.lineItems ?? []).find(
     (l) => l.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.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 +84,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 +92,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 +103,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(", ");
     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 +121,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 +138,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] },
   });

From 491a79a1358cd413f073a66b20b037c8ba5c30a9 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Mon, 17 Aug 2026 11:39:49 +0300
Subject: [PATCH 28/31] docs(ecom): migrate vibe-headless cart UI consumers to
 Cart V2 fields

The REST helpers return the raw V2 cart, but main's rebuilt React cart UI still read V1 line-item paths (broken cart). Migrate the storefront + restaurants cart consumers (CartContext/CartDrawer/OrderCartContext/OrderCartDrawer): quantity -> quantityInfo.confirmedQuantity; money -> pricing.unitPrice/totalPrice (ConvertedMoney, formatted client-side via a local formatCartMoney using businessInfo/customerInfo currencyCode); availability -> top-level status enum; image -> attributes.image.url (object); name -> name.original; subtotal from cart.subtotal (V2 keeps no discounted totals on the cart). Fix helper/doc field bugs (productName->name in both checkout() error maps + JSDoc, attributes.image object, stale root currency, bookings doc link) and the storefront INSTRUCTIONS cart-money paragraph. Product/catalog/reservation reads untouched. Independently re-reviewed: fully V2, no V1 cart reads remain.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../app/rest/wix-bookings-checkout.js         |  2 +-
 .../app/components/OrderCartDrawer.jsx        | 34 ++++++---
 .../app/context/OrderCartContext.jsx          |  2 +-
 .../app/rest/wix-restaurants-ordering.js      |  6 +-
 .../references/storefront/INSTRUCTIONS.md     | 11 +--
 .../storefront/app/components/CartDrawer.jsx  | 72 +++++++++----------
 .../storefront/app/context/CartContext.jsx    |  4 +-
 .../storefront/app/rest/wix-store-cart.js     |  8 +--
 8 files changed, 76 insertions(+), 63 deletions(-)

diff --git a/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js b/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js
index 480bfd9be..ef81c471a 100644
--- a/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js
+++ b/skills/wix-vibe-headless/references/bookings/app/rest/wix-bookings-checkout.js
@@ -106,7 +106,7 @@ export async function createBooking(slot, contactDetails, { totalParticipants =
  * the redirect session straight from that cart's id (there is no separate checkout-creation call).
  * Redirect the buyer there (window.location.href = ...). On return, the booking is confirmed.
  * Throws if no redirect URL is produced.
- * https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items.md
+ * https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md
  * @param {string} bookingId  booking.id from createBooking().
  * @returns {Promise<string>} The hosted-checkout URL to redirect to.
  */
diff --git a/skills/wix-vibe-headless/references/restaurants/app/components/OrderCartDrawer.jsx b/skills/wix-vibe-headless/references/restaurants/app/components/OrderCartDrawer.jsx
index f10fcac31..e6fc1c1cf 100644
--- a/skills/wix-vibe-headless/references/restaurants/app/components/OrderCartDrawer.jsx
+++ b/skills/wix-vibe-headless/references/restaurants/app/components/OrderCartDrawer.jsx
@@ -1,9 +1,18 @@
 // Slide-over order cart. Reads everything from useOrderCart(); mutate by lineItem.id (NOT the menu
-// item id), check out via the context (redirect-session URL). The eCom cart price
-// (line.price.formattedAmount) DOES include the currency symbol, unlike menu prices. Styled with
-// base44 design tokens (shadcn Tailwind classes). Mount it once in the Layout.
+// item id), check out via the context (redirect-session URL). The eCom Cart V2 line price is
+// `pricing.totalPrice`, a ConvertedMoney { amount, convertedAmount } with NO formatted string —
+// format it with the cart's currency (formatCartMoney below). Styled with base44 design tokens
+// (shadcn Tailwind classes). Mount it once in the Layout.
 import { useOrderCart } from "@/context/OrderCartContext";
 
+// 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 OrderCartDrawer() {
   const { cart, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading } = useOrderCart();
   const lineItems = cart?.lineItems ?? [];
@@ -22,23 +31,26 @@ export default function OrderCartDrawer() {
         <div className="flex-1 overflow-y-auto p-4">
           {lineItems.length === 0 ? (
             <p className="text-muted-foreground">Your order is empty.</p>
-          ) : lineItems.map((line) => (
+          ) : lineItems.map((line) => {
+            const qty = line.quantityInfo?.confirmedQuantity;
+            return (
             <div key={line.id} className="flex gap-3 py-3 border-b border-border">
               {/* line.id is the lineItemId for mutations — NOT the menu item id */}
               <div className="flex-1 flex flex-col gap-1">
-                <span className="font-semibold">{line.productName?.original}</span>
+                <span className="font-semibold">{line.name?.original}</span>
                 <div className="flex items-center gap-2 mt-1">
-                  <QtyButton onClick={() => updateQuantity(line.id, Math.max(1, line.quantity - 1))}>−</QtyButton>
-                  <span className="min-w-[20px] text-center">{line.quantity}</span>
-                  <QtyButton onClick={() => updateQuantity(line.id, line.quantity + 1)}>+</QtyButton>
+                  <QtyButton onClick={() => updateQuantity(line.id, Math.max(1, qty - 1))}>−</QtyButton>
+                  <span className="min-w-[20px] text-center">{qty}</span>
+                  <QtyButton onClick={() => updateQuantity(line.id, qty + 1)}>+</QtyButton>
                   <button onClick={() => removeItem(line.id)}
                     className="ml-auto border-none bg-transparent cursor-pointer text-muted-foreground text-[13px] underline">Remove</button>
                 </div>
               </div>
-              {/* eCom cart price DOES include the currency symbol (unlike menu prices) */}
-              <span className="font-semibold">{line.price?.formattedAmount}</span>
+              {/* Cart V2 has no formatted string — format the ConvertedMoney client-side */}
+              <span className="font-semibold">{formatCartMoney(line.pricing?.totalPrice, cart)}</span>
             </div>
-          ))}
+            );
+          })}
         </div>
 
         {lineItems.length > 0 && (
diff --git a/skills/wix-vibe-headless/references/restaurants/app/context/OrderCartContext.jsx b/skills/wix-vibe-headless/references/restaurants/app/context/OrderCartContext.jsx
index 4a465527c..afe3623f0 100644
--- a/skills/wix-vibe-headless/references/restaurants/app/context/OrderCartContext.jsx
+++ b/skills/wix-vibe-headless/references/restaurants/app/context/OrderCartContext.jsx
@@ -30,7 +30,7 @@ export function OrderCartProvider({ 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);
 
   // A menu item carries its menuId/sectionId from the getFullMenu tree — the caller passes both.
   // addItemToCart throws on a missing operation/menu/section or an unavailable line; let it propagate.
diff --git a/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js b/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
index f0dd1e871..f72228d2b 100644
--- a/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
+++ b/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
@@ -12,11 +12,11 @@ import { wixApiRequest } from "./wix-client.js";
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/restaurants/online-orders/operations/operation-object.md
  *
  * Cart (Wix eCom V2) — restaurant orders use the same visitor cart as the storefront.
- *   id {string} — the cart id IS the checkout id, currency {string},
+ *   id {string} — the cart id IS the checkout id,
  *   lineItems[].id {string} — lineItemId for update/remove (NOT the item id),
  *   lineItems[].quantityInfo.confirmedQuantity {number},
  *   lineItems[].catalogReference.catalogItemId {string} — the ordered item's GUID,
- *   lineItems[].productName.original {string},
+ *   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"
@@ -138,7 +138,7 @@ export async function checkout() {
   if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
   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.catalogReference?.catalogItemId).join(", ");
     throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
   }
   if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");
diff --git a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
index c89a10577..f3e01c32d 100644
--- a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
@@ -253,10 +253,13 @@ import { useCart } from "@/context/CartContext";
 //
 // 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 cart.currency) so the symbol and grouping match the locale. 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.
+// 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.
 
diff --git a/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx b/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx
index 93f9dae3d..38dd9d783 100644
--- a/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx
+++ b/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,19 +77,19 @@ 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>
+                  <span className="font-semibold truncate">{item.name?.original}</span>
                   {item.descriptionLines?.map((dl, i) => (
                     <small key={i} className="text-muted-foreground">
                       {dl.name?.original}: {dl.plainText?.original || dl.colorInfo?.original}
@@ -90,26 +97,23 @@ export default function CartDrawer() {
                   ))}
                   {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 +122,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>
diff --git a/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx b/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx
index 952ae52c5..75036f10b 100644
--- a/skills/wix-vibe-headless/references/storefront/app/context/CartContext.jsx
+++ b/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
diff --git a/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js b/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
index 778b754e4..cf0ac69e3 100644
--- a/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
+++ b/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
@@ -10,18 +10,18 @@ const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
  * 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} — the cart id IS the checkout id, 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[].quantityInfo.confirmedQuantity {number},
  *   lineItems[].catalogReference.catalogItemId {string},
- *   lineItems[].productName.original {string},
+ *   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[].descriptionLines {array} — human-readable option/modifier labels:
  *     [{ name: { original }, plainText: { original } OR colorInfo: { original, code } }],
- *   lineItems[].attributes.image {string},
+ *   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"
  */
 
@@ -105,7 +105,7 @@ export async function checkout() {
   if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
   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.catalogReference?.catalogItemId).join(", ");
     throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
   }
   if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");

From f39a9959a87c0be2ab1ce25a950fb4f9708ce228 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Mon, 17 Aug 2026 11:51:17 +0300
Subject: [PATCH 29/31] test(evalforge): add coverage scenarios for the
 V2-migrated wix-manage ecom docs

The V1->V2 migration edited booking-system-integration-gaps, end-to-end-booking-flow, and cms-ecommerce-catalog-integration; the EvalForge YAML gate requires a covering scenario per changed doc. Add three scenarios (ReadFullDocsArticle coverage assertion at each doc's URL + a V2-aware llm_judge that passes on Cart V2 create-cart/place-order and fails on Checkout V1).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../booking-ecom-payment-integration.yml      | 37 +++++++++++++++++++
 .../bookings/end-to-end-booking-flow.yml      | 36 ++++++++++++++++++
 .../cms/cms-ecommerce-catalog-integration.yml | 35 ++++++++++++++++++
 3 files changed, 108 insertions(+)
 create mode 100644 yaml/wix-manage-evals/bookings/booking-ecom-payment-integration.yml
 create mode 100644 yaml/wix-manage-evals/bookings/end-to-end-booking-flow.yml
 create mode 100644 yaml/wix-manage-evals/cms/cms-ecommerce-catalog-integration.yml

diff --git a/yaml/wix-manage-evals/bookings/booking-ecom-payment-integration.yml b/yaml/wix-manage-evals/bookings/booking-ecom-payment-integration.yml
new file mode 100644
index 000000000..9b1139163
--- /dev/null
+++ b/yaml/wix-manage-evals/bookings/booking-ecom-payment-integration.yml
@@ -0,0 +1,37 @@
+name: bookings/booking-ecom-payment-integration
+description: >-
+  Verifies the agent reads the booking system integration gaps reference and explains
+  the undocumented booking-to-ecommerce payment pattern using the Cart V2 flow.
+triggerPrompt: >-
+  I created a paid appointment booking through the Wix Bookings API, but I don't see how
+  the customer actually pays. Why do bookings need the ecommerce APIs, and what is the
+  exact sequence of calls to take payment for a booking? Just written REST instructions,
+  no live API call.
+tags: [bookings]
+assertions:
+  - tool: ReadFullDocsArticle
+    params:
+      articleUrl: https://dev.wix.com/docs/api-reference/business-solutions/bookings/skills/booking-system-integration-gaps
+  - type: llm_judge
+    minScore: 7
+    maxTokens: 2048
+    prompt: |
+      The user has a paid booking and wants to know why ecommerce APIs are needed and the exact
+      call sequence to take payment. Evaluate both the final response and any Wix API/tool calls made.
+      Intent: explain the undocumented Bookings -> Ecommerce integration and the Cart V2 payment flow.
+
+      Pass if the response:
+      - explains the booking system only reserves the time slot and the ecommerce system handles all
+        pricing, tax, and payment, AND
+      - uses the booking ID as the ecom `catalogItemId` (with the Wix Bookings appId in the catalogReference), AND
+      - creates a cart via `POST /ecom/v2/carts` with `catalogItems`, AND
+      - calculates the cart to obtain a `priceVerificationToken` and then places the order via
+        `POST /ecom/v2/carts/{cartId}/place-order` passing that token, AND
+      - states that booking status (CONFIRMED) is independent of payment/order status.
+
+      Fail if the response:
+      - uses Checkout V1 (e.g. `/ecom/v1/checkouts`, a create-checkout step, `createOrder`, or `lineItems`
+        instead of `catalogItems`), OR
+      - claims the Bookings API processes the payment itself, OR
+      - omits the create-cart or place-order step, OR
+      - ties booking confirmation directly to payment success.
diff --git a/yaml/wix-manage-evals/bookings/end-to-end-booking-flow.yml b/yaml/wix-manage-evals/bookings/end-to-end-booking-flow.yml
new file mode 100644
index 000000000..1fa0a8410
--- /dev/null
+++ b/yaml/wix-manage-evals/bookings/end-to-end-booking-flow.yml
@@ -0,0 +1,36 @@
+name: bookings/end-to-end-booking-flow
+description: >-
+  Verifies the agent reads the end-to-end booking flow reference and describes the full
+  REST flow, using the Cart V2 create-cart step for online-payment bookings.
+triggerPrompt: >-
+  Walk me through implementing a complete booking experience end to end with the Wix REST APIs,
+  from finding services to taking payment for an online-paid appointment. Written REST instructions
+  only, no live API call.
+tags: [bookings]
+assertions:
+  - tool: ReadFullDocsArticle
+    params:
+      articleUrl: https://dev.wix.com/docs/api-reference/business-solutions/bookings/skills/end-to-end-booking-flow
+  - type: llm_judge
+    minScore: 7
+    maxTokens: 2048
+    prompt: |
+      The user asked for a complete end-to-end booking flow, including payment for an online-paid
+      appointment. Evaluate both the final response and any Wix API/tool calls made.
+      Intent: describe the full flow (query services -> availability -> create booking -> confirm or pay)
+      using the correct Cart V2 flow for online payments.
+
+      Pass if the response:
+      - queries services and checks availability with Time Slots V2 (not the deprecated availability calendar), AND
+      - creates a booking with the appointment `slot` structure and notes the booking starts as `CREATED`, AND
+      - for free/offline bookings confirms directly, and for online payments creates a cart via
+        `POST /ecom/v2/carts` with `catalogItems` using the booking ID as `catalogItemId`, AND
+      - to place the order server-side, calculates the cart for a `priceVerificationToken` then calls
+        `POST /ecom/v2/carts/{cartId}/place-order`, AND
+      - notes the booking is auto-confirmed after online payment.
+
+      Fail if the response:
+      - uses Checkout V1 for the payment step (e.g. `/ecom/v1/checkouts`, a create-checkout call,
+        `createOrder`, or `lineItems` instead of `catalogItems`), OR
+      - uses the deprecated availability query instead of Time Slots V2, OR
+      - omits the create-booking or the online-payment cart step.
diff --git a/yaml/wix-manage-evals/cms/cms-ecommerce-catalog-integration.yml b/yaml/wix-manage-evals/cms/cms-ecommerce-catalog-integration.yml
new file mode 100644
index 000000000..d1d3cc4c1
--- /dev/null
+++ b/yaml/wix-manage-evals/cms/cms-ecommerce-catalog-integration.yml
@@ -0,0 +1,35 @@
+name: cms/cms-ecommerce-catalog-integration
+description: >-
+  Verifies the agent reads the CMS eCommerce catalog integration reference and explains
+  how to sell CMS collection items through Wix Cart V2 via the CATALOG plugin.
+triggerPrompt: >-
+  I have a Wix CMS collection of event tickets with name and price fields, and I want to sell them
+  through Wix checkout. How do I turn the collection into a purchasable catalog and add an item to
+  a cart? Written REST instructions only, no live API call.
+tags: [cms]
+assertions:
+  - tool: ReadFullDocsArticle
+    params:
+      articleUrl: https://dev.wix.com/docs/api-reference/business-solutions/cms/skills/cms-e-commerce-catalog-integration
+  - type: llm_judge
+    minScore: 7
+    maxTokens: 2048
+    prompt: |
+      The user wants to sell items from a CMS collection through Wix checkout. Evaluate both the final
+      response and any Wix API/tool calls made.
+      Intent: add the CATALOG plugin to the collection and use the CMS catalog items in the Cart V2 flow.
+
+      Pass if the response:
+      - adds the CATALOG plugin via `POST /wix-data/v2/collections/add-plugin`, mapping at least the
+        `name` and `price` fields in `catalogOptions`, AND
+      - uses the CMS appId `e593b0bd-b783-45b8-97c2-873d42aacaf4` in the `catalogReference`, AND
+      - adds the item to a cart using the Cart V2 API with `catalogItems` (e.g. create cart via
+        `POST /ecom/v2/carts` or add via `POST /ecom/v2/carts/{cartId}/add-line-items`), AND
+      - correctly represents CMS catalogs versus Wix Stores (e.g. manual variants/inventory).
+
+      Fail if the response:
+      - uses Checkout/Cart V1 (e.g. `/ecom/v1/checkouts`, a create-checkout step, or `lineItems`
+        instead of `catalogItems`), OR
+      - invents a different CMS appId, OR
+      - omits adding the CATALOG plugin before using the item in a cart, OR
+      - tells the user they must migrate the collection into Wix Stores to sell it.

From 854b6d639df5ad9ad4a51ab9cba951cc8f27f752 Mon Sep 17 00:00:00 2001
From: rommy-amitai-w <rommya@wix.com>
Date: Mon, 17 Aug 2026 13:58:18 +0300
Subject: [PATCH 30/31] revert(wix-app): drop the backend-event + site-plugin
 cart-v2 edits

Scope the PR to the ecommerce storefront skills (stores/bookings/restaurants/pricing-plans) + the given resources. The wix-app backend-event (cart events) and site-plugin (currentCart) docs are outside that scope and their eval areas have no coverage scenarios; reverting them to main clears the (non-blocking) wix-app coverage gate without adding scenarios for an out-of-scope area. Their V1->V2 migration is left to the wix-app owners with their own eval coverage.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 skills/wix-app/references/SITE_PLUGIN.md                 | 4 ++--
 skills/wix-app/references/backend-event/COMMON-EVENTS.md | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/skills/wix-app/references/SITE_PLUGIN.md b/skills/wix-app/references/SITE_PLUGIN.md
index 3f6207968..85c20be7d 100644
--- a/skills/wix-app/references/SITE_PLUGIN.md
+++ b/skills/wix-app/references/SITE_PLUGIN.md
@@ -324,14 +324,14 @@ Site plugins can import and use Wix SDK modules directly — you do NOT need `cr
 ```typescript
 // ✅ CORRECT — Import SDK modules directly
 import { items } from "@wix/data";
-import { currentCartV2 } from "@wix/ecom";
+import { currentCart } from "@wix/ecom";
 import { products } from "@wix/stores";
 
 class MyPlugin extends HTMLElement {
   async loadData() {
     // Call SDK methods directly — no createClient needed
     const result = await items.query("MyCollection").find();
-    const { cart } = await currentCartV2.getCurrentCart();
+    const cart = await currentCart.getCurrentCart();
     const productList = await products.queryProducts().limit(10).find();
   }
 }
diff --git a/skills/wix-app/references/backend-event/COMMON-EVENTS.md b/skills/wix-app/references/backend-event/COMMON-EVENTS.md
index 4cdba5b7f..24d21e88b 100644
--- a/skills/wix-app/references/backend-event/COMMON-EVENTS.md
+++ b/skills/wix-app/references/backend-event/COMMON-EVENTS.md
@@ -21,8 +21,8 @@ Order events use **`@wix/ecom`** (namespace `orders`). Order **refund** events a
 | Order canceled | `import { orders } from "@wix/ecom"` | `orders.onOrderCanceled(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onOrderCanceled](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-canceled?apiView=SDK) |
 | Refund created | `import { refunds } from "@wix/payments"` | `refunds.onRefundCreated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundCreated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-created?apiView=SDK) |
 | Refund updated | `import { refunds } from "@wix/payments"` | `refunds.onRefundUpdated(handler)` | `SCOPE.DC-PAYMENTS.READ-REFUNDS` | [onRefundUpdated](https://dev.wix.com/docs/api-reference/business-management/payments/refunds/refund-updated?apiView=SDK) |
-| Cart created | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-created?apiView=SDK) |
-| Cart updated | `import { cartV2 } from "@wix/ecom"` | `cartV2.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/cart-updated?apiView=SDK) |
+| Cart created | `import { cart } from "@wix/ecom"` | `cart.onCartCreated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartCreated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-created?apiView=SDK) |
+| Cart updated | `import { cart } from "@wix/ecom"` | `cart.onCartUpdated(handler)` | `SCOPE.DC-STORES.READ-ORDERS` | [onCartUpdated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/cart-updated?apiView=SDK) |
 
 ## Bookings Events
 

From 325f7f9146b36281ae1d5d2a1d3605a8e09adba8 Mon Sep 17 00:00:00 2001
From: ayal <ayal@wix.com>
Date: Thu, 20 Aug 2026 16:57:06 +0300
Subject: [PATCH 31/31] =?UTF-8?q?fix(vibe-headless):=20read=20V2=20line-it?=
 =?UTF-8?q?em=20paths=20=E2=80=94=20source.catalogReference,=20attributes.?=
 =?UTF-8?q?descriptionLines?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cart V2 moved two line-item fields the migrated helpers still read at their
V1 locations (verified against live /ecom/v2 responses and the latest
@wix/ecom types):

- catalogReference now lives at lineItem.source.catalogReference (options
  included), so addToCart's post-add find never matched and every successful
  add threw "Item could not be added to cart"; the restaurants helper's
  unbuyable-line guard was dead code for the same reason.
- descriptionLines now lives at lineItem.attributes.descriptionLines, so the
  CartDrawer never rendered option/modifier labels.

Also fixes the checkout() error-message fallbacks, both docblocks, and the
INSTRUCTIONS image path (attributes.image is an object; the URL is .url).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../restaurants/app/rest/wix-restaurants-ordering.js     | 7 ++++---
 .../references/storefront/INSTRUCTIONS.md                | 2 +-
 .../references/storefront/app/components/CartDrawer.jsx  | 3 ++-
 .../references/storefront/app/rest/wix-store-cart.js     | 9 +++++----
 4 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js b/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
index f72228d2b..60dcb2fdb 100644
--- a/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
+++ b/skills/wix-vibe-headless/references/restaurants/app/rest/wix-restaurants-ordering.js
@@ -15,7 +15,7 @@ import { wixApiRequest } from "./wix-client.js";
  *   id {string} — the cart id IS the checkout id,
  *   lineItems[].id {string} — lineItemId for update/remove (NOT the item id),
  *   lineItems[].quantityInfo.confirmedQuantity {number},
- *   lineItems[].catalogReference.catalogItemId {string} — the ordered item's GUID,
+ *   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,
@@ -81,7 +81,8 @@ export async function addItemToCart(itemId, { operationId, menuId, sectionId, on
       catalogItems: [{ catalogReference: { appId: RESTAURANTS_ORDERS_APP_ID, catalogItemId: itemId, options }, quantity }],
     },
   });
-  const line = (res?.cart?.lineItems ?? []).find((l) => l.catalogReference?.catalogItemId === itemId);
+  // 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}).`);
   }
@@ -138,7 +139,7 @@ export async function checkout() {
   if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
   const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
   if (unavailable.length) {
-    const names = unavailable.map((l) => l.name?.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}.`);
   }
   if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");
diff --git a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
index f3e01c32d..537165c7b 100644
--- a/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
+++ b/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md
@@ -301,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[].attributes.image
+// 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
diff --git a/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx b/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx
index 38dd9d783..5fff59879 100644
--- a/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx
+++ b/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx
@@ -90,7 +90,8 @@ export default function CartDrawer() {
                 </div>
                 <div className="flex-1 flex flex-col gap-1 min-w-0">
                   <span className="font-semibold truncate">{item.name?.original}</span>
-                  {item.descriptionLines?.map((dl, i) => (
+                  {/* 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>
diff --git a/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js b/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
index cf0ac69e3..a823f0baa 100644
--- a/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
+++ b/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js
@@ -13,13 +13,13 @@ const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
  *   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[].quantityInfo.confirmedQuantity {number},
- *   lineItems[].catalogReference.catalogItemId {string},
+ *   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[].descriptionLines {array} — human-readable option/modifier labels:
+ *   lineItems[].attributes.descriptionLines {array} — human-readable option/modifier labels:
  *     [{ name: { original }, plainText: { original } OR colorInfo: { original, code } }],
  *   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"
@@ -58,8 +58,9 @@ export async function addToCart(catalogItemId, variantId, quantity = 1, { modifi
     method: "POST",
     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),
   );
   // Cart V2 rejects an unbuyable line with an explicit error rather than silently dropping it, but
   // guard both signals defensively:
@@ -105,7 +106,7 @@ export async function checkout() {
   if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
   const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
   if (unavailable.length) {
-    const names = unavailable.map((l) => l.name?.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}.`);
   }
   if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");