eCommerce Integration with Wix Stores Catalog V3

When integrating products from your Wix Stores catalog into an eCommerce cart, checkout, or order, you must use the catalogReference object structure. This guide explains how to properly format and use the catalogReference object in various eCommerce API functions.

Pass the catalogReference object as part of the lineItems array in the following eCommerce API functions:

• Create Cart and Add To Cart
• Create Checkout and Add To Checkout
• Create Order

Catalog Reference Object Structure

The catalogReference object includes the following fields:

Important Notes

1. Use modifiers in either options or customTextFields based on the modifierRenderType:
   • For TEXT_CHOICES, use the modifier and choice key in options.
   • For FREE_TEXT, use the freeTextSettings.key in customTextFields.
2. You may omit customTextFields and options in catalogReference if the related modifier is not mandatory.
3. You can omit subscriptionOptionId if the product doesn't have subscriptionDetails defined or when subscriptionDetails.allowOneTimePurchases is true.
4. Always include the variantId.

Example

Consider a product with the following structure:

Note: many product fields in the above example have been omitted for conciseness.

Scenario

A buyer wants to purchase "Coffee" with the following options:

• Size: S
• Box color: Red
• Remove price tag: Yes
• Engraving: "For my best friend! :)"
• Delivery: Monthly subscription

Resulting catalogReference object

To find the correct variantId, match the options.id and options.choicesSettings.choices.choiceId of the buyer's selected options with variantsInfo.variants.optionChoiceIds.optionId and variantsInfo.variants.optionChoiceIds.optionId in the variants.

Minimal valid catalogReference object

Since both modifiers have "mandatory": false and subscriptionDetails.allowOneTimePurchases is true, the following minimal catalogReference is also valid: