ALWAYS use this recipe as the entry point when the user wants to create a product from one or more images. Do NOT skip STEP 1 (version detection) — even if you believe you know the catalog version from dynamic context.
CRITICAL — IMAGE DESCRIPTION FIRST: In your VERY FIRST response after seeing a product image, you MUST write a detailed text description of what you see in the image (product type, colors, materials, shape, branding). Output this description as text alongside your first tool call. This description will persist in conversation context and is the ONLY source of truth for product details in later steps. Do NOT attempt to re-analyze the image later — use the description you wrote here.
This recipe creates a Wix Store product from an image. It first detects the site's catalog version, then runs the appropriate flow:
Prerequisites:
API Endpoint: GET https://www.wixapis.com/stores/v3/provision/version
No request body — this is a GET request.
Expected response:
Possible values for catalogVersion:
| Value | Action |
|---|---|
V3_CATALOG | Run the V3 Flow below (V3 STEP 2 through V3 STEP 6) |
V1_CATALOG | Run the V1 Flow below (V1 STEP 2 through V1 STEP 4) |
STORES_NOT_INSTALLED | Stop. Inform the user: "The Wix Stores app is not installed on this site. Please install Wix Stores first before creating products. You can install it using the Install Wix Apps recipe." |
V3_CATALOG)Run this section ONLY if STEP 1 returned V3_CATALOG. Otherwise jump to the V1 Flow further below.
This is an interactive 5-step flow (STEP 2 through STEP 6). V3 STEP 4 and V3 STEP 5 require user interaction — do NOT skip them.
Ask the user to provide 1 to 3 images of their product:
Upload 1-3 images of your product. If your product comes in different colors or sizes, feel free to upload images of those variants — I'll use them to set up product options automatically.
You can upload images directly or provide public URLs.
Rules:
https://).Optional free-text: The user may include a text note with context (e.g., "handmade ceramic mug, usually around $25, available in blue and green"). Use this to supplement the image analysis.
Immediately upload each image to the Wix Media Manager to get permanent public URLs:
API Endpoint: POST https://www.wixapis.com/site-media/v1/files/import
For each image, send:
Expected response:
After uploading, save the file.url (wixstatic.com URL) for each image. You need these in V3 STEP 3 and V3 STEP 6.
Fallback: If the upload fails (e.g., the source URL is not publicly accessible, or operationStatus: "FAILED"), ask the user: "I couldn't upload that image. Could you provide a publicly accessible URL for it (e.g., from Unsplash, Imgur, or any https:// link)?"
Media assignment:
media.main.media.itemsInfo.items[].Use the image description you wrote at the start of this conversation (in your first response, per the CRITICAL instruction at the top of this recipe). That description is the source of truth for all product fields. Do NOT attempt to re-analyze the image — use the text description already in context.
Use ONLY details from your earlier image description to generate the fields below. Do NOT use generic names like "Product" or hallucinate new details. If you did not write an image description earlier, ask the user for clarification instead of guessing.
Generate the following fields based on what you see in the image(s) (and any free-text note from the user):
A concise, appealing product name optimized for e-commerce discoverability. Maximum 80 characters. Follow the naming convention: [Brand/Style] [Material] [Product Type].
Example: "Artisan Stoneware Ceramic Mug" — not generic names like "Mug" or "Product".
A marketing description of 2-4 sentences. Highlight key features, materials, and use case. Adapt tone to the product type (artisanal for handmade, technical for electronics, warm for home goods). This will be formatted as rich text nodes in V3 STEP 6.
Based on the product type and what's visible in the image, generate category-specific info sections. Only include sections that are relevant — omit entirely if not applicable.
| Product Category | Possible Info Sections |
|---|---|
| Clothing/Textiles | "Materials & Composition" (e.g., "100% Organic Cotton"), "Care Instructions" (e.g., "Machine wash cold, tumble dry low") |
| Candles/Fragrance | "Burn Time & Care" (e.g., "Approx. 45 hours burn time. Trim wick to 1/4 inch before each use.") |
| Furniture/Home | "Dimensions & Specs" (e.g., "Height: 30cm, Width: 15cm"), "Assembly" if applicable |
| Electronics | "Technical Specifications", "What's Included" |
| Food/Beverages | "Ingredients", "Nutritional Info", "Storage Instructions" |
| Jewelry | "Materials" (e.g., "Sterling Silver 925"), "Sizing Guide" |
| Skincare/Beauty | "Ingredients", "How to Use" |
Each info section needs: a uniqueName (lowercase-hyphenated, e.g., "care-instructions"), a title (display name, e.g., "Care Instructions"), and a description (2-3 sentences).
A short meta description (120-160 characters) optimized for search. Include the product type, key materials, and primary use case.
Example: "Handcrafted stoneware ceramic mug with a matte glaze finish. Perfect for coffee and tea lovers. Microwave and dishwasher safe."
Examine the images for visible product attributes that should become variant options.
CRITICAL: Do NOT invent attributes. Only suggest options that are:
Multi-image variant detection:
Common options to detect:
You MUST present ALL generated fields to the user and ask for confirmation before proceeding.
Present a structured review card:
Here's what I've generated from your image(s):
Name: [generated name]
Description: [generated description text]
Price: $[price] (avg. market: $[low]-$[high])
Info Sections:
SEO Description: [meta description]
Would you like to:
If the user provided a text note that contradicts what's visible in the image (e.g., image shows blue but note says "available in red"), ask the user to clarify before proceeding.
Wait for user confirmation. Apply any corrections they request. Do NOT proceed until approved.
Present the detected options from V3 STEP 3f and ask the user if they want to add product options.
If options were detected:
Based on your image(s), I suggest the following product options:
Would you like to:
If no options were detected:
I didn't detect any variant attributes from the image(s). Would you like to add product options (such as Size or Color), or should I create a simple product without variants?
Wait for user response. Collect the final list of options and choices based on their answer.
API Endpoint: POST https://www.wixapis.com/stores/v3/products
Build the request body with all confirmed fields. The write must be atomic — either all fields save or none do.
Use this if the user chose to skip options in V3 STEP 6.
Exact request example:
Use this if the user confirmed or provided options in V3 STEP 6. You MUST define both options and variantsInfo.variants.
Rules for variants:
visible: true for all variants.Exact request example (product with Color option detected from two images):
Expected response (partial):
On success: Report to the user the product name, price, options (if any), info sections added, and confirm the product was created with images attached.
On failure: Show an error message and offer to retry. Do NOT leave a partially created product.
Before reporting success to the user, verify ALL of the following:
V3_CATALOG.V1_CATALOG)Run this section ONLY if STEP 1 returned V1_CATALOG. Otherwise use the V3 Flow above.
This is a 3-step sequential flow (STEP 2 through STEP 4). ALL steps MUST be completed in order. Do NOT report success until ALL steps have executed successfully.
V1 prerequisites:
API Endpoint: POST https://www.wixapis.com/site-media/v1/files/import
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | The image URL. Can be a publicly accessible HTTP/HTTPS URL OR a wixmp URL from a chat-uploaded image. Both work with the Media Manager import API. |
mimeType | string | Recommended | The MIME type of the image. Use image/jpeg for .jpg/.jpeg files, image/png for .png files, image/webp for .webp files. |
displayName | string | No | A display name for the file in Media Manager. Include the file extension (e.g., product-image.jpg). |
Exact request example:
Expected response:
After this step, save these values — you need them later:
file.url — the wixstatic.com URL (use in V1 STEP 4)file.id — the media file IDIf the response contains operationStatus: "FAILED": The source URL is not accessible. Ask the user for a different image URL.
API Endpoint: POST https://www.wixapis.com/stores/v1/products
Use the image description you wrote at the start of this conversation (in your first response, per the CRITICAL instruction at the top of this recipe). That description is the source of truth for the product name, description, and price. Do NOT attempt to re-analyze the image — use the text description already in context.
Use ONLY details from your earlier image description to set the product name, description, and price below. Do NOT use generic text like "Product from image" or hallucinate new details. If you did not write an image description earlier, ask the user for clarification instead of guessing.
Request body fields:
| Field | Type | Required | Value |
|---|---|---|---|
product.name | string | Yes | A concise, appealing name describing the ACTUAL product in the image (max 80 chars). Example: "Premium Spinning Fishing Reel" — NOT "Product from image". |
product.description | string | Yes | A 2-3 sentence marketing description of what you SEE in the image. MUST be wrapped in <p> tags. |
product.visible | boolean | Yes | true |
product.productType | string | Yes | "physical" |
product.priceData.price | number | Yes | A reasonable retail price based on the product type visible in the image |
Exact request example (using values from V1 STEP 3):
Expected response (partial):
After this step, save this value — you need it in V1 STEP 4:
product.id — the product ID (a UUID string like "a1b2c3d4-e5f6-7890-abcd-ef1234567890")API Endpoint: POST https://www.wixapis.com/stores/v1/products/{id}/media
Replace {id} in the URL with the product.id from V1 STEP 4.
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
media | array | Yes | Array of media objects to attach |
media[].url | string | Yes | The file.url (wixstatic.com URL) from V1 STEP 2. Do NOT use the original image URL — use the wixstatic.com URL returned by the Media Manager. |
Exact request example:
URL: POST https://www.wixapis.com/stores/v1/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890/media
Expected response: Empty object {} — this means success.
This step is MANDATORY. The product is not complete without its image. Do NOT report success to the user before this step returns successfully.
Before reporting success to the user, verify ALL of the following:
V1_CATALOG.Only after ALL 4 steps succeed (STEP 1 + V1 STEP 2-4), report to the user: the product name, price, and that it was created with the image attached.
The API key may not have permission to access Stores APIs, or Stores may not be installed. Verify Stores is installed and the auth token has the correct scopes.
The response field is catalogVersion. Map it as follows:
V3_CATALOG -> run V3 Flow (V3 STEP 2 onward)V1_CATALOG -> run V1 Flow (V1 STEP 2 onward)STORES_NOT_INSTALLED -> stop and ask user to install Wix StoresRespond: "I wasn't able to identify a product in this image. Try a clearer photo or add a description."
Respond: "It looks like these images show different products. For now, I can create one product at a time. Please upload images of a single product."
If the user's free-text note conflicts with what's visible (e.g., image shows blue but note says "available in red"), ask the user to clarify before showing the review card.
V3 requires rich text nodes, NOT HTML strings. Ensure the description is an object with nodes array.
You must generate ALL combinations of option choices. For example, 2 colors x 2 sizes = 4 variants.
Show an error and offer to retry. Do NOT leave a partially created product.
The URL may be a local file path or invalid reference. Both public HTTPS URLs and wixmp URLs from chat uploads work. If the error persists, ask the user for a different image source.
You used the original external URL instead of the wixstatic.com URL in V1 STEP 4. Always use the file.url from V1 STEP 2's response.
The source server blocks external requests. Ask the user for a different image URL. Reliable sources: Unsplash (images.unsplash.com), Pexels (images.pexels.com), Imgur, public S3/GCS buckets.
You called the wrong endpoint for the site's catalog version. Re-run STEP 1 to detect the version and use the matching flow:
POST /stores/v3/products (V3 STEP 6)POST /stores/v1/products (V1 STEP 4)