🔒
Requires write_product access scope. More access scope

📘
Important Note: When updating the same product, the updateVariant API may encounter performance issues due to locking mechanisms. If multiple updates are needed for the same product (e.g., updating variant prices), it is strongly recommended to use the updateProduct API instead.

The Update Variant API allows users to modify the details of a specific product variant. By providing a valid variant_id in the path parameter, users can update fields such as options, pricing, inventory, and more. This endpoint is essential for managing product variants efficiently, ensuring the most accurate and updated information is reflected in the system.This API is especially useful for:

Update variant-specific attributes like size, color, or SKU.
Adjust pricing or inventory details for a particular variant.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`variant_id`	string	Yes	Unique identifier of the variant	`"var_123456789"`

Body Parameters

Parameter	Type	Required	Description	Example
`variant`	object	Yes	Variant update data	-
`variant.option1`	string	No	First option value	`"Black"`
`variant.option2`	string	No	Second option value	`"Large"`
`variant.option3`	string	No	Third option value	`""`
`variant.image_id`	string	No	Associated image ID	`"img_456789"`
`variant.image`	object	No	Variant image details	-
`variant.image.src`	string	Yes	Image URL	`"https://example.com/image.jpg"`
`variant.image.width`	int32	No	Image width	`800`
`variant.image.height`	int32	No	Image height	`600`
`variant.image.alt`	string	No	Alt text	`"Black variant"`
`variant.image.path`	string	No	Storage path	`"/images/variants"`
`variant.compare_at_price`	double	No	Original price	`199.99`
`variant.price`	double	Yes	Selling price	`149.99`
`variant.sku`	string	No	Stock keeping unit	`"SKU123-BLK-L"`
`variant.barcode`	string	No	Product barcode	`"123456789012"`
`variant.note`	string	No	Internal notes	`"New stock"`
`variant. inventory_quantity`	string	No	Stock quantity	`"50"`
`variant.weight`	double	No	Product weight	`0.75`
`variant.weight_unit`	string	No	Weight unit	`"kg"`
`variant.cost_price`	double	No	Cost price	`89.99`
`variant.whole_prices`	array of objects	No	Wholesale pricing	-
`variant.whole_prices. price`	float	No	Wholesale price	`129.99`
`variant.whole_prices. min_quantity`	string	No	Minimum order	`"10"`
`variant.retail_price`	double	No	Retail price	`149.99`
`variant.position`	string	No	Display position	`"2"`
`variant.extend`	object	No	Extended properties	-
`variant.extend.length`	double	No	Product length	`25.5`
`variant.extend.width`	double	No	Product width	`18.0`
`variant.extend.height`	double	No	Product height	`8.5`
`variant.extend. dimension_unit`	string	No	Dimension unit	`"cm"`
`variant.extend. origin_country_code`	string	No	Country of origin	`"CN"`
`variant.extend.hs_code`	string	No	HS classification code	`"8518.29.00"`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"200"`	HTTP status code
`message`	string	`"Success"`	Operation result message
`data.variant`	array of objects	-

Variant Object

Parameter	Type	Example	Description
`id`	string	`"var_987654321"`	Unique variant identifier
`product_id`	string	`"prod_123456789"`	Parent product ID
`image_id`	string	`"img_456789"`	Primary image reference
`created_at`	string	`"2025-01-15T09:00:00Z"`	Creation timestamp
`updated_at`	string	`"2025-06-15T14:30:00Z"`	Last update timestamp
`title`	string	`"Large / Black"`	Variant display title
`option1`	string	`"Black"`	First option value
`option2`	string	`"Large"`	Second option value
`option3`	string	`""`	Third option value
`image`	object	-	Variant image details
`image.src`	string	`"https://example. com/image.jpg"`	Image URL
`image.width`	int32	`800`	Image width in pixels
`image.height`	int32	`600`	Image height in pixels
`image.alt`	string	`"Black variant"`	Image alt text
`image.path`	string	`"/images/variants"`	Image storage path
`position`	string	`"1"`	Display position
`compare_at_price`	float	`199.99`	Original/comparison price
`price`	float	`149.99`	Current selling price
`sku`	string	`"SKU123-BLK-L"`	Stock keeping unit
`barcode`	string	`"123456789012"`	Product barcode
`note`	string	`"New stock"`	Internal notes
`inventory_quantity`	string	`"50"`	Current stock level
`weight`	float	`0.75`	Product weight
`weight_unit`	string	`"kg"`	Weight measurement unit
`cost_price`	float	`89.99`	Cost/production price
`whole_prices`	array of objects	-	Wholesale pricing tiers
`whole_prices.price`	float	`129.99`	Wholesale price
`whole_prices. min_quantity`	string	`"10"`	Minimum order quantity
`retail_price`	float	`149.99`	Retail price
`is_discount`	boolean	`true`	Discount status flag
`origin_price`	float	`179.99`	Original base price
`extend`	object	-	Extended properties
`extend.length`	float	`25.5`	Product length
`extend.width`	float	`18.0`	Product width
`extend.height`	float	`8.5`	Product height
`extend. dimension_unit`	string	`"cm"`	Dimension unit
`extend. origin_country_code`	string	`"CN"`	Country of origin
`extend.hs_code`	string	`"8518.29.00"`	Harmonized System code

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message