# Update Variant Endpoint

#### Structure

##### Variant

<table border="1" id="bkmrk-name-type-descriptio" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`sku`</td><td>string</td><td>The **unique** SKU for the variant</td><td>Yes</td></tr><tr><td>`reference`</td><td>string</td><td>The **unique** reference for the variant</td><td>No</td></tr><tr><td>`name`</td><td>string</td><td>Display name of the variant</td><td>No</td></tr><tr><td>`summary`</td><td>string</td><td>A short summary of the variant</td><td>No</td></tr><tr><td>`description`</td><td>string</td><td>A detailed description of the variant</td><td>No</td></tr><tr><td>`barcode`</td><td>string</td><td>The barcode/UPC/EAN of the variant</td><td>No</td></tr><tr><td>`buyable`</td><td>boolean</td><td>Whether the variant can be purchased</td><td>No</td></tr><tr><td>`visible`</td><td>boolean</td><td>Whether the variant is visible in listings</td><td>No</td></tr><tr><td>`shippable`</td><td>boolean</td><td>Whether the variant is shippable</td><td>No</td></tr><tr><td>`discountable`</td><td>boolean</td><td>Whether discounts can be applied to this variant</td><td>No</td></tr><tr><td>`hide_when_no_stock`</td><td>boolean</td><td>Whether the variant should be hidden when out of stock</td><td>No</td></tr><tr><td>`infinite_stock`</td><td>boolean</td><td>Whether the variant has unlimited stock</td><td>No</td></tr><tr><td>`stock_level`</td><td>int</td><td>Current stock level</td><td>No</td></tr><tr><td>`stock_buffer`</td><td>int</td><td>The stock buffer</td><td>No</td></tr><tr><td>`tax_group`</td><td>string</td><td>The tax group applied to the variant</td><td>No</td></tr><tr><td>`minimum_quantity`</td><td>int</td><td>Minimum quantity per purchase</td><td>No</td></tr><tr><td>`maximum_quantity`</td><td>int</td><td>Maximum quantity per purchase</td><td>No</td></tr><tr><td>`multiples_of`</td><td>int</td><td>Purchasable only in multiples of this number</td><td>No</td></tr><tr><td>`weight`</td><td>float</td><td>Weight of the variant</td><td>No</td></tr><tr><td>`weight_unit`</td><td>string</td><td>Unit of weight (e.g., `kg`, `lb`)</td><td>No</td></tr><tr><td>`volume`</td><td>float</td><td>Volume of the variant</td><td>No</td></tr><tr><td>`volume_unit`</td><td>string</td><td>Unit of volume (e.g., `m^3`, `cm^3`)</td><td>No</td></tr><tr><td>`hs`</td><td>string</td><td>HS (Harmonized System) code for customs</td><td>No</td></tr><tr><td>`origin_country`</td><td>string</td><td>ISO country code of origin (e.g., `US`, `GB`)</td><td>No</td></tr><tr><td>`goods_description`</td><td>string</td><td>Description of goods for customs</td><td>No</td></tr><tr><td>`attributes`</td><td>array</td><td>An array of [Attribute](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-attribute) objects</td><td>Yes</td></tr><tr><td>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-tag) objects</td><td>No</td></tr><tr><td>`images`</td><td>array</td><td>An array of [Image](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-image) objects</td><td>No</td></tr><tr><td>`cost`</td><td>object</td><td>The [Cost Price](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-cost-price) of the variant</td><td>No</td></tr><tr><td>`prices`</td><td>array</td><td>An array of [Price](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-price) objects</td><td>Yes</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-additional-attribute) objects</td><td>No  
</td></tr><tr><td style="height: 46.5938px;">`specifications` `*`</td><td style="height: 46.5938px;">array</td><td style="height: 46.5938px;">An array of [Specification](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-specification) objects</td><td style="height: 46.5938px;">No</td></tr><tr><td>`specification_groups` `*`</td><td>array</td><td>An array of [Specification Group](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-specification-group) objects</td><td>No</td></tr><tr><td style="height: 29.7969px;">`upsells`</td><td style="height: 29.7969px;">array</td><td style="height: 29.7969px;">An array of [Upsell](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-upsell) objects</td><td style="height: 29.7969px;">No</td></tr></tbody></table>

`*` `specifications` is if using `<1.0.0` version of `aerocargo/specifications`, otherwise use `specification_groups`.

##### Attribute

