Create Product With Options Catalog V3

Article: Steps for creating a Wix Store Product with Options

STEP 0: Conversation — gather what’s needed for a “ready-to-sell” product

The goal of this step is not just to create a product, but to help the user create a complete, ready-to-sell product. Before jumping to the API call in STEP 1, run a short conversation to fill the important gaps — but keep it brief.

CRITICAL — ASK AT MOST 1–2 FOLLOW-UP QUESTIONS. Never interrogate the user. Ask no more than one or two follow-up questions total before creating the product. If the user is disengaged or says “just create it”, proceed with sensible generated values rather than asking again.

0a. Opening the conversation

As soon as this skill is triggered — and the user hasn’t already described a product — YOU open the conversation. Proactively send a single opening message that invites either or both input paths and makes clear you’ll generate the full product info from whatever they provide:

What would you like to sell? Just describe your product in a few words and/or upload a photo of it — I’ll generate the full product info (name, description, price, and any options) for you from there.

The user can reply with a text prompt, an image, or both:

• An image is provided (with or without text) → follow the Create Product from Image (opens in a new tab) recipe to generate the product info from the image(s), then continue from the gap check in 0b for anything still missing.
• Text only → continue with the gap check in 0b.

If the user already described a product when triggering the skill, skip this opening message and go straight to 0b.

This opening message is the entry point, not a follow-up — it does NOT count against the 1–2 follow-up-question budget in 0b.

0b. Gap check — decide what (if anything) to ask

Mandatory inputs are name and price. Check what the user has already provided:

Case 1 — a mandatory input is missing (no name and/or no price): Ask for the missing mandatory field(s), and in the same message offer to generate it for them. Combine both missing fields into a single question. For example:

“What would you like to call this product, and what price should I set? I can also suggest a name and price for you if you’d like.”

If the user asks you to generate them (or doesn’t provide them after being asked once), generate a sensible name and price based on the product context and proceed — do not ask a second time.

Case 2 — both mandatory inputs are provided: You may ask one enrichment question to make the product more complete. Ask about whichever is most relevant, and offer to do the work for them. For example:

“Does this product come in different sizes or colors (e.g. options customers choose from)? And would you like me to generate a SEO description and/or info sections to make it ready to sell?”

• If the user wants options/choices → collect them and build the options + variants per STEP 1.
• If the user wants generated SEO description and/or info sections → generate them and include them in the product.
• If the user declines or says “just create it” → proceed with what you have.

Do NOT ask about options AND enrichment as two separate rounds. Bundle them into the single enrichment question above so the total stays within the 1–2 question budget.

0c. Stay focused on the product until it’s saved

CRITICAL — ONCE A PRODUCT-CREATION CONVERSATION HAS STARTED, STAY ON IT. Do not switch to other topics, suggest unrelated tasks, or start new workflows until the product has actually been created (saved) via STEP 1 — unless the user explicitly asks to do something else. If the user goes off-topic, briefly answer if needed, then steer back to finishing and saving the product.

0d. Confirm once — then create

CRITICAL — VALIDATE EXACTLY ONCE BEFORE CREATING. Right before calling the Create Product API (STEP 1), show a brief summary of what you’re about to create and ask for a single go-ahead. Ask only once. Do NOT approve-and-then-ask-again (e.g. present a summary, get a “yes”, and then ask “shall I create it now?” a second time) — that double confirmation is exactly what we want to avoid. Once the user approves, go straight to STEP 1 with no further approval prompts.

For example:

“Here’s what I’ll add to your store: [name] — [price][, options: …]. Ready to create it?”

If the user already signaled approval (e.g. “just create it”, “go ahead”), treat that as the single confirmation and proceed straight to STEP 1 — do not ask again.

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 (opens in a new tab) 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.

Important: The V3 Products API requires URLs for media, not media IDs. Even when using files from the Media Manager, you must use the full wixstatic.com URL.

Option 1: Using External URLs Directly

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

Warning: Some external URLs may fail if the source server blocks requests or has hotlink protection. For reliable media, use Option 2.

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:

Note: Wait for operationStatus to become READY before using the media. You can verify by calling the List Files API (GET /site-media/v1/files).

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

Why use Media Manager? External URLs can fail if the source server blocks requests. Once uploaded to Media Manager, the file is permanently stored on Wix servers and the wixstatic.com URL is always reliable.

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.

Need to Update This Product Later?

See Update Product with Options for updating existing products.

Important: All update operations (PATCH) require the current product.revision value. Always GET the product first to obtain the revision before updating.

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.