Search product variations

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

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

Request and response example

Request:

curl --location 'https://app.ecwid.com/api/v3/1003/products/692730761/combinations' \
--header 'Authorization: Bearer secret_ab***cd'

Response:

[
    {
        "id": 422488527,
        "combinationNumber": 3,
        "options": [
            {
                "name": "Mark",
                "nameTranslated": {
                    "cs": "",
                    "en": "Mark"
                },
                "value": "III",
                "valueTranslated": {
                    "cs": "",
                    "en": "III"
                }
            }
        ],
        "inStock": true,
        "unlimited": true,
        "attributes": [],
        "defaultDisplayedPrice": 27.5,
        "defaultDisplayedPriceFormatted": "€27,50",
        "dimensions": {
            "length": 0,
            "width": 0,
            "height": 0
        },
        "volume": 0,
        "outOfStockVisibilityBehaviour": "SHOW",
        "lowestPrice": 10,
        "defaultDisplayedLowestPrice": 11,
        "defaultDisplayedLowestPriceFormatted": "€11,00",
        "lowestPriceSettings": {
            "lowestPriceEnabled": true
        },
        "alt": {
            "translated": {}
        }
    },
    {
        "id": 422488528,
        "combinationNumber": 2,
        "options": [
            {
                "name": "Mark",
                "nameTranslated": {
                    "cs": "",
                    "en": "Mark"
                },
                "value": "II",
                "valueTranslated": {
                    "cs": "",
                    "en": "II"
                }
            }
        ],
        "inStock": true,
        "unlimited": true,
        "attributes": [],
        "defaultDisplayedPrice": 27.5,
        "defaultDisplayedPriceFormatted": "€27,50",
        "dimensions": {
            "length": 0,
            "width": 0,
            "height": 0
        },
        "volume": 0,
        "outOfStockVisibilityBehaviour": "SHOW",
        "lowestPrice": 10,
        "defaultDisplayedLowestPrice": 11,
        "defaultDisplayedLowestPriceFormatted": "€11,00",
        "lowestPriceSettings": {
            "lowestPriceEnabled": true
        },
        "alt": {
            "translated": {}
        }
    },
    {
        "id": 422488529,
        "combinationNumber": 1,
        "options": [
            {
                "name": "Mark",
                "nameTranslated": {
                    "cs": "",
                    "en": "Mark"
                },
                "value": "I",
                "valueTranslated": {
                    "cs": "",
                    "en": "I"
                }
            }
        ],
        "inStock": true,
        "unlimited": true,
        "attributes": [],
        "defaultDisplayedPrice": 27.5,
        "defaultDisplayedPriceFormatted": "€27,50",
        "dimensions": {
            "length": 0,
            "width": 0,
            "height": 0
        },
        "volume": 0,
        "outOfStockVisibilityBehaviour": "SHOW",
        "lowestPrice": 10,
        "defaultDisplayedLowestPrice": 11,
        "defaultDisplayedLowestPriceFormatted": "€11,00",
        "lowestPriceSettings": {
            "lowestPriceEnabled": true
        },
        "alt": {
            "translated": {}
        }
    }
]

Access scopes

Requires the following access scope: read_catalog

Path params

Param	Type	Description
storeId	number	Ecwid store ID.
productId	number	Product ID.

Query params

All query params are optional.

Param	Type	Description
lang	string	Language ISO code for translations in JSON response, e.g. `en`, `fr`. If a certain field does not have the translation available for the set language, the default language text will be used for that field
responseFields	string	Limit JSON response by specific fields. If specified, all missing fields will be removed from the response body. Example: `?responseFields=id,inStock`

Example of using responseFields param:

curl --location 'https://app.ecwid.com/api/v3/1003/products/692730761/combinations?responseFields=id,inStock' \
--header 'Authorization: Bearer secret_ab***cd'

[
    {
        "id": 422488527,
        "inStock": true
    },
    {
        "id": 422488528,
        "inStock": true
    },
    {
        "id": 422488529,
        "inStock": true
    }
]

Headers

The Authorization header with a secret access token is required.

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

Response

An array of JSON objects with the following fields:

