Skip to content

Migrate all storefront templates to Cart V2 - #696

Merged
kfirstri merged 13 commits into
wix:mainfrom
rommy-amitai-w:cart-v2-migration
Sep 6, 2026
Merged

Migrate all storefront templates to Cart V2#696
kfirstri merged 13 commits into
wix:mainfrom
rommy-amitai-w:cart-v2-migration

Conversation

@rommy-amitai-w

@rommy-amitai-w rommy-amitai-w commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What

Migrates every Cart V1 + Checkout V1 usage across the runnable templates to the unified Cart V2 API (@wix/ecom currentCartV2 / cartV2). Both V1 APIs are removed 2027-02-01 (migration guide · mapping).

Renames taken from those guides, cross-checked against the wix-private/ecom CartV1Proxy Scala mappers, and the cart API surface is compiler-verified against the real public @wix/ecom types (see below).

Templates migrated

astro/commerce, astro/scheduler, nextjs/commerce, nextjs/commerce-ticketing, nextjs/minimal-examples, react-native/mobile-ecommerce, plus AGENTS.md.

Key changes (V1 → V2)

  • addToCurrentCart({ lineItems }) → addLineItemsToCurrentCart({ catalogItems })
  • getCurrentCart() now returns { cart } (optional — guarded/asserted); ids are _id
  • updateCurrentCartLineItemQuantity(...) → updateLineItemsInCurrentCart({ lineItems: [{ lineItemId, quantity: { newQuantity } }] })
  • removeLineItemsFromCurrentCart([ids]) — positional array in the SDK (not an options object)
  • estimateCurrentCartTotals() → estimateCurrentCart() → summary.priceSummary
  • Checkout: dropped createCheckoutFromCurrentCart / checkout.createCheckout; feed the cart's _id to redirects.createRedirectSession (cart id is the checkout id). astro/scheduler's createOrder → cartV2.placeOrder(cartId, { priceVerificationToken }) (token from calculateCart). "Buy Now"/quick-buy use cartV2.createCart (isolated cart), returning the Cart directly.
  • Line-item read shapes: quantity→quantityInfo.confirmedQuantity, productName→name, price→pricing.unitPrice/totalPrice, image/url/descriptionLines→attributes.*, availability.status→status.
  • overrideCheckoutUrl → customCheckoutUrl, placeholder token {checkout_id} (snake_case; the only token V2 substitutes).
  • Client-side money formatting everywhere V1 relied on formattedAmount — all V2 cart money (line items and summary.priceSummary) is raw ConvertedMoney; prefer convertedAmount ?? amount.
  • astro/commerce @wix/ecom pin loosened so cartV2/currentCartV2 resolve.

Compiler verification (embargo workaround)

A full npm install/build is blocked by the org npm embargo, so every Cart V2 call + read-shape was compiled against the real public @wix/ecom types (already installed). This deterministically validated the cart surface and caught real issues that manual review missed — now fixed:

  • removeLineItemsFromCurrentCart is positional, not { lineItemIds }
  • cart line-item type is cartV2.V2LineItem, not cartV2.LineItem
  • getCurrentCart().cart is optional → CartView deref now guarded
  • membershipPayment is @internal (docs recipe uses the public selectedMembership)

Behavior note (react-native)

V1 applied buyer-note + coupon on the checkout entity; V2 applies them on the cart — note via updateCurrentCart({ note }), coupon via addCouponToCurrentCart({ code }). Please confirm in the live test.

Testing — ⚠️ NOT yet run against a live site or a full build

Every changed file parses (Babel) and the cart API surface is compiler-clean against real types. But the full tsc/next build is blocked by the org npm embargo (registry.npmjs.org blackholed; Wix mirror lacks some public versions) and no template has been run against a real store. Before merge: run tsc/next build + a smoke test (cart render + checkout redirect) once the embargo lifts or in a sanctioned env. Residual risk is non-cart TS glue + runtime behavior; the migrated cart surface itself is verified.

Requires

@wix/ecom version exporting cartV2 / currentCartV2.

Companion PR: wix/skills#855

@rommy-amitai-w @claude
chore(commerce): migrate astro storefront to Cart V2
08a23e5 
Migrates the astro/commerce template from @wix/ecom currentCart (Cart V1 +
Checkout V1) to currentCartV2 (Cart V2). Both V1 APIs are removed 2027-02-01.

