NAV

Product variations

Using the methods below you can get/update/delete variations and their details in an Ecwid store. Learn more about product variations in the Ecwid Help Center.

Get all product variations

Get all variations of a specific product in an Ecwid store.

Request example

GET /api/v3/4870020/products/8383892837/combinations?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID

Response

Response example (JSON)

[
  {
    "id":7084071,
    "combinationNumber":6,
    "options":[
      {
        "name":"Size",
        "value":"Large"
      },
      {
        "name":"Color",
        "value":"White"
      }
    ],
    "sku":"000076",
    "smallThumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912079.jpg",
    "hdThumbnailUrl": "https://images-cdn.ecwid.com/images/4870020/397690841.jpg",
    "thumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912077.jpg",
    "imageUrl":"http://images-cdn.ecwid.com/images/4870020/249912061.jpg",
    "originalImageUrl":"http://images-cdn.ecwid.com/images/4870020/249912061.jpg",
    "quantity":21,
    "unlimited":false,
    "price":1.45,
    "wholesalePrices":[
      {
        "quantity":10,
        "price":1.05
      }
    ],
    "warningLimit":1
  },
  {
    "id":7084072,
    "combinationNumber":5,
    "options":[
      {
        "name":"Color",
        "value":"Red"
      },
      {
        "name":"Size",
        "value":"Large"
      }
    ],
    "sku":"000075",
    "quantity":0,
    "unlimited":false,
    "warningLimit":0
  },
  {
    "id":7084075,
    "combinationNumber":2,
    "options":[
      {
        "name":"Size",
        "value":"Small"
      },
      {
        "name":"Color",
        "value":"White"
      }
    ],
    "sku":"000072",
    "smallThumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912078.jpg",
    "hdThumbnailUrl": "https://images-cdn.ecwid.com/images/4870020/397690841.jpg",
    "thumbnailUrl":"http://images-cdn.ecwid.com/images/4870020/249912076.jpg",
    "imageUrl":"http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "originalImageUrl":"http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "quantity":62,
    "unlimited":false,
    "price":1.45,
    "wholesalePrices":[
      {
        "quantity":10,
        "price":1.35
      },
      {
        "quantity":20,
        "price":1.25
      }
    ],
    "warningLimit":10
  },
  {
    "id":7084076,
    "combinationNumber":1,
    "options":[
      {
        "name":"Size",
        "value":"Small"
      },
      {
        "name":"Color",
        "value":"Red"
      }
    ],
    "sku":"000071",
    "quantity":61,
    "unlimited":false,
    "warningLimit":0
  }
]

An array of JSON objects of type ‘Variation’ with the following fields:

Variation

FieldTypeDescription
idnumberVariation ID
combinationNumbernumberVariation # number, which is displayed in the variations table in Control panel
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
thumbnailUrlstringURL of the product variation thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the variation inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product variation image resized to fit 1500x1500px. Omitted if the variation inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product variation thumbnail resized to fit 160x160px. Omitted if the variation inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct variation HD thumbnail URL resized to fit 800x800px. Omitted if the variation inherits the base product’s image.
originalImageUrlstringURL of the original not resized product variation image. Omitted if the variation inherits the base product’s image.
quantitynumberAmount of the variation items in stock. Omitted if the variation inherits the base product’s quantity.
unlimitedbooleantrue if the variation has unlimited stock (that is, never runs out)
pricenumberVariation price. Omitted if the variation inherits the base product’s price.
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.
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.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

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

Errors

Error response example

HTTP/1.1 400 Wrong numeric parameter 'id' value: not a number or a number out of range
Content-Type application/json; charset=utf-8

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
415Unsupported content-type: expected application/json or text/json
500Cannot get variations because of an error on the server

Get product variation

Get a specific product variation details referring to its ID.

Request example

GET /api/v3/4870020/products/8383892837/combinations/772828388?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID
combinationIdnumberInternal variation ID

Response

Response example (JSON)

{
    "id": 7084075,
    "combinationNumber": 2,
    "options": [
        {
            "name": "Size",
            "value": "Small"
        },
        {
            "name": "Color",
            "value": "White"
        }
    ],
    "sku": "000072",
    "smallThumbnailUrl": "http://images-cdn.ecwid.com/images/4870020/249919682.jpg",
    "hdThumbnailUrl": "https://images-cdn.ecwid.com/images/4870020/397690841.jpg",
    "thumbnailUrl": "http://images-cdn.ecwid.com/images/4870020/249919680.jpg",
    "imageUrl": "http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "originalImageUrl": "http://images-cdn.ecwid.com/images/4870020/249912060.jpg",
    "quantity": 62,
    "unlimited": false,
    "price": 1.45,
    "wholesalePrices": [
        {
            "quantity": 10,
            "price": 1.35
        },
        {
            "quantity": 20,
            "price": 1.25
        }
    ],
    "warningLimit": 10
}

An array of JSON objects of type 'Variation’ with the following fields:

Variation

FieldTypeDescription
idnumberVariation ID
combinationNumbernumberCombination # number, which is displayed in the variations table in Control panel
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
thumbnailUrlstringURL of the product variation thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the variation inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product variation image resized to fit 1500x1500px. Omitted if the variation inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product variation thumbnail resized to fit 160x160px. Omitted if the variation inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct variation HD thumbnail URL resized to fit 800x800px. Omitted if the variation inherits the base product’s image.
originalImageUrlstringURL of the original not resized product variation image. Omitted if the variation inherits the base product’s image.
quantitynumberAmount of the variation items in stock. Omitted if the variation inherits the base product’s quantity.
unlimitedbooleantrue if the variation has unlimited stock (that is, never runs out)
pricenumberVariation price. Omitted if the variation inherits the base product’s price.
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.
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.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

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

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

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 variation is not found
415Unsupported content-type: expected application/json or text/json
500Cannot get the variation because of an error on the server

