Update Product with Options (Catalog V3)

RECIPE: Business Recipe - Updating a Wix Store Product (Catalog V3)

Use this recipe to update an existing Catalog V3 product: description, media, options, variants, prices, or stock-related inventory records.

Before Any Product Update

Every Catalog V3 product update is revision-based:

• If the user gives a product name instead of a product ID, use Search Products and choose the exact product name match.
• Use Get Product to retrieve the current product and product.revision.
• Include product.id and the current product.revision in every Update Product PATCH body.
• For simple text/HTML description updates, prefer plainDescription. Use description only when sending a Rich Content object.

Find the product by name

For product-name lookup, prefer Search Products before retrieving the product by ID.

Get the current revision

Common Update Patterns

Update Description Only

For a normal user request like "set the product description to X", use plainDescription with valid HTML. The API converts it to rich content.

Do not send a plain string in description. description is a Rich Content object.

Use description only when you intentionally need to send Rich Content:

Update Options and Variants

When adding or changing options and variants, send the full option definitions and one variant for each option-choice combination. Use optionChoiceNames to reference choices.

When updating existing variants, include each existing variant id. If no GUID is passed, a variant is created with a new GUID.

Convert a Simple Product to Color Variants

When adding the first option to a simple product, do not preserve a choice-less default variant unchanged. A simple product often has one existing variant with price or stock but no choices. After you add a Color option, every variant in variantsInfo.variants must include choices that match the product options.

Use the existing default variant as source data only. For example, copy its price if the user did not ask to change price, then send a complete optioned variants list where each variant has:

After the product update returns the new variant IDs, use those IDs to set inventory.

Set Stock for New Variants

Inventory is handled separately from product updates. After the product update returns variant IDs, use Bulk Create Inventory Items with productId, variantId, and quantity.

If the store has multiple inventory locations, include locationId; otherwise the store's default location is used. After bulk inventory create, check bulkActionMetadata.totalSuccesses and results[].itemMetadata.success. Returned inventory entities are under results[].item, not a top-level inventoryItems field; confirm stock from results[].item.quantity.

Update Media Only

Update Variant Price Only

Important Notes

• To update array fields like options, modifiers, variantsInfo.variants, and any others, pass the entire existing array. Passing only the changed item overwrites the whole array.
• To update variantsInfo.variants, also pass options, and vice versa. Variants and options are mutually dependent and must stay aligned.
• When converting a simple product to an optioned product, rebuild the variants list so every variant has choices; do not keep an existing choice-less default variant unchanged.
• Always include choicesSettings with the complete list of choices when updating a product with options.
• Use optionChoiceNames rather than optionChoiceIds in variants for more reliable updates.
• Include the renderType in optionChoiceNames.

Error Message Reference