Create Product From Image

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:

• V3 flow: 6 interactive steps. Up to 3 images, multi-image variant detection, info sections (materials, care, specs), SEO meta, options/variants, atomic single-call create.
• V1 flow: 3 sequential steps. Single image, product details inferred from the image, separate media-attach call after create.

Prerequisites:

• The user MUST provide at least one product image — uploaded directly to the chat or as a publicly accessible URL.
• Up to 3 images are supported (V3 only — V1 supports only 1 image).

STEP 1: Detect Catalog Version (no user interaction)

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:

V3 Flow (catalogVersion = 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.

V3 STEP 2: Collect Images and Upload to Wix Media Manager

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:

• Accept uploaded files (any image the user sends in the chat) OR publicly accessible URLs (https://).
• Minimum: 1 image. Maximum: 3 images.
• Supported formats: JPG, PNG, WEBP.
• All images must be of the same product. If the images appear to show completely different products, 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 an image is blurry or unrecognizable, respond: “I wasn’t able to identify a product in this image. Try a clearer photo or add a description.”

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:

• The first successfully uploaded image becomes media.main.
• All images go into media.itemsInfo.items[].

V3 STEP 3: Analyze Images and Generate Product Details

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):

4a. Product Name

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".

4b. Sample Existing Product Tone (silent — no user interaction)

Before writing the description, check whether the site already has products to match their tone:

API Endpoint: POST https://www.wixapis.com/stores/v3/products/query

• If the response contains products with non-empty description fields, analyze their writing style (casual, professional, playful, luxury, technical, etc.) and note it as the site tone.
• If no products exist or descriptions are empty, use a neutral e-commerce tone.
• This query is best-effort — if it fails, proceed with neutral tone. Do NOT block the flow.

4c. Product Description

A marketing description of 2-4 sentences. Highlight key features, materials, and use case. Match the site tone detected in 4b — if the existing products use casual language, write casually; if they use formal/luxury language, match that style. If no site tone was detected, 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 7.

4d. Price with Market Range

• Suggest a retail price based on the product type and industry averages.
• Also determine an approximate market range for annotation (e.g., “avg. market: $28-$42”). This range is shown to the user in V3 STEP 5 but is NOT sent to the API.

4e. Info Sections (only if relevant)

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.

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).

4f. SEO Meta Description

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."

4g. Suggested Options (from images)

Examine the images for visible product attributes that should become variant options.

CRITICAL: Do NOT invent or infer attributes. Only suggest options that meet one of these evidence thresholds:

• Visually confirmed in the image(s) — you can see distinct values (e.g., two different colors across two images, a size label printed on packaging)
• Explicitly stated by the user in their text note (e.g., “available in blue and green”, “comes in S, M, L”)

Do NOT suggest standard industry options based on product category. For example, do NOT suggest Size: S, M, L, XL, XXL for apparel just because it is a clothing item. If no size information is visible in the image and the user did not mention sizes, report no size options detected.

Negative example: Image shows a single t-shirt with no size labels visible and the user did not mention sizes → do NOT suggest a Size option. Report: “No variant options detected from the image.”

Multi-image variant detection:

• If multiple images show the same product in different colors (e.g., one red shirt, one blue shirt), suggest a Color option with only those visible colors as choices.
• If multiple images show the same product from different angles, treat them as additional product media — NOT as separate variants.
• If only one image is provided and a distinctive color is visible, suggest that single color as a choice and ask the user if the product comes in other colors.

4h. Subscription Eligibility Detection (silent — no user interaction)

Based on the product name, description, and image analysis, determine whether this product is subscription-eligible. A product qualifies if it is a consumable that gets depleted at a predictable rate — something customers buy repeatedly on a regular schedule.

Eligible categories (examples):

• Food & beverage: coffee beans/pods, tea, protein powder, meal kits
• Supplements & health: vitamins, probiotics, protein supplements
• Pet: pet food, flea/tick treatments, cat litter
• Personal care: skincare routine products, razor blades/cartridges, deodorant, shampoo/conditioner
• Household: cleaning supplies, paper towels, toilet paper, laundry detergent
• Baby: diapers, formula, wipes
• Media: print/digital newspapers, magazines
• Candles (daily-use scented candles with high burn frequency)

NOT eligible (do not suggest):

• Furniture, art, décor (one-time purchase)
• Electronics, tools, appliances
• Standard clothing, apparel, shoes (not subscription-typical)
• Jewelry, watches
• Books (single title), games, toys
• Any unique or collectible item

Store the result internally as subscription_eligible: true/false. If true, also note a brief reason (e.g., "coffee beans — daily consumable"). No user interaction at this step.