Create product variation

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.

Request example

POST /api/v3/4870020/products/8383892837/combinations?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

{
    "options": [
        {
            "name": "Size",
            "value": "L"
        },
        {
            "name": "Color",
            "value": "Red"
        }
    ],
    "price": 10,
    "quantity": 4,
    "weight": 0.5,
    "sku": "combination-sku"
}

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

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID

Request body

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

Variation

FieldTypeDescription
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. Omitted if the variation inherits the base product’s quantity.
unlimitedbooleantrue if the variation has unlimited stock (that is, never runs out)
pricenumberVariation price. Omitted if the variation inherits the base product’s price.
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.
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.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

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

Response

Response example

{
    "id": 397662764
}

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

CreateStatus

FieldTypeDescription
idnumberID of the created variation

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

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

Update product variation

Update a specific product variation details referring to its ID.

Request example

PUT /api/v3/4870020/products/8383892837/combinations/772828388?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

{
    "price": 10,
    "quantity": 4,
    "weight": 0.5,
    "sku": "combination-new-sku"
}

PUT https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}?checkLowStockNotification={checkLowStockNotification}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID
combinationIdnumberInternal variation ID
checkLowStockNotificationbooleanIf true, makes Ecwid check whether the low stock email notification needs to be sent to merchant after request is sent

Request body

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

Variation

FieldTypeDescription
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. Omitted if the variation inherits the base product’s quantity.
unlimitedbooleantrue if the variation has unlimited stock (that is, never runs out)
pricenumberVariation price. Omitted if the variation inherits the base product’s price.
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.
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.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

WholesalePrice

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

Response

Response example

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated variations (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

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 or variation 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

Delete product variation

Delete a specific product variation referring to its ID.

Request example

DELETE /api/v3/4870020/products/8383892837/combinations/772828388?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID
combinationIdnumberInternal variation ID

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted variations (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

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

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Variations” feature is not available on the merchant plan
404The variation is not found
500Cannot remove the variation because of an error on the server

Delete all product variations

Delete all product variations of a product in an Ecwid store.

Request example

DELETE /api/v3/4870020/products/8383892837/combinations?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
productIdnumberInternal product ID

Response

Response example

{
    "deleteCount": 4
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted variations

Errors

Error response example

HTTP/1.1 404 Not found
Content-Type application/json; charset=utf-8

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

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
402The “Product Variations” feature is not available on the merchant plan
500Cannot delete variations because of an error on the server

Adjust variation inventory

Request example

PUT /api/v3/4870020/products/8383892837/combinations/772828388/inventory?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "quantityDelta": -10
}

When your integration changes in stock quantity of product variation in a store pretty often, it becomes harder and harder to keep track of how many items are actually in stock. For example, when at one point of time you have 3 items in stock and 5 in the very next second, then using the specific values can result in incorrect stock quantity.

This method solves this very problem: you can increase or decrease the product variation’s stock quantity by a delta quantity. For example, if you need to decrease quantity by 10 items, you can use this method.

This method is also available for products.

PUT https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}/inventory?checkLowStockNotification={checkLowStockNotification}&token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
combinationIdnumberVariation ID
tokenstringoAuth token
checkLowStockNotificationbooleanIf true, makes Ecwid check whether the low stock email notification needs to be sent to merchant after request is sent

Request body

A JSON object of type 'Inventory’ with the following fields:

Inventory

FieldTypeDescription
quantityDeltanumberDelta value used to update product quantity. Negative value will decrease quantity, positive one will increase it.

Response

Response example (JSON)

{
  "updateCount": 1
}

A JSON object of type 'InventoryAdjustmentStatus’ with the following fields:

InventoryAdjustmentStatus

FieldTypeDescription
updateCountnumberThe number of updated products (1 or 0 depending on whether the update was successful)
warningstringInventory update warning(optional). For example, the warning will display if the stock became negative

Errors

HTTP/1.1 400 Bad Request
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402This functionality is not available on this plan
404Product not found
415Unsupported content-type: expected application/json or text/json
500Could not process the request, internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload variation image

Upload a custom image for a specific product variation referring to its ID.

Request example

POST /api/v3/4870020/products/1234657/combinations/463737373/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: image/jpeg
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/1003/products/123456/combinations/1233541/image?token=abcdefg123456';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/1003/products/123456/combinations/1233541/image?token=abcdefg123456"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}/image?token={token}&externalUrl={externalUrl}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
combinationIdnumberInternal variation ID
externalUrlstringExternal file URL available for public download. If specified, Ecwid will ignore any binary file data sent in a request

When uploading an image for a variation, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Alternatively, you can specify an externalURL to your file as a request parameter and Ecwid will download it from there.

Response

Response example

{
    "id": 240198557
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal image ID

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

{
    "errorMessage": "Internal server error"
}

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Product or variation in request are not found
413The image file is too large (Maximum allowed file size is 20Mb)
422The uploaded file is not an image
415Unsupported content-type: expected application/octet-stream
500Uploading of the image file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete variation image

Delete an image of a specific product variation in an Ecwid store.

Request example

DELETE /api/v3/4870020/products/1234657/combinations/463737373/image?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations/{combinationId}/image?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
tokenstringoAuth token
combinationIdnumberInternal variation ID

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted images (1 if the image has been removed, 0 otherwise)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, a JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The Product variations are not available on the merchant plan
404Product or variation in request are not found
500Request failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message