NAV

Product combinations

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

Get all product combinations

Get all combinations 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 ‘Combination’ with the following fields:

Combination

FieldTypeDescription
idnumberCombination ID
combinationNumbernumberCombination # number, which is displayed in the combinations table in Control panel
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
thumbnailUrlstringURL of the product combination 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 combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product combination image resized to fit 1500x1500px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product combination thumbnail resized to fit 160x160px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct combination HD thumbnail URL resized to fit 800x800px. Omitted if the combination inherits the base product’s image.
originalImageUrlstringURL of the original not resized product combination image. Omitted if the combination inherits the base product’s image.
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedbooleantrue if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination 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 Combinations” feature are not available on the merchant plan
415Unsupported content-type: expected application/json or text/json
500Cannot get combinations because of an error on the server

Get product combination

Get a specific product combination 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 combination 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 'Combination’ with the following fields:

Combination

FieldTypeDescription
idnumberCombination ID
combinationNumbernumberCombination # number, which is displayed in the combinations table in Control panel
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
thumbnailUrlstringURL of the product combination 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 combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
imageUrlstringURL of the product combination image resized to fit 1500x1500px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product combination thumbnail resized to fit 160x160px. Omitted if the combination inherits the base product’s image. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct combination HD thumbnail URL resized to fit 800x800px. Omitted if the combination inherits the base product’s image.
originalImageUrlstringURL of the original not resized product combination image. Omitted if the combination inherits the base product’s image.
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedbooleantrue if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination 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 Combinations” feature are not available on the merchant plan
404The combination is not found
415Unsupported content-type: expected application/json or text/json
500Cannot get the combination because of an error on the server

Create product combination

You can create a new product combination 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 'Combination’ with the following fields:

Combination

FieldTypeDescription
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedbooleantrue if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination 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 combination

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 Combinations” 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 combination because of an error on the server

Update product combination

Update a specific product combination 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}?token={token}

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

Request body

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

Combination

FieldTypeDescription
optionsArray<OptionValue>Set of options that identifies this combination. An array of name-value pairs
skustringCombination SKU. Omitted if the combination inherits the base product’s SKU
quantitynumberAmount of the combination items in stock. Omitted if the combination inherits the base product’s quantity.
unlimitedbooleantrue if the combination has unlimited stock (that is, never runs out)
pricenumberCombination price. Omitted if the combination inherits the base product’s price.
wholesalePricesArray<WholesalePrice>Sorted array of the combination’s wholesale price tiers (quantity limit and price). Omitted if the combination inherits the base product’s tiered price settings.
weightnumberCombination weight in the units defined in store settings. Omitted if the combination inherits the base product’s weight.
warningLimitnumberThe minimum 'warning’ amount of the product items in stock for this combination, if set. When the combination in stock amount reaches this level, the store administrator gets an email notification. Omitted if the combination 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 combinations (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 Combinations” feature are not available on the merchant plan
404The product or combination is not found
409The specified sku or options variation already exists
415Unsupported content-type: expected application/json or text/json
500Cannot get the combination because of an error on the server

Delete product combination

Delete a specific product combination 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 combination ID

Response

Response example

{
    "deleteCount": 1
}

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

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted combinations (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 Combinations” feature is not available on the merchant plan
404The combination is not found
500Cannot remove the combination because of an error on the server

Delete all product combinations

Delete all product combinations 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 combinations

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 Combinations” feature is not available on the merchant plan
500Cannot delete combinations because of an error on the server

Adjust combination 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 combination 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 combination’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?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
productIdnumberProduct ID
combinationIdnumberCombination ID
tokenstringoAuth token

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 combination image

Upload a custom image for a specific product combination 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 combination 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 combination, 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 combination 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 combination image

Delete an image of a specific product combination 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 combination 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 combinations are not available on the merchant plan
404Product or combination 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