🔒
Requires write_product access scope. More access scope

The Update Variant by SKU API allows users to update the details of a specific product variant using its SKU. This endpoint is useful for managing inventory, pricing, and other variant-specific attributes by targeting the unique SKU of a variant. It provides flexibility in updating multiple fields of the variant in a single API call.This API is especially useful for:

Update inventory and pricing details for a specific SKU.
Modify metadata such as barcode, weight, or custom notes for better variant management.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Example	Description
sku	string	Yes	`"ABC123"`	SKU of the product to retrieve variants.

Body Parameters

Field	Type	Required	Example	Description
`variant.compare_at_price`	float	No	`99.99`	The original price of the variant before discount.
`variant.price`	float	No	`9.99`	The current price of the variant.
`variant.barcode`	string	No	`"123456789"`	The barcode for the variant for inventory or sales tracking.
`variant.note`	string	No	`Seasonal sale`	Custom notes or remarks for the variant.
`variant.inventory_quantity`	int	No	`100`	The current inventory level for the variant.
`variant.weight`	float	No	`1.5`	The weight of the variant.
`variant.weight_unit`	string	No	`kg`	The unit of measurement for the weight. (e.g., `kg`, `g`, `lb`, `oz`)
`variant.cost_price`	float	No	`50.00`	The cost price of the variant.
`variant.retail_price`	float	No	`120.00`	The recommended retail price for the variant.
`refuse_multi_result`	bool	No	`true`	false: If sku matches multiple sub-items, update the matched sub-items normally. true: Rejects the update if the sku matches more than one subitem

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