Create product variation

Get variation of a specific product.

You can create a new product variation using this method. If the options you specify in request don't exist, they will be created automatically with the type of dropdown. If you want to create options explicitly, use the Update product call to create them.


You can create only one variation per API request. To create several variations, send several separate requests for each.


AuthorizationstringoAuth token with mandatory Bearer before it. Example: Bearer e***s0, where e***s0 should be replaced with your oAuth token.

Request body

A JSON object of type 'Variation' with the following fields:


optionsArray<OptionValue>Set of options that identifies this variation. An array of name-value pairs
skustringVariation SKU. Omitted if the variation inherits the base product's SKU
quantitynumberAmount of the variation items in stock
unlimitedbooleantrue if the variation has unlimited stock (that is, never runs out)
pricenumberVariation price. Omitted if the variation inherits the base product's price
isShippingRequiredbooleantrue if variation requires shipping, false otherwise
wholesalePricesArray<WholesalePrice>Sorted array of the variation's wholesale price tiers (quantity limit and price). Omitted if the variation inherits the base product's tiered price settings
costPricenumberPurchase price (the price at which the seller bought the product from the supplier). A positive number, 0 by default. The field is not shown in the UI and can be used for reports and profit calculations
weightnumberVariation weight in the units defined in store settings. Omitted if the variation inherits the base product's weight.
warningLimitnumberThe minimum 'warning' amount of the product items in stock for this variation, if set. When the variation in stock amount reaches this level, the store administrator gets an email notification. Omitted if the variation inherits the base product's settings
attributesArray<AttributeValue>Variation's UPC attribute and its value
compareToPricenumberVariation's sale price displayed strike-out in the customer frontend Omitted if empty
externalReferenceIdstringExternal ID for products synced from external services (e.g. POS)
minPurchaseQuantitynumberSets minimum product variation purchase quantity. Default value is taken from a base product.
maxPurchaseQuantitynumberSets maximum product variation purchase quantity. Default value is taken from a base product.
lowestPricenumberThe lowest price for the last 30 days before discount.
defaultDisplayedLowestPricenumberlowestPrice with tax
defaultDisplayedLowestPriceFormattedstringFormatted display of defaultDisplayedLowestPrice in the store's formatting for prices
outOfStockVisibilityBehaviourstringIndicates whether an out of stock product should visible or not. One of: SHOW, HIDE, ALLOW_PREORDER.


namestringOption name
nameTranslated<Translations>Available translations for product option name
valuestringOption value
valueTranslated<Translations>Available translations for product option value


<ISO_LANG_CODE>stringTranslations for each available language. If no other translations are provided, the default language translation is returned. See available languages in store language settings


quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier


idnumberUnique attribute ID. See Product Classes for the information on attribute IDs.
namestringCan be used to specify the attribute. It's case-insensitive. If id or alias fields are sent, the field will be ignored.
nameTranslated<Translations>Available translations for product attribute name
aliasstringOne of UPC, BRAND, PRICE_PER_UNIT, UNITS_IN_PRODUCT. This can be used instead of id or name to quickly set the basic variation attributes without numeric id.
valuestringAttribute value
valueTranslated<Translations>Available translations for product attribute value
showstringDefines if an attribute is visible on a product page. Supported values: NOTSHOW, DESCR, PRICE. The value PRICE = DESCR.


A JSON object of type 'CreateStatus' with the following fields:


idnumberID of the created variation


In case of error, Ecwid responds with an error HTTP status code

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The "Product Variations" feature are not available on the merchant plan
404The product is not found
409The specified sku or options variation already exists
415Unsupported content-type: expected application/json or text/json
500Cannot get the variation because of an error on the server