@wix/agent-skills 1.16.0 → 1.16.2

package/skills/wix-manage/references/stores/create-product-with-options-catalog-v3.md

@@ -1,623 +0,0 @@
----
-name: "Create Product with Options (Catalog V3)"
-description: Single product creation with options using Catalog V3 Products API. Covers option types (TEXT_CHOICES, SWATCH_CHOICES), choice configuration, and automatic variant generation.
----
-# 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 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/skills/create-product-from-image)** 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/create-product) **CRITICAL: USE THIS WORKING EXAMPLE**
-
-```bash
-curl -X POST 'https://www.wixapis.com/stores/v3/products' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-    "product": {
-        "name": "Air Max Runner",
-        "description": {
-            "nodes": [
-                {
-                    "type": "PARAGRAPH",
-                    "id": "desc1",
-                    "nodes": [
-                        {
-                            "type": "TEXT",
-                            "textData": {
-                                "text": "Premium running sneaker with advanced cushioning technology and breathable mesh design for ultimate comfort."
-                            }
-                        }
-                    ],
-                    "paragraphData": {
-                        "textStyle": {
-                            "textAlignment": "AUTO"
-                        }
-                    }
-                }
-            ],
-            "metadata": {
-                "version": 1,
-                "id": "sneaker-desc-001"
-            }
-        },
-        "productType": "PHYSICAL",
-        "physicalProperties": {},
-        "media": {
-            "main": {
-                "url": "https://images.unsplash.com/photo-1549298916-b41d501d3772?w=400&h=400&fit=crop&crop=center",
-                "altText": "Air Max Runner - Main Product Image"
-            },
-            "itemsInfo": {
-                "items": [
-                    {
-                        "url": "https://images.unsplash.com/photo-1549298916-b41d501d3772?w=400&h=400&fit=crop&crop=center",
-                        "altText": "Air Max Runner - Product View"
-                    }
-                ]
-            }
-        },
-        "options": [
-            {
-                "name": "Size",
-                "optionRenderType": "TEXT_CHOICES",
-                "choicesSettings": {
-                    "choices": [
-                        {
-                            "choiceType": "CHOICE_TEXT",
-                            "name": "8"
-                        },
-                        {
-                            "choiceType": "CHOICE_TEXT",
-                            "name": "9"
-                        },
-                        {
-                            "choiceType": "CHOICE_TEXT",
-                            "name": "10"
-                        }
-                    ]
-                }
-            },
-            {
-                "name": "Color",
-                "optionRenderType": "TEXT_CHOICES",
-                "choicesSettings": {
-                    "choices": [
-                        {
-                            "choiceType": "CHOICE_TEXT",
-                            "name": "Black"
-                        },
-                        {
-                            "choiceType": "CHOICE_TEXT",
-                            "name": "White"
-                        }
-                    ]
-                }
-            }
-        ],
-        "variantsInfo": {
-            "variants": [
-                {
-                    "choices": [
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Size",
-                                "choiceName": "8",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        },
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Color",
-                                "choiceName": "Black",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        }
-                    ],
-                    "price": {
-                        "actualPrice": {
-                            "amount": "129.99"
-                        }
-                    },
-                    "physicalProperties": {},
-                    "visible": true
-                },
-                {
-                    "choices": [
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Size",
-                                "choiceName": "8",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        },
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Color",
-                                "choiceName": "White",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        }
-                    ],
-                    "price": {
-                        "actualPrice": {
-                            "amount": "129.99"
-                        }
-                    },
-                    "physicalProperties": {},
-                    "visible": false
-                },
-                {
-                    "choices": [
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Size",
-                                "choiceName": "9",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        },
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Color",
-                                "choiceName": "Black",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        }
-                    ],
-                    "price": {
-                        "actualPrice": {
-                            "amount": "129.99"
-                        }
-                    },
-                    "physicalProperties": {},
-                    "visible": false
-                },
-                {
-                    "choices": [
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Size",
-                                "choiceName": "9",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        },
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Color",
-                                "choiceName": "White",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        }
-                    ],
-                    "price": {
-                        "actualPrice": {
-                            "amount": "129.99"
-                        }
-                    },
-                    "physicalProperties": {},
-                    "visible": true
-                },
-                {
-                    "choices": [
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Size",
-                                "choiceName": "10",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        },
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Color",
-                                "choiceName": "Black",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        }
-                    ],
-                    "price": {
-                        "actualPrice": {
-                            "amount": "129.99"
-                        }
-                    },
-                    "physicalProperties": {},
-                    "visible": true
-                },
-                {
-                    "choices": [
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Size",
-                                "choiceName": "10",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        },
-                        {
-                            "optionChoiceNames": {
-                                "optionName": "Color",
-                                "choiceName": "White",
-                                "renderType": "TEXT_CHOICES"
-                            }
-                        }
-                    ],
-                    "price": {
-                        "actualPrice": {
-                            "amount": "129.99"
-                        }
-                    },
-                    "physicalProperties": {},
-                    "visible": false
-                }
-            ]
-        }
-    }
-}'
-```
-
-### 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 Format**If 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:**
-
-```json
-"description": {
-    "nodes": [
-        {
-            "type": "PARAGRAPH",
-            "id": "desc1",
-            "nodes": [
-                {
-                    "type": "TEXT",
-                    "textData": {
-                        "text": "Your product description here"
-                    }
-                }
-            ],
-            "paragraphData": {
-                "textStyle": {
-                    "textAlignment": "AUTO"
-                }
-            }
-        }
-    ],
-    "metadata": {
-        "version": 1,
-        "id": "unique-desc-id"
-    }
-}
-```
-
-**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):
-
-```json
-"media": {
-    "main": {
-        "url": "https://images.unsplash.com/photo-1549298916-b41d501d3772?w=400",
-        "altText": "Product Main Image"
-    },
-    "itemsInfo": {
-        "items": [
-            {
-                "url": "https://images.unsplash.com/photo-1549298916-b41d501d3772?w=400",
-                "altText": "Product View"
-            }
-        ]
-    }
-}
-```
-
-> **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:
-
-```bash
-curl -X POST 'https://www.wixapis.com/site-media/v1/files/import' \
--H 'Content-Type: application/json' \
--H 'Authorization: <AUTH>' \
--d '{
-    "url": "https://images.unsplash.com/photo-1563729784474-d77dbb933a9e?w=400",
-    "mimeType": "image/jpeg",
-    "displayName": "Product Image"
-}'
-```
-
-Response includes the wixstatic.com URL:
-
-```json
-{
-    "file": {
-        "id": "e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
-        "url": "https://static.wixstatic.com/media/e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
-        "operationStatus": "PENDING"
-    }
-}
-```
-
-> **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:
-
-```json
-"media": {
-    "main": {
-        "url": "https://static.wixstatic.com/media/e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
-        "altText": "Product Image"
-    },
-    "itemsInfo": {
-        "items": [
-            {
-                "url": "https://static.wixstatic.com/media/e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
-                "altText": "Product Image"
-            }
-        ]
-    }
-}
-```
-
-> **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 Structure**Each 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](update-product-with-options.md) 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:**
-
-```json
-"options": [
-    {
-        "name": "Size",
-        "optionRenderType": "TEXT_CHOICES",
-        "choicesSettings": {
-            "choices": [
-                {
-                    "choiceType": "CHOICE_TEXT",
-                    "name": "Small"
-                }
-            ]
-        }
-    }
-]
-```
-
-**What NOT to do:**
-
-```json
-// WRONG - Missing choicesSettings entirely
-"options": [
-    {
-        "name": "Size",
-        "optionRenderType": "TEXT_CHOICES"
-    }
-]
-
-// WRONG - Empty choicesSettings
-"options": [
-    {
-        "name": "Size",
-        "optionRenderType": "TEXT_CHOICES",
-        "choicesSettings": {}
-    }
-]
-
-// WRONG - Empty choices array
-"options": [
-    {
-        "name": "Size",
-        "optionRenderType": "TEXT_CHOICES",
-        "choicesSettings": {
-            "choices": []
-        }
-    }
-]
-```
-
-### 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):**
-
-```json
-"options": [
-    {
-        "name": "Size",
-        "optionRenderType": "TEXT_CHOICES",
-        "optionSettings": {
-            "choicesSettings": {
-                "choices": []
-            }
-        }
-    }
-]
-```
-
-**CORRECT Structure (use this instead):**
-
-```json
-"options": [
-    {
-        "name": "Size",
-        "optionRenderType": "TEXT_CHOICES",
-        "choicesSettings": {
-            "choices": [
-                {
-                    "choiceType": "CHOICE_TEXT",
-                    "name": "Small"
-                }
-            ]
-        }
-    }
-]
-```
-
-**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.