V3 STEP 4: Present Review Card to User (INTERACTIVE)

Present ALL generated fields to the user so they can review and refine them. This is a content preview for editing — NOT the create approval. The single confirmation before creating happens later, in V3 STEP 6. Do not ask the user to approve creation at this step.

Present a structured review card using the markdown format below. This provides a visual product-card-style layout:

After the card, offer the ways they can adjust the content:

1. Refine — tell me what to change (e.g., “make the description shorter”, “the price should be lower”)
2. Regenerate — I’ll start the analysis over, optionally with additional context from you
3. Looks good — continue to the next steps (options / subscription)

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.

Apply any corrections the user requests. When they’re happy (or have no changes), continue to the next step. Do NOT treat this as the final create approval — that single confirmation comes once, at V3 STEP 6.

V3 STEP 4.5: Suggest Subscription (INTERACTIVE, conditional)

Run this step ONLY if subscription_eligible: true was set in V3 STEP 3 section 4h. Otherwise skip directly to V3 STEP 5.

Present a short, non-pushy suggestion card:

This product looks like a great candidate for a subscription plan. Customers who subscribe to [product name] get auto-refills on a schedule they choose — boosting repeat revenue for you.

Would you like to add a subscription option?

• Yes — set it up now (takes ~30 seconds)
• No — create as a one-time purchase only

If the user says No, proceed directly to V3 STEP 5.

If the user says Yes, ask the following 4 questions (can be presented together as a single form):

Q1 — Billing frequency

“How often should subscribers be charged and receive this product?”

Q2 — Duration

“How long should the subscription run?”

• Ongoing — renews automatically until the customer cancels (omit billingCycles)
• Fixed — ends after N cycles (ask: “How many cycles?”) → set billingCycles: N

Q3 — Subscriber discount (optional incentive)

“Would you like to offer a discount to customers who subscribe?”

• No discount (omit discount block)
• 10% off (Recommended) → type: "PERCENTAGE", amount: 10
• Custom percentage → ask for value → type: "PERCENTAGE", amount: [value]
• Fixed amount off → ask for value → type: "AMOUNT", amount: [value]

Q4 — Allow one-time purchase alongside subscription

“Can customers also buy this product as a one-time purchase (without subscribing)?”

• Yes — sell both ways (Recommended) → allowOneTimePurchases: true
• No — subscription only → allowOneTimePurchases: false

After collecting the user’s answers, show a brief confirmation line before moving on:

Subscription plan configured: [e.g. Monthly · Ongoing · 10% off · One-time purchases also allowed]

Store the collected subscription data for use in V3 STEP 6.

V3 STEP 5: Suggest Options and Ask User (INTERACTIVE)

Present the detected options from V3 STEP 4g 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:

• [Option Name]: [Choice 1], [Choice 2], …

Would you like to:

1. Use these options as suggested
2. Add more choices (e.g., additional colors or sizes)
3. Add entirely new options
4. Skip options and create a simple product (no variants)

If no options were detected:

I didn’t detect any variant attributes from the image(s). Would you like to add product options, 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.

V3 STEP 6: Create the Product

CRITICAL — THIS IS THE ONLY CREATE CONFIRMATION. ASK EXACTLY ONCE. The review card in V3 STEP 4 was a content preview for editing, not an approval. Here you ask for the single go-ahead before creating. Do NOT summarize-and-ask more than once — one clear confirmation is enough.

Ask the user once:

Everything is ready. Shall I create the product now?

• Yes, create it — I’ll submit the product to your store now.
• No, go back — return to a previous step to make changes.

Wait for confirmation. Only proceed with the API call if the user says Yes. If the user already said something like “just create it”, treat that as the confirmation and proceed without asking again.

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.

If a subscription was configured in V3 STEP 4.5, include a subscriptionDetails block in the product body (see rules below). Otherwise omit it entirely.

subscriptionDetails rules:

• title: auto-generate from frequency (e.g. "Monthly Subscription", "Weekly Subscription", "Quarterly Subscription")
• description: if a discount was set, write a short sentence referencing it (e.g. "Subscribe and save 10% on every order."). Omit if no discount.
• visible: always true
• frequency + interval: from user’s Q1 answer
• billingCycles: include only for fixed-duration subscriptions (from Q2). Omit for ongoing.
• discount: include only if a discount was chosen (from Q3). Omit the entire block if no discount.
• allowOneTimePurchases: from user’s Q4 answer

Example subscriptionDetails block (monthly, ongoing, 10% off, one-time also allowed):

