RECIPE: Business Recipe - Creating a Wix Store Product with options (Catalog V3)

Learn how to create a Wix store product with customizable options like colors, sizes, or other variants, allowing customers to select their preferences when purchasing.

Article: Steps for creating a Wix Store Product with Options

STEP 1: create the product with options and variants

1. create the product with options and create variants for them - Wix REST API: Create Product CRITICAL: USE THIS WORKING EXAMPLE

IMPORTANT NOTES:

When Creating a product YOU MUST leave the physicalProperties and all other non required fields empty. for example: "physicalProperties": {}. In most cases the product will be a physical product, and therefore MUST have the empty physicalProperties object ("physicalProperties": {}) and a corresponding "productType": "PHYSICAL".

CRITICAL: variantsInfo is Always Required variantsInfo.variants must contain at least one variant, even for simple products without options. Omitting it causes: "variantsInfo must not be empty".

CRITICAL: Description FormatIf you include a description, it MUST use Wix's rich text nodes structure, NOT a plain string. Plain strings will cause "Expected an object" API errors.

WRONG: "description": "Your text here" CORRECT:

CRITICAL: Media Format To add product images, use the media object with main for the primary image and itemsInfo.items for additional gallery images. YOU MUST add an image to each product.

Option 1: Using External URLs Directly

You can reference images directly from external URLs that allow hotlinking (e.g., Unsplash, Pexels):

Option 2: Using Media Manager (Recommended)

For reliable, permanent media storage, first upload the image to the site's Media Manager, then use the returned wixstatic.com URL.

Step 1: Upload the image to Media Manager using the Import File API:

Response includes the wixstatic.com URL:

Step 2: Use the wixstatic.com URL (not the ID) when creating the product:

CRITICAL: Options StructureEach option MUST include:

• optionRenderType: "TEXT_CHOICES" for text-based choices
• choicesSettings: Object containing the choices array
• choicesSettings.choices: Array with at least one choice
• Each choice MUST have choiceType: "CHOICE_TEXT" and name properties

CRITICAL: Variants Structure

• Create one variant for EVERY combination of option choices (Cartesian product of all options)
• In this example: 2 colors and 3 sizes creates 6 variants (2 x 3) - all combinations must be included
• Each variant must reference ALL options defined on the product
• Use optionChoiceNames structure with optionName, choiceName, and renderType
• Price must use price.actualPrice.amount with string values
• Use visible: true for variants you want customers to see and purchase
• Use visible: false for variants that exist but should be hidden from customers

The Create Product API can handle creating customizations and choices in a single call. There's no need to separately check for existing customizations, create new ones, or add choices to them—the API handles all of this automatically:

1. If you provide an option with a name that doesn't exist as a customization, a new customization will be created
2. If a customization with that name already exists, it will be associated with the product
3. New choices will be added to the customization if they don't exist
4. When creating variants, use optionChoiceNames rather than optionChoiceIds to reference the options and choices
5. Always include the choicesSettings object with the complete list of choices
6. You must create one variant for each combination of option choices

Next Steps:

After Creating the product, verify that the options appear correctly in the store and that customers can select different variants.

Troubleshooting Common Issues

Issue 1: "ChoicesSettings must not be empty" error

• Problem: When creating a product with options, you get an error saying choicesSettings must not be empty. This can appear in several forms:
  • "product is invalid: options [at index 0] is invalid: value choicesSettings must not be empty"
  • "product is invalid: options [at index 0] is invalid: value choicesSettings must not be empty" with "violatedRule":"REQUIRED_ONE_OF_FIELD"
  • "choicesSettings must not be empty" with field violations showing "supported":["choicesSettings"]
• Solution: Always include the choicesSettings object with the full array of choices when creating a product with options. Every option MUST have a complete choicesSettings structure with at least one choice, even when using an existing customization.

Common Causes:

1. Missing choicesSettings entirely - The option object doesn't include any choicesSettings
2. Empty choicesSettings object - The choicesSettings exists but has no choices array or empty choices array
3. Null or undefined choicesSettings - The choicesSettings field is present but set to null/undefined

Example of correct choicesSettings structure:

What NOT to do:

Issue 2: "optionSettings.choicesSettings.choices must not be empty" error

• Problem: You get an error like "product is invalid: options [at index 0] is invalid: optionSettings.choicesSettings is invalid: choices has size 0, expected 1 or more" or "choices must not be empty".
• Solution: This error occurs when using the incorrect nested structure optionSettings.choicesSettings instead of the correct choicesSettings directly under the option.

WRONG Structure (causes the error):

CORRECT Structure (use this instead):

Key Points:

• Use choicesSettings directly under the option object, NOT nested under optionSettings
• The choicesSettings.choices array MUST contain at least one choice
• Each choice MUST have choiceType and name properties
• Always include the complete choices array even when referencing existing customizations

Issue 3: Variants not matching options

• Problem: The API returns errors about variants not matching the product's options.
• Solution:
• Create one variant for each possible combination of option choices
• Ensure each variant references all options defined on the product
• If the product has only one option with three choices, you need three variants
• Make sure each variant's option choice name exactly matches the corresponding option choice

Issue 4: Conflicts when using existing customizations

• Problem: When attempting to use existing customizations, you encounter name conflicts or choice conflicts.
• Solution:
• If you need to use a specific existing customization ID, first query customizations to get the correct ID
• When working with existing customizations, ensure all choices you reference actually exist in that customization
• If you're creating a new customization with the same name as an existing one, the API will use the existing one
• Be aware that customizations are shared across all products in your store

Issue 5: "Expected an object" error for description

• Problem: Using a plain string for the description field causes API failure.
• Solution: Always use the rich text nodes structure for descriptions as shown in the CRITICAL section above.

Issue 6: Inconsistencies in documentation vs. actual API behavior

• Problem: Several API requirements are not well-documented or are documented differently from how the API actually behaves.
• Solution:
• Always include choicesSettings with all choices when creating a product
• Use optionChoiceNames rather than optionChoiceIds in variants for more reliable results
• Include the renderType in optionChoiceNames
• Use the exact same choice names as defined in the customization

Conclusion

Creating a Wix store product with options involves understanding the relationship between store-wide customizations and product-specific options and variants. The key is to ensure consistency between customization definitions, product options, and product variants.

By following this recipe and being aware of the common pitfalls, you can successfully create a Wix store product with options.