Field	Type	Description
id	number	Unique product variation ID.
combinationNumber	number	Sorting number of the product variation starting with `1`.
options	Array options	Set of options and their choices that identify the variation.
sku	string	Variation SKU.
imageUrl	string	URL of the product variation image resized to fit 1500x1500px.
hdThumbnailUrl	string	URL of the product variation thumbnail resized to fit 800x800px.
thumbnailUrl	string	URL of the product variation thumbnail resized to fit 400x400px.
smallThumbnailUrl	string	URL of the product variation thumbnail resized to fit 160x160px.
originalImageUrl	string	URL of the original not resized product variation image. Omitted if the variation inherits the base product's image from the `originalImageUrl` field.
imageExternalId	string	Image ID for Lightspeed R-Series/X-Series image sync. Read-only
quantity	number	In-stock amount of the product variation. If `sku` is omitted, uses base product stock.
unlimited	boolean	`true` if the variation has unlimited stock.
price	number	Product variation price.
isShippingRequired	boolean	`true` if variation requires shipping, `false` otherwise
wholesalePrices	Array wholesalePrices	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
weight	number	Variation weight in the units defined in store settings. Omitted if the variation inherits the base product's weight.
warningLimit	number	The 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
attributes	Array attributes	Variation's UPC attribute and its value
defaultDisplayedPrice	number	Product price displayed in a storefront for logged out customer for default location (store location). May differ from the price value when the product has options and variations and the default variation's price is different from the base product price. It also includes taxes
defaultDisplayedPriceFormatted	string	Formatted displayed price
costPrice	number	Purchase 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
dimensions	Object dimensions	Variation dimensions info
compareToPrice	number	Variation's sale price displayed strike-out in the customer frontend Omitted if empty
minPurchaseQuantity	number	Sets minimum product variation purchase quantity. Default value is taken from a base product. Not visible if the value is not assigned.
maxPurchaseQuantity	number	Sets maximum product variation purchase quantity. Default value is taken from a base product. Not visible if the value is not assigned.
lowestPrice	number	Value of the product's "Lowest price" used for promotions. This value matches with the one displayed in Ecwid admin.
defaultDisplayedLowestPrice	number	Value of the lowest product price with applied taxes (`lowestPrice` + `tax`). Matches with the lowest product price displayed on the storefront.
defaultDisplayedLowestPriceFormatted	string	Formatted lowest price displayed on the storefront (`defaultDisplayedLowestPrice`). Uses store formatting settings. Example: `"defaultDisplayedLowestPrice": 45` => `"defaultDisplayedLowestPriceFormatted": "45.00"`.
outOfStockVisibilityBehaviour	string	Defines if a variation is visible and/or can be pre-ordered when out-of-stock. Requires enabled pre-orders which can be enabled with the `allowPreordersForOutOfStockProducts` setting in `/profile` endpoint. Supported values: `SHOW` - Show out-of-stock variations, but adding them to the cart is impossible. `HIDE` - Hide out-of-stock variations. `ALLOW_PREORDER` - Show out-of-stock variations and allow them to be added to the cart.

options

Field	Type	Description
name	string	Option name
nameTranslated	Object translations	Available translations for product option name
value	string	Option value
valueTranslated	Object translations	Available translations for product option value

translations

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

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

Translations for each available language. If no other translations are provided, the default language translations is returned. See available languages in store language settings.

wholesalePrices

Field	Type	Description
quantity	number	Number of product items on this wholesale tier
price	number	Product price on the tier

attributes

Field	Type	Description
id	number	Unique attribute ID. See Product Classes for the information on attribute IDs
name	string	Attribute displayed name
value	string	Attribute value
type	string	Attribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: `CUSTOM`, `UPC`, `BRAND`, `GENDER`, `AGE_GROUP`, `COLOR`, `SIZE`, `PRICE_PER_UNIT`, `UNITS_IN_PRODUCT`
show	string	Defines where to display the product attribute value:. Supported values: `NOTSHOW`, `DESCR`, `PRICE`

dimensions

Field	Type	Description
length	number	Length of a variation
width	number	Width of a variation
height	number	Height of a variation