# Create product variation
`POST` `https://app.ecwid.com/api/v3/{storeId}/products/{productId}/combinations`
{% hint style="info" %}
If specified options do not yet exist, they will be created automatically as a dropdown list (`SELECT` option type).
{% endhint %}
Request and response example
Request:
```http
POST /api/v3/1003/products/692730761/combinations HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache
{
"options": [
{
"name": "Size",
"value": "L",
},
{
"name": "Color",
"value": "Red",
}
],
"price": 10,
"costPrice": 8,
"quantity": 10,
"inStock": true,
"unlimited": false,
"weight": 0.5,
"compareToPrice": 15,
"sku": "combination-sku",
"attributes": [
{
"id": 9998010,
"name": "UPC",
"value": "0435943543594395",
"show": "DESCR",
"type": "UPC"
}
],
"isShippingRequired": true
}
```
Response:
{% code fullWidth="true" %}
```json
{
"id": 397662764
}
```
{% endcode %}
### 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](#options) | Set of selected product option values that identify this variation.
Required
|
| 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](#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](#dimensions) | Variation's dimensions. |
| wholesalePrices | array of objects [wholesalePrices](#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](#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](#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](#translations) | Available translations for the product option name. |
| value | string | Value of the selected option. |
| valueTranslated | object [translations](#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`.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.ecwid.com/api-reference/rest-api/products/product-variations/create-product-variation.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.