- currentCart.addToCurrentCart -> currentCartV2.addLineItemsToCurrentCart
  (lineItems -> catalogItems)
- getCurrentCart() now returns { cart } (destructured)
- estimateCurrentCartTotals -> estimateCurrentCart; totals under summary.priceSummary
- No checkout entity: feed the current cart's _id to createRedirectSession
  (cart id is the checkout id) instead of createCheckoutFromCurrentCart
- Line-item read shapes moved (quantityInfo.confirmedQuantity, name, pricing,
  attributes.image); added a client-side money formatter since V2 line-item
  prices are raw ConvertedMoney (no formatted string)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@netlify

netlify Bot commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

👷 Deploy request for wix-classes-subscriptions-nextjs pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit e76dda8

@netlify

netlify Bot commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

👷 Deploy request for wix-appointments-subscriptions-nextjs pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit e76dda8

@netlify

netlify Bot commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

👷 Deploy request for wix-cms-nextjs-template pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit e76dda8

@netlify

netlify Bot commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

👷 Deploy request for wix-headless-example pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit e76dda8

@netlify

netlify Bot commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

👷 Deploy request for wix-commerce-ticketing-nextjs pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit e76dda8

@rommy-amitai-w rommy-amitai-w mentioned this pull request Aug 5, 2026
Merged
@rommy-amitai-w @claude
chore(templates): migrate remaining storefronts to Cart V2
8598e45 
Extends the Cart V2 migration to every remaining Cart V1 / Checkout V1
usage across the runnable templates (mappings verified against the ecom
CartV1Proxy Scala V1<->V2 mappers):

- nextjs/commerce: reshapeCart + full cart/checkout flow (price->pricing,
  quantity->quantityInfo.confirmedQuantity, productName->name,
  descriptionLines/url/image->attributes.*, currency->businessInfo/customerInfo)
- nextjs/commerce-ticketing: all cart hooks/components + quick-buy
  (createCart catalogItems, overrideCheckoutUrl->customCheckoutUrl,
  updateCurrentCart(cart) shape)
- react-native/mobile-ecommerce: add/update/remove/get + redirect checkout;
  coupon+note re-applied via addCouponToCurrentCart + updateCurrentCart note
- nextjs/minimal-examples: store + installed-apps demos
- astro/scheduler: booking checkout -> createCart + calculateCart + placeOrder
- AGENTS.md: totals guidance -> estimateCurrentCart/calculateCart summary

All redirect sessions keep @wix/redirects, fed the cart id (which is the
checkout id in V2). Templates not run against a live site.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w rommy-amitai-w changed the title Migrate astro/commerce storefront to Cart V2 Migrate all storefront templates to Cart V2 Aug 6, 2026
rommy-amitai-w and others added 10 commits August 6, 2026 11:12
@rommy-amitai-w @claude
fix(templates): correct V2 read-shape bugs from independent review
652ddca 
- commerce-ticketing CartItem: item.url/item.image -> item.attributes.url/
  .image (build-breaking + broken link/thumbnail); name .translated ?? .original
- astro/commerce + minimal-examples: subtotal was reading nonexistent
  summary.priceSummary.subtotal.formattedAmount (V2PriceSummary is
  ConvertedMoney, no formatted string) -> format client-side
- AGENTS.md: all V2 cart money (line items AND summary) is raw ConvertedMoney

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
fix(templates): address 2nd independent review (2 MAJOR + minor/nit)
32f7434 
- minimal-examples/store.js: subtotal went stale after add/update (computed
  only on mount) — re-fetch (cart + estimate) after each mutation
- react-native ProductScreen "Buy Now": was polluting the persistent current
  cart; now creates an isolated cart via cartV2.createCart and redirects to it
  (register cartV2 in wixClient)
- prefer pricing.convertedAmount ?? amount for display-currency correctness
  (nextjs/commerce reshapeCart, commerce-ticketing CartView/CartItem)
- CartItem: name?.translated ?? name?.original in the non-linked branch too

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
fix(templates): 3rd-review — remove-line-items signature + V2LineItem…
b012a9b 
… type

