> For the complete documentation index, see [llms.txt](https://docs.shipbubble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shipbubble.com/api-reference/marketplaces/products/create-a-variable-product.md).

# Create a variable product

Add a product with multiple variations (e.g. size, colour) to your marketplace store.

```
POST /v1/external/marketplace/{store_id}/products/variable
```

{% hint style="info" %}
Each variation must have at least one attribute. Attributes are used to distinguish variations from one another — ensure `name` and `value` Combinations are unique across variations within the same product.
{% endhint %}

## Path Parameters

| Parameter  | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| `store_id` | string | Yes      | Your unique marketplace store ID |

## Request Body

### Top-level Fields

| Parameter          | Type   | Required | Description                                        |
| ------------------ | ------ | -------- | -------------------------------------------------- |
| `name`             | string | Yes      | Product name                                       |
| `description`      | string | Yes      | Short product description                          |
| `currency`         | string | Yes      | Currency code e.g. `NGN`, `USD`, `GBP`             |
| `image_1`          | string | Yes      | URL of the primary product image                   |
| `variations`       | array  | Yes      | List of product variations (at least one required) |
| `category_name`    | string | Yes      | Product category e.g. `Shoes`, `Dresses`, `Tees`   |
| `store_product_id` | string | Yes      | Your unique identifer for the product on your      |

### Variation Object

Each object in the `variations` array supports the following fields:

| Parameter              | Type   | Required | Description                                           |
| ---------------------- | ------ | -------- | ----------------------------------------------------- |
| `price`                | number | Yes      | Price of this variation in the specified currency     |
| `kg_weight`            | number | Yes      | Weight of this variation in kilograms                 |
| `dimensions`           | object | Yes      | Physical dimensions of this variation                 |
| `dimensions.length_cm` | number | Yes      | Length in centimetres                                 |
| `dimensions.width_cm`  | number | Yes      | Width in centimetres                                  |
| `dimensions.height_cm` | number | Yes      | Height in centimetres                                 |
| `image`                | string | Yes      | URL of the image for this specific variation          |
| `attributes`           | array  | Yes      | List of attribute objects defining this variation     |
| `store_variation_id`   | string | Yes      | Your unique identifer for the product variant on your |

### Attribute Object

Each object in the `attributes` array supports the following fields:

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `name`    | string | Yes      | Attribute name e.g. `Size`, `Color`, `Material` |
| `value`   | string | Yes      | Attribute value e.g. `42`, `Red`, `Cotton`      |

## Response

```json
{
    "status": "success",
    "message": "Classic Sneakers created successfully",
    "data": {
        "product_id": "88049e93357d",
        "name": "Classic Sneakers",
        "description": "Available in multiple sizes",
        "type": "variable",
        "sku": "GEN-CLAS-DFCFB",
        "currency": "NGN",
        "images": [
            "https://example.com/sneakers.jpg"
        ],
        "category": "Shoes",
        "total_stock": 0,
        "is_active": true,
        "captured": "2026-03-12T13:32:05.000Z",
        "variants": [
            {
                "variation_id": "1acca52c37fd",
                "sku": "GEN-CLAS-DFCFB-AEC3",
                "price": 15000,
                "dimensions": {
                    "length_cm": 35,
                    "width_cm": 20,
                    "height_cm": 15
                },
                "total_stock": 0,
                "available_stock": 0,
                "is_active": true,
                "image": "https://example.com/sneakers-red.jpg",
                "attributes": [
                    {
                        "variation_id": "1acca52c37fd",
                        "name": "Size",
                        "value": "42"
                    },
                    {
                        "variation_id": "1acca52c37fd",
                        "name": "Color",
                        "value": "Red"
                    }
                ]
            },
            {
                "variation_id": "ef914eedf36b",
                "sku": "GEN-CLAS-DFCFB-F9EC",
                "price": 15000,
                "dimensions": {
                    "length_cm": 35,
                    "width_cm": 20,
                    "height_cm": 15
                },
                "total_stock": 0,
                "available_stock": 0,
                "is_active": true,
                "image": "https://example.com/sneakers-blue.jpg",
                "attributes": [
                    {
                        "variation_id": "ef914eedf36b",
                        "name": "Size",
                        "value": "43"
                    },
                    {
                        "variation_id": "ef914eedf36b",
                        "name": "Color",
                        "value": "Blue"
                    }
                ]
            }
        ]
    }
}
```