Create product variation

POST https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}

If specified options do not yet exist, they will be created automatically as a dropdown list (SELECT option type).

Required access scopes

Your app must have the following access scopes to make this request: create_catalog

Path params

All path params are required.

Param	Type	Description
storeId	number	Ecwid store ID.
productId	number	Internal product ID.

Headers

The Authorization header is required.

Header	Format	Description
Authorization	Bearer secret_ab***cd	Access token of the application.

Request JSON

A JSON object with the following fields:

Field	Type	Description
options	array of objects options	Set of selected product option values that identify this variation.
sku	string	Variation SKU. If empty, variation inherits the base product's SKU.
thumbnailUrl	string	Link to the variation image resized to fit 400x400px container.
imageUrl	string	Link to the variation image resized to fit 1200x1200px container.
smallThumbnailUrl	string	Link to the variation image resized to fit 160x160px container.
hdThumbnailUrl	string	Link to the variation image resized to fit 800x800px container.
originalImageUrl	string	Link to the full-sized variation image.
instock	boolean	Defines if the variation is in stock (quantity is more than 0).
quantity	number	Number of variation items in stock. If the variation has unlimited stock (unlimited is true), this field is not returned.
unlimited	boolean	Defines if the variation has unlimited stock.
price	number	Base variation price without any modifiers.
defaultDisplayedPrice	number	Variation price as it's shown on the storefront for logged out customers with default location (store location). Pre-selected product options or variations modify the price. Includes taxes
defaultDisplayedPriceFormatted	string	Formatted variant (curency symbol and delimeter settings) of defaultDisplayedPrice based on the store's format settings. For example, €11,00
lowestPrice	number	Variation's lowest price for EU store.
lowestPriceSettings	object lowestPriceSettings	Variation's lowest price settings contain only one field: lowestPriceEnabled It defines if the lowest price is enabled for the variation.
defaultDisplayedLowestPrice	number	Variation lowest price as it's shown on the storefront for logged out customers with default location (store location). Includes taxes
defaultDisplayedLowestPriceFormatted	string	Formatted variant (curency symbol and delimeter settings) of defaultDisplayedLowestPrice based on the store's format settings. For example, €11,00
dimensions	object dimensions	Variation's dimensions.
wholesalePrices	array of objects wholesalePrices	Sorted list of wholesale price tiers specific to the variation: "minimum quantity = price" pairs.
weight	number	Variation's weight for calculating shipping costs.
volume	number	Variation volume for calculations shipping costs, fractional number, 0 by default.
warningLimit	number	Minimum amount of variation in stock to trigger an automated "low stock" email notification for the store owner.
attributes	array of objects attributes	List of variation attributes and their values.
compareToPrice	number	Pre-sale price for the variation.
minPurchaseQuantity	number	Sets minimum product purchase quantity. Default value is null.
maxPurchaseQuantity	number	Sets maximum product purchase quantity. Default value is null.
outOfStockVisibilityBehaviour	boolean	Defines if a variation is visible and/or can be pre-ordered when out-of-stock. Requires enabled pre-orders on the store level: allowPreordersForOutOfStockProducts setting in /profile endpoint. Supported values: SHOW - Show out-of-stock variation, but adding it to the cart is disabled. ALLOW_PREORDER - Show out-of-stock variation and allow adding it to the cart.
alt	object alt	Image description for the "alt" HTML attribute and its translations.

options

Field	Type	Description
name	string	Name of the selected option.
nameTranslated	object translations	Available translations for the product option name.
value	string	Value of the selected option.
valueTranslated	object translations	Available translations for the product option value.

dimensions

Field	Type	Description
length	number	Length of a product for calculating shipping costs.
width	number	Width of a product for calculating shipping costs.
height	number	Height of a product for calculating shipping costs.

lowestPriceSettings

Field	Type	Description
lowestPriceEnabled	boolean	Defines if the lowest price is enabled for the product and shown on the storefront.
manualLowestPrice	number	Manually entered lowest price for the last 30 days before any discounts or taxes applied.
defaultDisplayedManualLowestPrice	number	manualLowestPrice with taxes applied.
defaultDisplayedManualLowestPriceFormatted	string	Formatted display of defaultDisplayedManualLowestPrice using store format settings.
automaticLowestPrice	number	Automatically calculated lowest price for the last 30 days before any discounts or taxes applied. Read-only
defaultDisplayedAutomaticLowestPrice	number	automaticLowestPrice with taxes applied. Read-only
defaultDisplayedAutomaticLowestPriceFormatted	string	Formatted display of defaultDisplayedAutomaticLowestPrice using store format settings. Read-only

attributes

Field	Type	Description
id	number	Internal attribute ID.
name	string	Attribute name visible on the storefront.
nameTranslated	object translations	Available translations for the attribute name.
value	string	Value of the attribute for this product.
valueTranslated	object translations	Available translations for the attribute value.
type	string	Attribute type. There are user-defined attributes, general attributes and attributes pre-defined by Ecwid, for example, "price per unit". One of: CUSTOM UPC BRAND GENDER AGE_GROUP COLOR SIZE PRICE_PER_UNIT UNITS_IN_PRODUCT
show	string	Defines if an attribute is visible on a product page. One of: NOTSHOW - Not visible. DESCR - Visible under the product description. PRICE - Visible under the product price

alt

Field	Type	Description
main	string	Image description for the "alt" HTML attribute of the image.
translations	object translations	Available translations for the "alt" text.

translations

Object with text field translations in the "lang": "text" format, where the "lang" is an ISO 639-1 language code. For example:

{
    "en": "Sample text",
    "nl": "Voorbeeldtekst"
}

Translations are available for all active store languages. Only the default language translations are returned if no other translations are provided for the field. Find active store languages with GET /profile request > languages > enabledLanguages.