BLOCKER: removeLineItemsFromCurrentCart takes a positional string[] in the SDK
(asymmetric vs add/update which take options objects). The { lineItemIds }
object double-wrapped the REST body and broke removal + failed TS build. Fixed
in commerce-ticketing (useRemoveItemFromCart), nextjs/commerce (lib/wix), and
react-native (CartScreen).

MAJOR: cartV2.LineItem is a violation/suggested-fix type; the cart line item is
cartV2.V2LineItem. Fixed the type annotations in CartBag and CartItem so the
ticketing template type-checks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
fix(templates): 4th-review — 1 BLOCKER + 2 MAJOR
e878336 
- minimal-examples/store.js: item.catalogReference (top-level) threw on any
  non-empty cart; V2 nests it at item.source.catalogReference (BLOCKER)
- commerce-ticketing CartItem: item.descriptionLines -> item.attributes
  .descriptionLines (TS error + silently non-rendering) (MAJOR)
- customCheckoutUrl placeholder {checkoutId} -> {checkout_id} in quick-buy +
  useAddItemToCart; V2 only substitutes the snake_case token (MAJOR)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
chore(commerce): loosen @wix/ecom pin so cartV2/currentCartV2 resolve
e29f00e 
astro/commerce pinned @wix/ecom exactly at 1.0.806 (pre-Cart-V2); caret it so
install resolves a version exporting currentCartV2 (matches the other templates).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
fix(commerce-ticketing): guard optional cart in CartView checkout
c7e03ae 
getCurrentCart() returns { cart?: Cart } (cart optional); CartView deref'd
cart._id unguarded -> strict-null build error. Assert cart!._id (matches lib/wix).
Caught by a type harness compiled against the real @wix/ecom types.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
docs(templates): name the entity "cart", not "checkout" (V2 unification)
6bf00c2 
- astro/commerce README: add the "one cart entity; checkout = the hosted page"
  framing note
- astro/scheduler README: "@wix/ecom checkout" -> "@wix/ecom cart" (code uses
  cartV2.createCart)
- minimal-examples README: "carts and checkouts" -> "carts and orders"
Code comments keep their V1->V2 contrast + version-specific "Cart V2" notes
(they help maintainers); identifiers untouched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
docs(commerce): add migration-guide link to the astro/commerce README…
09c1ecc 
… note

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
docs(ecom): finish Cart V2-only pass across templates
83f154d 
- Reframe comments/prose to describe Cart V2 as the only model; remove remaining Cart V1 / Checkout V1 references and V1<->V2 contrasts. One migration-guide referral in astro/commerce README where @wix/ecom is introduced.

- Comment/prose only; no runtime behavior change (all edited code files still parse).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w @claude
fix(ecom): address review nits in cart-v2 templates
c35ad5c 
- store.js: correct the subtotal comment — the cart keeps no *calculated* totals (they come from estimateCurrentCart -> summary.priceSummary); the cart's raw top-level subtotal isn't the discounted figure.

- lib/wix/index.ts getCart(): guard the empty current cart (getCurrentCart returns { cart? }) and drop the cart! non-null assertion, so an absent cart returns undefined instead of reshaping undefined.

- installed-apps.js: guard the cart.lineItems deref with optional chaining.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rommy-amitai-w
rommy-amitai-w marked this pull request as ready for review August 24, 2026 11:25
tomsa9
tomsa9 approved these changes Sep 3, 2026
View reviewed changes

@tomsa9 tomsa9 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tested, lgtm!

@rommy-amitai-w @claude
fix(ecom): address final-review findings on the Cart V2 templates
e76dda8 
- commerce-ticketing CartView: document that Cart V2 enforces the payment-acceptance gate at place-order on the hosted checkout, so the SITE_MUST_ACCEPT_PAYMENTS branch is a best-effort client fallback.

- Type cart line items as currentCartV2.V2LineItem (the module the data comes from) in CartBag/CartItem instead of the cross-module cartV2 alias.

- Correct the stale hook comments: the V2 input types (currentCartV2.CatalogItemInput, LineItemUpdate/QuantityUpdate) do exist; the structural types are a deliberate decoupling, not an unverifiable guess.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@kfirstri
kfirstri merged commit bacf0ad into wix:main Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kfirstri kfirstri kfirstri approved these changes
+1 more reviewer
@tomsa9 tomsa9 tomsa9 approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@rommy-amitai-w @kfirstri @tomsa9