post https://app.ecwid.com/api/v3//products//combinations
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.
Access scopes
Requires the following access scope: create_catalog
Request body
A JSON object with the following fields:
| Field | Type | Description |
|---|---|---|
| options | Array<OptionValue> | Set of options that identifies this variation. An array of name-value pairs |
| sku | string | Variation SKU. Omitted if the variation inherits the base product's SKU |
| quantity | number | Amount of the variation items in stock |
| unlimited | boolean | true if the variation has unlimited stock (that is, never runs out) |
| price | number | Variation price. Omitted if the variation inherits the base product's price |
| isShippingRequired | boolean | true if variation requires shipping, false otherwise |
| wholesalePrices | Array<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 |
| 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 |
| 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<AttributeValue> | Variation's UPC attribute and its value |
| compareToPrice | number | Variation's sale price displayed strike-out in the customer frontend Omitted if empty |
| externalReferenceId | string | External ID for products synced from external services (e.g. POS) |
| minPurchaseQuantity | number | Sets minimum product variation purchase quantity. Default value is taken from a base product. |
| maxPurchaseQuantity | number | Sets maximum product variation purchase quantity. Default value is taken from a base product. |
| 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 | Indicates whether an out of stock product should visible or not. One of: SHOW, ALLOW_PREORDER. |
OptionValue
| Field | Type | Description |
|---|---|---|
| name | string | Option name |
| nameTranslated | <Translations> | Available translations for product option name |
| value | string | Option value |
| valueTranslated | <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.
WholesalePrice
| Field | Type | Description |
|---|---|---|
| quantity | number | Number of product items on this wholesale tier |
| price | number | Product price on the tier |
AttributeValue
| Field | Type | Description |
|---|---|---|
| id | number | Unique attribute ID. See Product Classes for the information on attribute IDs. |
| name | string | Can 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 |
| alias | string | One 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. |
| value | string | Attribute value |
| valueTranslated | <Translations> | Available translations for product attribute value |
| show | string | Defines if an attribute is visible on a product page. Supported values: NOTSHOW, DESCR, PRICE. The value PRICE = DESCR. |
Response
A JSON object of type 'CreateStatus' with the following fields:
CreateStatus
| Field | Type | Description |
|---|---|---|
| id | number | ID of the created variation |
Errors
In case of error, Ecwid responds with an error HTTP status code
HTTP codes
| HTTP Status | Meaning |
|---|---|
| 400 | Request parameters are malformed |
| 402 | The "Product Variations" feature are not available on the merchant plan |
| 404 | The product is not found |
| 409 | The specified sku or options variation already exists |
| 415 | Unsupported content-type: expected application/json or text/json |
| 500 | Cannot get the variation because of an error on the server |