🔒
Requires write_product access scope. More access scope

The Create Variant API allows users to add a new product variant to an existing product by specifying details such as options, pricing, inventory, and wholesale information. This operation is used to expand a product’s available options by creating additional variants with unique attributes.This API is especially useful for:

1.Adding new variants to existing products with different options like size, color, or style.

2.Managing inventory and pricing for individual product variants.

3.Customizing product variants for wholesale or retail purposes.

Request Parameters

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Body Parameters

Parameter	Type	Required	Description	Example
`variant`	object	Yes	Variant configuration	-
`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_987654"`
`variant. compare_at_price`	float	No	Original/compare price	`199.99`
`variant.price`	float	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	`"Limited edition"`
`variant.inventory_quantity`	string	No	Initial stock quantity	`"100"`
`variant.weight`	float	No	Product weight	`0.75`
`variant.weight_unit`	string	No	Weight measurement unit	`"kg"`
`variant.cost_price`	float	No	Cost price	`89.99`
`variant.wholesale_price`	array of objects	No	Wholesale pricing tiers	-
`variant.wholesale_price. price`	float	Yes	Wholesale price	`129.99`
`variant.wholesale_price. min_quantity`	string	Yes	Minimum order quantity	`"10"`
`variant.retail_price`	float	No	Retail price	`149.99`
`variant.position`	string	Yes	Display position	`"2"`
`variant.extend`	object	No	Extended properties	-
`variant.extend.length`	float	No	Product length	`25.5`
`variant.extend.width`	float	No	Product width	`18.0`
`variant.extend.height`	float	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`	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