RECIPE: Add Product to Cart

STEP 1: Get a visitor token

If you do not already have a visitor token in the conversation context, call the GenerateVisitorToken tool to mint one. Reuse the same token for every step of this flow — re-running add-to-cart with the same token merges items into the same cart, it does not create a new cart.

STEP 2: Resolve the product (and variant) IDs

You need the product GUID (catalogItemId). If you do not have it, use the matching Query Products recipe based on the site's catalog version (reported in <site-context> as Stores catalog version):

• V1_CATALOG → use the "Query Products (Catalog V1)" recipe.
• V3_CATALOG → use the V3 query-products endpoint at POST /stores/v3/products/query.

For a specific variant, also resolve the variant GUID from product.variants[].id (or its V3 equivalent).

STEP 3: Add the line item to the current cart

POST https://www.wixapis.com/ecom/v1/carts/current/add-to-cart

Simple add (product only, no variant):

STEP 4: Adding a specific variant

Supply the variant GUID via catalogReference.options.variantId — keep catalogItemId as the product GUID:

STEP 5: Use the response

The response is { cart: { id, checkoutId, lineItems, ... } }. Save cart.id and cart.checkoutId — follow-up calls (update quantity, remove items, create checkout) need them.

Important Notes

• The endpoint lives under /ecom/v1, not /stores/v1 or /stores/v3, even when the items are Stores products. Adding to cart is an eCom operation.
• catalogReference.appId is the catalog provider's app ID, not the site or app GUID. For Wix catalogs the constants are:
  • Wix Stores: 215238eb-22a5-4c36-9e7b-e7c08025e04e
  • Wix Bookings: 13d21c63-b5ec-5912-8397-c3a5ddb27a97
  • Wix Restaurants: 9a5d83fd-8570-482e-81ab-cfa88942ee60
• catalogItemId is the product GUID — never the variant GUID. Variants go in catalogReference.options.variantId.
• This endpoint requires visitor or member authentication. Calling it with an account or admin token will fail — always route through GenerateVisitorToken + CallWixSiteAPI.
• The same endpoint works for both Catalog V1 and V3 sites. Only the shape of optional options differs; the basic "add product, quantity N" call is identical.

References

• Add To Current Cart
• eCom Cart introduction
• Catalog & eCommerce integration (V3)
• Catalog & eCommerce integration (V1)