Important:
The Cart V1 and Checkout V1 APIs will be removed on February 1, 2027. Until then they continue to work, so you can migrate incrementally. We recommend Cart V2 for new development.
Cart V2 is a unified API that replaces both the Cart V1 and Checkout V1 APIs. It combines the cart and checkout models into a single Cart entity that covers the entire purchase flow, from adding items to placing an order.
There is no separate checkout entity. The Cart V2 object holds all the information that was previously split between the cart and the checkout, including billing, delivery, gift cards, and payment configuration.
This guide helps you migrate your app or integration from the Cart V1 and Checkout V1 APIs to the Cart V2 API.
For a detailed field, method, and event mapping, see Migration Mapping.
Cart V1 and Checkout V1 are 2 separate entities that together represent the purchase flow. Cart V2 merges them into a single Cart entity that manages the full lifecycle, from adding items through placing an order.
The V1 flow requires creating a checkout from a cart, then creating an order from the checkout. In V2, call Place Order directly on the cart.
In Checkout V1, fields like priceSummary, taxSummary, payNow, and payLater are stored on the checkout object. In Cart V2, these aren't stored on the cart. Call Calculate Cart or Estimate Cart to get a CartSummary containing these values.
In V1, you add coupons and gift cards by passing a code string in create and update requests. In V2, use the dedicated Add Coupon, Add Gift Card, and Set Delivery Method methods.
Flat line item fields from V1 are now organized into focused sub-objects in V2: source, pricing, attributes, paymentConfig, deliveryConfig, and taxConfig.
Root-level fields like currency, buyerLanguage, and businessLocationId are now organized under businessInfo and customerInfo.
In Cart V1, creating a cart always created the current cart and unmarked the previously current cart. In Cart V2:
Checkout V1 handles invalid states implicitly:
In Cart V2, these API calls fail with explicit errors. Your app must handle them and decide how to continue, for example, by showing out-of-stock messages, refreshing catalog data, or blocking checkout. The API is now predictable and transparent, but requires explicit error handling in your app.
Replace each V1 call with its Cart V2 equivalent. The Migration Mapping article lists every method and field. The examples below cover the most common migrations.
In Cart V1, you call Add To Current Cart with lineItems. In Cart V2, call Add Line Items To Current Cart with catalogItems:
Key differences:
lineItems → catalogItemsLineItem → CatalogItemInputIf you used Create Checkout from Checkout V1 to start a "buy now" flow, call Create Cart instead.
Before (Checkout V1 Create Checkout request):
After (Cart V2 Create Cart request):
Key differences:
checkoutInfo → cartbuyerNote → notechannelType (top-level) → cart.source.channelTypelineItems → catalogItemsCall Get Cart with the cart ID. In Cart V2, the checkout ID from Checkout V1 is the cart ID. There is no separate entity.
To get calculated totals, which Get Checkout previously returned on the checkout object, call Calculate Cart.
Call Update Cart. Field paths have changed, so update your requests to use the new paths:
buyerNote → notecontactInfo.contactDetails (Cart V1) → customerInfocontactInfo.address (Cart V1) → deliveryInfo.addressbillingInfo.address (Checkout V1) → paymentInfo.billingAddressshippingInfo.shippingDestination.address (Checkout V1) → deliveryInfo.addressFor the complete list, see the entity field mapping.
Call Place Order on the cart. It replaces Create Order from Checkout V1. The request field id (checkout ID) is now cartId.
As in Checkout V1, Place Order creates the order but doesn't collect payment. When money needs to be charged, the response includes paymentGatewayOrderId, the same payment gateway order ID that Create Order returned. Collect payment with it the same way as in V1, by passing it as the paymentId parameter to the Wix Pay startPayment() function.
paymentGatewayOrderId is omitted when there is nothing to charge, for example, when the cart total is 0, the order is fully discounted, or a gift card covers the total.
startPayment() runs in Velo on a Wix site. If your app can't run Velo code, such as a headless storefront or an external backend, direct payment collection isn't supported yet. Instead, send the customer to the Wix-hosted checkout page with Get Checkout URL.
No. You can migrate incrementally. The V1 APIs continue to work until they're removed on February 1, 2027. Prioritize your high-traffic flows first.
Cart V2 emits its own events: CartCreated, CartUpdated, and CartDeleted, plus a CartCalculated event emitted after Calculate Cart and Estimate Cart. If you're subscribed to Cart V1 or Checkout V1 events, subscribe to the Cart V2 events instead.
Call Calculate Cart to get totals such as priceSummary, taxSummary, and deliverySummary. The response also contains the cart itself.
refresh parameter on Get Checkout?Use Refresh Cart in Cart V2, which re-evaluates prices, inventory, and discounts.
Last updated: 5 August 2026