<table border="1" id="bkmrk-name-type-descriptio-1" style="border-collapse: collapse; width: 100%; height: 59.5938px;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">**Type**  
</td><td style="height: 29.7969px;">**Description**  
</td><td style="height: 29.7969px;">**Required**  
</td></tr><tr style="height: 29.7969px;"><td>`name`</td><td>string</td><td>The name of the attribute (e.g., "Small" or "Red")</td><td>Yes</td></tr><tr><td>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-tag) objects linked to the attribute</td><td>No</td></tr><tr><td>`group`</td><td>object</td><td>The [Attribute Group](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-attribute-group) of the attribute</td><td>Yes</td></tr></tbody></table>

##### Attribute Group

<table border="1" id="bkmrk-name-type-descriptio-2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the attribute group (e.g., "Size", "Colour")</td><td>Yes</td></tr></tbody></table>

##### Tag

<table border="1" id="bkmrk-name-type-descriptio-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag (e.g., "Small" or "Red")</td><td>Yes</td></tr><tr><td>`group`</td><td>object</td><td>The [Tag Group](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-tag-group) of the tag</td><td>Yes</td></tr></tbody></table>

##### Tag Group

<table border="1" id="bkmrk-name-type-descriptio-4" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag group (e.g., "Size" or "Colour"</td><td>Yes</td></tr></tbody></table>

##### Image

<table border="1" id="bkmrk-name-type-descriptio-5" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`src`</td><td>string</td><td>The source url of the image</td><td>Yes</td></tr><tr><td>`alt`</td><td>string</td><td>Alt text for accessibility and SEO</td><td>No</td></tr><tr><td>`is_default`</td><td>boolean</td><td>Whether this is a default image</td><td>No</td></tr><tr><td>`position`</td><td>int</td><td>Sort order position of the image</td><td>No</td></tr><tr><td>`attributes`</td><td>array</td><td>An array of [Attribute](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-attribute) objects that apply to this image</td><td>No</td></tr></tbody></table>

##### Cost Price

<table border="1" id="bkmrk-name-type-descriptio-6" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`amount`</td><td>float</td><td>The cost price **including tax**</td><td>Yes</td></tr><tr><td>`currency`</td><td>string</td><td>Currency code (defaults to store default if not provided)</td><td>No</td></tr></tbody></table>

##### Price

<table border="1" id="bkmrk-name-type-descriptio-7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`price`</td><td>float</td><td>The base price **including tax**</td><td>Yes</td></tr><tr><td>`sale_price`</td><td>float</td><td>The sale price **including tax**</td><td>No</td></tr><tr><td>`retail_price`</td><td>float</td><td>The retail price **including tax**</td><td>No</td></tr><tr><td>`quantity`</td><td>int</td><td>Quantity required for this price tier (default: 1)</td><td>No</td></tr><tr><td>`currency`</td><td>string</td><td>Currency code (defaults to store default)</td><td>No</td></tr><tr><td>`start_at`</td><td>timestamp</td><td>When this price becomes active (e.g., 2023-09-01 09:29:41)</td><td>No</td></tr><tr><td>`end_at`</td><td>timestamp</td><td>When this price expires</td><td>No</td></tr><tr><td>`reference`</td><td>string</td><td>The **unique** reference for the price</td><td>No</td></tr></tbody></table>

##### Settings

Settings are grouped as key-value pairs.

- Use "\_" for ungrouped settings.
- Each group contains its own object of key-value pairs.

```json
{
    "settings": {
        "_": {
            "no_group": "value"
        },
        "group": {
            "key": "value"
        }
    }
}
```


##### Additional Attribute

<table border="1" id="bkmrk-name-type-descriptio-8" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`key`</td><td>string</td><td>The key of the additional attribute</td><td>Yes</td></tr><tr><td>`value`</td><td>string</td><td>The value of the additional attribute</td><td>Yes</td></tr></tbody></table>

##### Specification

<table border="1" id="bkmrk-name-type-descriptio-12" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`group.name`</td><td>string</td><td>The name of the specification group</td><td>Yes</td></tr><tr><td>`name`</td><td>string</td><td>The name of the specification</td><td>`*`</td></tr><tr><td>`value`</td><td>string</td><td>The value of the specification</td><td>No</td></tr><tr><td>`media`</td><td>array</td><td>An array of [Media](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-media) objects</td><td>`*`</td></tr></tbody></table>

`*` At least one must be present, futhermore if the group doesn't exist and is to be created you must provide at least one field for it.

<p class="callout info">This is only for `<1.0.0` version of `aerocargo/specifications`. See [Specification Group](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-specification-group) for `1.x` structure.</p>

##### Specification Group

<table border="1" id="bkmrk-name-type-descriptio-13" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**</td></tr><tr><td>`id`</td><td>int</td><td>The id of the specification group</td><td>`*`</td></tr><tr><td>`name`</td><td>string</td><td>The name of the specification group</td><td>`*`</td></tr><tr><td>`fields`</td><td>array</td><td>An array of [Field](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-specification-group-) objects</td><td>Yes</td></tr><tr><td>`media`</td><td>array</td><td>An array of [Media](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-media) objects</td><td>No</td></tr><tr><td>`settings`</td><td>object</td><td>A [Settings](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td>No</td></tr></tbody></table>

`*` At least one must be present.

<p class="callout info">This is only for `>=1.0.0` version of `aerocargo/specifications`. See [Specification](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-specification-group-) for `0.x` structure.</p>

##### Specification Group Field

<table border="1" id="bkmrk-name-type-descriptio-14" style="border-collapse: collapse; width: 100%; height: 257.172px;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Name**  
</td><td style="height: 29.7969px;">**Type**  
</td><td style="height: 29.7969px;">**Description**  
</td><td style="height: 29.7969px;">**Required**  
</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`id`</td><td style="height: 46.5938px;">int</td><td style="height: 46.5938px;">The id of the specification group field</td><td style="height: 46.5938px;">`*`</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`name`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The name of the specification group field</td><td style="height: 46.5938px;">`*`</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`value`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The value of the specification group field</td><td style="height: 46.5938px;">Yes</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`media`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Media](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-media) objects</td><td style="height: 35.3984px;">No</td></tr><tr style="height: 52.1953px;"><td style="height: 52.1953px;">`settings`</td><td style="height: 52.1953px;">object</td><td style="height: 52.1953px;">A [Settings](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td style="height: 52.1953px;">No</td></tr></tbody></table>

`*` At least one must be present.

##### Media

<table border="1" id="bkmrk-name-type-descriptio-15" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the media</td><td>`*`</td></tr><tr><td>`source`</td><td>string</td><td>The source of the media, e.g. test.png</td><td>`*`</td></tr></tbody></table>

`*` At least one must be present.

##### Upsell

<table border="1" id="bkmrk-name-type-descriptio-16" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col><col style="width: 25.0298%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td><td>**Required**  
</td></tr><tr><td>`group.key`</td><td>string</td><td>The upsell group key</td><td>Yes</td></tr><tr><td>`attributes`</td><td>array</td><td>An array of [Attribute](https://support.aerocommerce.com/books/api/page/update-variant-endpoint/update-variant-endpoint#bkmrk-attribute) objects that the upsell shows for</td><td>No</td></tr><tr><td>`models`</td><td>array</td><td>And array of models for the upsell</td><td>No</td></tr><tr><td>`skus`</td><td>array</td><td>And array of SKUs for the upsell</td><td>No</td></tr></tbody></table>

#### Example Request  


<details id="bkmrk-update-basic-variant"><summary>Update Basic Variant Details</summary>

```
PUT /api/products/{id|model}/variants/{id|sku}
```

```json
{
    "stock_level": 50,
    "buyable": true,
    "prices": [
        {
            "price": 199.99,
            "sale_price": 179.99,
            "currency": "GBP"
        }
    ],
    "cost": {
        "amount": 350,
        "currency": "GBP"
    }
}
```

</details><details id="bkmrk-add-tags-to-variant-"><summary>Add Tags to Variant</summary>

```
PUT /api/products/{id|model}/variants/{id|sku}
```

```json
{
    "tags": [
        {
            "group": { 
                "name": "Size"
            },
            "name": "Small"
        },
        {
            "group": { 
                "name": "Style"
            },
            "name": "Casual"
        }
    ]
}
```

</details><details id="bkmrk-add-images-to-varian"><summary>Add Images to Variant</summary>

```
PUT /api/products/{id|model}/variants/{id|sku}
```

```json
{
    "images": [
        {
            "src": "https://picsum.photos/seed/puffer-s/600/400",
            "alt": "Small size jacket, front view",
            "is_default": true,
            "position": 1,
            "attributes": [
                {
                    "name": "Small",
                    "group": {
                        "name": "Size"
                    }
                }
            ]
        }
    ]
}
```

<p class="callout info">Variant images must include at least one attribute, and each attribute must exactly match one of the variant’s attributes.</p>

</details><details id="bkmrk-add-additional-attri"><summary>Add Additional Attributes to Variant</summary>

```
PUT /api/products/{id|model}/variants/{id|sku}
```

```json
{
    "additional_attributes": [
        { 
            "key": "material", 
            "value": "100% leather"
        },
        { 
            "key": "lining", 
            "value": "Polyester"
        }
    ]
}
```

</details>#### Example Response

```json
{
    "variant": {
        "id": 1
    }
}
```