Example with fixed duration and flat amount discount (every 2 months, 6 cycles, $5 off, subscription only):

Path A: Simple Product (No Options)

Use this if the user chose to skip options in V3 STEP 6.

Exact request example:

Path B: Product with Options

Use this if the user confirmed or provided options in V3 STEP 6. You MUST define both options and variantsInfo.variants.

Rules for variants:

• Generate ALL combinations of option choices as variants.
• Each variant uses the same price unless the user specified different prices.
• Set visible: true for all variants.

Exact request example (product with Color option detected from two images):

Expected response (partial):

On success: Present a completion card summarizing what was created:

Replace [siteId] with the site ID from the MCP context and [productId] with the product.id from the API response. This link lets the user immediately view and edit the product in the Wix dashboard.

On failure: Show an error message and offer to retry. Do NOT leave a partially created product.

V3 Completion Checklist

Before reporting success to the user, verify ALL of the following:

• Not done: STEP 1 completed: Catalog version detected as V3_CATALOG.
• Not done: V3 STEP 2 completed: User provided 1-3 images, all uploaded to Media Manager with wixstatic.com URLs.
• Not done: V3 STEP 3 completed: Images analyzed from user’s message, all product fields generated based on what’s visible in the image(s).
• Not done: V3 STEP 4 completed: User reviewed and approved the generated details.
• Not done: V3 STEP 4.5 completed (if applicable): Subscription eligibility was evaluated. If eligible, user was asked and their choice (Yes/No) was applied before proceeding to STEP 5.
• Not done: V3 STEP 5 completed: User confirmed, modified, or skipped product options.
• Not done: V3 STEP 6 completed: User confirmed “create now”, product was created via API and you received a product ID.

V1 Flow (catalogVersion = 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:

• The user MUST provide at least one product image — uploaded directly to the chat or as a publicly accessible URL.
• Both chat uploads and public URLs are accepted. Chat-uploaded images have a wixmp URL that works for Media Manager import.

V1 STEP 2: Upload the Image to Wix Media Manager (MANDATORY)

API Endpoint: POST https://www.wixapis.com/site-media/v1/files/import

Request body fields:

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 ID

If the response contains operationStatus: "FAILED": The source URL is not accessible. Ask the user for a different image URL.

V1 STEP 3: Create the Product (with image-based details)

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:

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")

V1 STEP 4: Attach the Image to the Product (MANDATORY — DO NOT SKIP)

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:

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.

V1 Completion Checklist

Before reporting success to the user, verify ALL of the following:

• Not done: STEP 1 completed: Catalog version detected as V1_CATALOG.
• Not done: V1 STEP 2 completed: Image was uploaded to Wix Media Manager and you received a wixstatic.com URL.
• Not done: V1 STEP 3 completed: You looked at the image, identified the product, and created it with accurate name/description/price.
• Not done: V1 STEP 4 completed: Image was attached to the product using the Add Product Media endpoint.

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.

Troubleshooting and Error Handling

Catalog version detection issues

Get Catalog Version returns 404 or authorization error

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.

Unsure which flow to run

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 Stores

V3 issues

Image is blurry or unrecognizable

Respond: “I wasn’t able to identify a product in this image. Try a clearer photo or add a description.”

Images show different products

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.”

User text contradicts images

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.

Description format error (V3)

V3 requires rich text nodes, NOT HTML strings. Ensure the description is an object with nodes array.

Variant count mismatch

You must generate ALL combinations of option choices. For example, 2 colors x 2 sizes = 4 variants.

V3 API write fails

Show an error and offer to retry. Do NOT leave a partially created product.

V1 issues

“The url field must be a publicly accessible URL”

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.

Product created but no image visible (V1)

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.

Cross-version errors

Image import fails (operationStatus: FAILED)

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.

428 Precondition Required on product creation

You called the wrong endpoint for the site’s catalog version. Re-run STEP 1 to detect the version and use the matching flow:

• V3 sites must use POST /stores/v3/products (V3 STEP 6)
• V1 sites must use POST /stores/v1/products (V1 STEP 4)

References

• Get Catalog Version (opens in a new tab)
• Catalog Versioning Overview (opens in a new tab)
• Create Product (Catalog V3) (opens in a new tab)
• Create Product with Options (Catalog V3) (opens in a new tab)
• Info Sections API (Catalog V3) (opens in a new tab)
• Create Product (Catalog V1) (opens in a new tab)
• Add Product Media (Catalog V1) (opens in a new tab)
• Upload Media to Wix (opens in a new tab)
• Install Wix Apps (opens in a new tab)