# Products

# Product Index Endpoint

## Structure

See [<span class="s1">View Product Endpoint</span>](https://support.aerocommerce.com/books/api/page/view-product-endpoint) for the structure of the order payload inside the data array.

## Scopes

<table border="1" id="bkmrk-name-description-exa" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Description**  
</td><td>**Example**  
</td></tr><tr><td>`active`</td><td>Only return active products</td><td>`?scope=active`</td></tr><tr><td>`inactive`</td><td>Only return inactive products</td><td>`?scope=inactive`</td></tr><tr><td>`visible`</td><td>Only return visible products</td><td>`?scope=visible`</td></tr><tr><td>`hidden`</td><td>Only return hidden products</td><td>`?scope=hidden`</td></tr><tr><td>`published`</td><td>Only return published products</td><td>`?scope=published`</td></tr><tr><td>`unpublished`</td><td>Only return unpublished products</td><td>`?scope=unpublished`</td></tr><tr><td>`scheduled`</td><td>Only return scheduled to be published products</td><td>`?scope=scheduled`</td></tr></tbody></table>

<p class="callout info">These scopes are applied at database level and may not always reflect real-time search index data. For precise filtering use the [Product Search Endpoint](https://support.aerocommerce.com/books/api/page/product-search-endpoint).</p>

## Filters

<table border="1" id="bkmrk-name-description-exa-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Description**  
</td><td>**Example**  
</td></tr><tr><td>`models`</td><td>Only return products with specific models (note: singular form `?model` not supported)</td><td>`?models=ABC,DEF`</td></tr><tr><td>`skus`</td><td>Only return products with variants that have specific SKUs</td><td>`?skus=ABC-123,DEF-456`</td></tr></tbody></table>

<p class="callout info">Plural filters can also be used in singular form (unless otherwise stated), e.g. `?sku=ABC-123` for `?skus=ABC-123`.</p>

## Example Request

```
GET /api/products?per_page=2&min_updated_at=2023-08-30%2010:36:23
```

## Example Response

```json
{
    "current_page": 1,
    "data": [
      //...
    ],
    "first_page_url": "http://aero.test/api/products?page=1",
    "from": 1,
    "last_page": 16,
    "last_page_url": "http://aero.test/api/products?page=16",
    "next_page_url": "http://aero.test/api/products?page=2",
    "path": "http://aero.test/api/products",
    "per_page": 2,
    "prev_page_url": null,
    "to": 2,
    "total": 32
}
```

# Product Search Endpoint

## Pre-requisites

This endpoint performs product search queries using Elasticsearch. Make sure your product documents are indexed before using this route:

```
php artisan aero:search:reindex --type=product
```

<p class="callout info">You must run this command **after** installing the API.</p>

## Structure

See [<span class="s1">View Product Endpoint</span>](https://support.aerocommerce.com/books/api/page/view-product-endpoint) for the structure of the order payload inside the data array.

<table border="1" id="bkmrk-name-description-exa" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Description**  
</td><td>**Example**  
</td></tr><tr><td>`active`</td><td>Only return active products</td><td>`?scope=active`</td></tr><tr><td>`inactive`</td><td>Only return inactive products</td><td>`?scope=inactive`</td></tr><tr><td>`visible`</td><td>Only return visible products</td><td>`?scope=visible`</td></tr><tr><td>`hidden`</td><td>Only return hidden products</td><td>`?scope=hidden`</td></tr><tr><td>`categorised`</td><td>Only return products that are in a category</td><td>`?scope=categorised`</td></tr><tr><td>`un-categorised`</td><td>Only return products that aren't in a category</td><td>`?scope=un-categorised`</td></tr><tr><td>`published`</td><td>Only return published products</td><td>`?scope=published`</td></tr><tr><td>`unpublished`</td><td>Only return unpublished products</td><td>`?scope=unpublished`</td></tr><tr><td>`scheduled`</td><td>Only return scheduled to be published products</td><td>`?scope=scheduled`</td></tr><tr><td>`has-stock`</td><td>Only return products that have stock</td><td>`?scope=has-stock`</td></tr><tr><td>`out-of-stock`</td><td>Only return products that don't have stock</td><td>`?scope=out-of-stock`</td></tr><tr><td>`not-tracking-stock`</td><td>Only return products that aren't tracking stock</td><td>`?scope=not-tracking-stock`</td></tr><tr><td>`reduced`</td><td>Only return reduced products</td><td>`?scope=reduced`</td></tr><tr><td>`not-reduced`</td><td>Only return non-reduced products</td><td>`?scope=not-reduced`</td></tr><tr><td>`has-images`</td><td>Only return products that have images</td><td>`?scope=has-images`</td></tr><tr><td>`no-images`</td><td>Only return products that don't have images</td><td>`?scope=no-images`</td></tr></tbody></table>

## Filters

<table border="1" id="bkmrk-name-description-exa-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Description**  
</td><td>**Example**  
</td></tr><tr><td>`manufacturers`</td><td>Only return products with specific manufacturer ids (or names)</td><td>`?manufacturers=1,burberry`</td></tr><tr><td>`tags`</td><td>Only return products with specific tag ids (or names formatted as `group|name`)</td><td>`?tags=1,colour|red`</td></tr><tr><td>`barcodes`</td><td>Only return products with specific barcodes</td><td>`?barcodes=123,abc`</td></tr><tr><td>`references`</td><td>Only return products with specific references</td><td>`?references=123,abc`</td></tr><tr><td>`price`</td><td>Only return products with specific price in whole units (e.g. pounds, not pence)</td><td>`?price=123`</td></tr><tr><td>`min_price`</td><td>Only return products with price above min price in whole units (e.g. pounds, not pence)</td><td>`?min_price=123`</td></tr><tr><td>`max_price`</td><td>Only return products with price below max price in whole units (e.g. pounds, not pence)</td><td>`?max_price=123`</td></tr><tr><td>`stock_level`</td><td>Only return products with specific stock level</td><td>`?stock_level=1`</td></tr><tr><td>`min_stock_level`</td><td>Only return products with stock above specific stock level</td><td>`?min_stock_level=1`</td></tr><tr><td>`max_stock_level`</td><td>Only return products with stock below specific stock level</td><td>`?max_stock_level=10`</td></tr><tr><td>`type`</td><td>Only return products of a certain type (e.g. simple or variant)</td><td>`?type=variant`</td></tr><tr><td>`models`</td><td>Only return products with specific models</td><td>`?models=ABC,DEF`</td></tr><tr><td>`skus`</td><td>Only return products with variants that have specific SKUs</td><td>`?skus=ABC-123,DEF-456`</td></tr></tbody></table>

<p class="callout info">The `tags` filter applies AND logic across groups and OR logic within groups:  
  
- `?tags=size|small,colour|red` = small **and** red.  
- `?tags=colour|red,colour|green` = red **or** green.</p>

<p class="callout info">Plural filters can also be used in singular form, e.g. `?manufacturer=burberry` for `?manufacturers=burberry`.</p>

## Example Request

```
GET /api/products/search?per_page=2&min_updated_at=2023-08-30%2010:36:23&min_stock_level=1&max_stock_level=10
```

## Example Response

```json
{
    "current_page": 1,
    "data": [
        //...
    ],
    "first_page_url": "http://aero.test/api/products?page=1",
    "from": 1,
    "last_page": 16,
    "last_page_url": "http://aero.test/api/products?page=16",
    "next_page_url": "http://aero.test/api/products?page=2",
    "path": "http://aero.test/api/products",
    "per_page": 2,
    "prev_page_url": null,
    "to": 2,
    "total": 32
}
```

# View Product Endpoint

## Structure

### Product

<table border="1" id="bkmrk-name-type-descriptio" style="border-collapse: collapse; width: 100%; height: 793.734px;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></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></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`model`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The **unique** model identifier for the product</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`name`</td><td style="height: 29.7969px;">string</td><td style="height: 29.7969px;">The display name of the product</td></tr><tr style="height: 52.1953px;"><td style="height: 52.1953px;">`manufacturer`</td><td style="height: 52.1953px;">object</td><td style="height: 52.1953px;">The [Manufacturer](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-manufacturer) object (null when none)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`summary`</td><td style="height: 29.7969px;">string</td><td style="height: 29.7969px;">A short summary of the product</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`description`</td><td style="height: 29.7969px;">string</td><td style="height: 29.7969px;">A detailed description of the product</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`active`</td><td style="height: 46.5938px;">boolean</td><td style="height: 46.5938px;">Whether the product is active (available for purchase)</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`visible`</td><td style="height: 46.5938px;">boolean</td><td style="height: 46.5938px;">Whether the product is visible in the storefront</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`attribute_groups_to_split_by`</td><td style="height: 46.5938px;">?array</td><td style="height: 46.5938px;">The attribute groups to split listings by (null when none)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`published_at`</td><td style="height: 29.7969px;">timestamp</td><td style="height: 29.7969px;">When the product was published</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`images`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Image](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-image) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`categories`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Category](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-category) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`tags`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Tag](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-tag) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`variants`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Variant](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-variant) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`seo`</td><td style="height: 35.3984px;">object</td><td style="height: 35.3984px;">A [SEO](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-seo) object</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/view-product-endpoint#bkmrk-settings) object with grouped key-value pairs</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`additional_attributes`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-additional-attribute) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`specifications` `*`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Specification](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-specification) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`specification_groups` `*`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Specification Group](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-specification-group) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`upsells`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Upsell](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-upsell) objects</td></tr><tr style="height: 35.3984px;"><td style="height: 35.3984px;">`related_listings`</td><td style="height: 35.3984px;">array</td><td style="height: 35.3984px;">An array of [Related Listing](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-related-listing) objects</td></tr></tbody></table>

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

### Manufacturer

<table border="1" id="bkmrk-name-type-descriptio-1" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the manufacturer</td></tr><tr><td>`name`</td><td>string</td><td>The name of the manufacturer</td></tr></tbody></table>

### Image

<table border="1" id="bkmrk-name-type-descriptio-2" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`url`</td><td>string</td><td>The url of the image</td></tr><tr><td>`default`</td><td>bool</td><td>Whether the image is default</td></tr><tr><td>`attributes`</td><td>array</td><td>An array of [Attribute](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-attribute) objects</td></tr></tbody></table>

### Category

<table border="1" id="bkmrk-name-type-descriptio-3" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the category</td></tr><tr><td>`name`</td><td>string</td><td>The name of the category (e.g., Coats)</td></tr><tr><td>`breadcrumb`</td><td>string</td><td>The breadcrumb path for the category (e.g., Mens &gt; Coats)</td></tr></tbody></table>

### Variant

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

### Attribute Group

<table border="1" id="bkmrk-name-type-descriptio-6" style="border-collapse: collapse; width: 100%; height: 29.7969px;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></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></tr><tr><td>`id`</td><td>int</td><td>The id of the tag group</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag group</td></tr><tr><td>`reference`</td><td>string</td><td>The reference of the tag group</td></tr></tbody></table>

### Tag

<table border="1" id="bkmrk-name-type-descriptio-7" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the tag</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag</td></tr><tr><td>`reference`</td><td>string</td><td>The reference of the tag</td></tr><tr><td>`group`</td><td>object</td><td>The [Tag Group](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-tag-group) object</td></tr></tbody></table>

### Tag Group

<table border="1" id="bkmrk-name-type-descriptio-8" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the tag group</td></tr><tr><td>`name`</td><td>string</td><td>The name of the tag group</td></tr><tr><td>`reference`</td><td>string</td><td>The reference of the tag group</td></tr></tbody></table>

### Cost Price

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

### Price

<table border="1" id="bkmrk-name-type-descriptio-10" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the price</td></tr><tr><td>`currency`</td><td>string</td><td>The currency code for the price</td></tr><tr><td>`quantity`</td><td>int</td><td>The quantity required for the price to be detected/applied</td></tr><tr><td>`value.amount`</td><td>float</td><td>The normal price **excluding tax**</td></tr><tr><td>`value.tax`</td><td>float</td><td>The tax for the normal price</td></tr><tr><td>`sale_value.amount`</td><td>float</td><td>The sale price **excluding tax**</td></tr><tr><td>`sale_value.tax`</td><td>float</td><td>The tax for the sale price</td></tr><tr><td>`retail_value.amount`</td><td>float</td><td>The retail price **excluding tax**</td></tr><tr><td>`retail_value.tax`</td><td>float</td><td>The tax for the retail price</td></tr><tr><td>`start_at`</td><td>timestamp</td><td>The start date for when the price is active</td></tr><tr><td>`end_at`</td><td>timestamp</td><td>The end date for when the price is active</td></tr><tr><td>`reference`</td><td>string</td><td>The reference for the price</td></tr></tbody></table>

### SEO

<table border="1" id="bkmrk-name-type-descriptio-11" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`heading`</td><td>string</td><td>The SEO Heading</td></tr><tr><td>`page_title`</td><td>string</td><td>The SEO Page Title</td></tr><tr><td>`meta_description`</td><td>string</td><td>The SEO Meta Description</td></tr><tr><td>`canonical`</td><td>string</td><td>The SEO Canonical</td></tr><tr><td>`noindex`</td><td>boolean</td><td>The SEO No Index</td></tr><tr><td>`nofollow`</td><td>boolean</td><td>The SEO No Follow</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-12" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`key`</td><td>string</td><td>The key of the additional attribute</td></tr><tr><td>`value`</td><td>string</td><td>The value of the additional attribute</td></tr></tbody></table>

### Specification

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

<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/view-product-endpoint#bkmrk-specification-group) for `1.x` structure.</p>

### Specification Group

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

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

### Specification Group Field

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

### Media

<table border="1" id="bkmrk-name-type-descriptio-16" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the media</td></tr><tr><td>`slug`</td><td>string</td><td>The slug of the media</td></tr><tr><td>`disk`</td><td>string</td><td>The disk used to store the media</td></tr><tr><td>`path`</td><td>string</td><td>The path of the media on the disk</td></tr><tr><td>`title`</td><td>string</td><td>The title of the media</td></tr><tr><td>`type`</td><td>string</td><td>The mimetype of the media</td></tr><tr><td>`extension`</td><td>string</td><td>The file extension of the media</td></tr><tr><td>`size`</td><td>int</td><td>The file size of the media in bytes</td></tr><tr><td>`meta`</td><td>object</td><td>The meta data of the media</td></tr><tr><td>`source`</td><td>string</td><td>The source file name of the media</td></tr><tr><td>`is_protected`</td><td>bool</td><td>Whether the media is protected</td></tr></tbody></table>

### Upsell

<table border="1" id="bkmrk-name-type-descriptio-17" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`group`</td><td>object</td><td>The [Upsell Group](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-upsell-group) object (null when none)</td></tr><tr><td>`attributes`</td><td>array</td><td>An array of [Attribute](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-attribute) objects that the upsell shows for</td></tr><tr><td>`models`</td><td>array</td><td>And array of models for the upsell</td></tr><tr><td>`skus`</td><td>array</td><td>And array of SKUs for the upsell</td></tr></tbody></table>

### Upsell Group

<table border="1" id="bkmrk-name-type-descriptio-18" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`key`</td><td>string</td><td>The key of the upsell group</td></tr><tr><td>`name`</td><td>string</td><td>The name of the upsell group</td></tr></tbody></table>

### Related Listing

<table border="1" id="bkmrk-name-type-descriptio-19" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr><td>**Name**  
</td><td>**Type**  
</td><td>**Description**  
</td></tr><tr><td>`id`</td><td>int</td><td>The id of the listing</td></tr><tr><td>`product.id`</td><td>int</td><td>The id of the product linked to the listing</td></tr><tr><td>`product.model`</td><td>string</td><td>The model of the product linked to the listing</td></tr><tr><td>`variants.*.id`</td><td>id</td><td>The id of the variants linked to the listing</td></tr><tr><td>`variants.*.sku`</td><td>string</td><td>The sku of the variants linked to the listing</td></tr><tr><td>`sort`</td><td>int</td><td>The sort of the listing within the group</td></tr></tbody></table>

## Example Requests

```
GET /api/products/{id|model}
```

```
GET /api/products?model=model
```

<p class="callout info">Using the first request syntax is advised, only use the second if/when the model is numeric, as if a matching id exists that would be resolved instead.</p>

## Example Responses

<details id="bkmrk-simple-product-%7B-%22mo"><summary>Simple Product</summary>

```json
{
    "model": "9021182",
    "name": "Detachable Sleeve Puffer Jacket",
    "manufacturer": "Burberry",
    "categories": [
        { 
            "name": "Mens > Coats > Padded Coats"
        }
    ],
    "summary": "Summary",
    "description": "Description",
    "active": true,
    "visible": true,
    "images": [
        {
            "src": "https://picsum.photos/seed/first/600/400",
            "default": true
        }
    ],
    "variants": [
        {
            "sku": "9021182",
            "barcode": "abc123",
            "stock_level": 5,
            "prices": [
                {
                    "currency": "GBP",
                    "price": 790,
                    "quantity": 1
                }
            ],
            "tax_group": "Taxable Product"
        }
    ],
    "tags": [
        {
            "group": { 
                "name": "Colour"
            },
            "name": "Blue"
        }
    ],
    "seo": {
        "heading": "test heading",
        "page_title": "test page title",
        "meta_description": "test meta description",
        "noindex": 0,
        "nofollow": 0
    },
    "additional_attributes": [
        {
            "key": "test_name",
            "value": "test_value"
        }
    ]
}
```

</details><details id="bkmrk-variant-product-%7B-%22i"><summary>Variant Product</summary>

```json
{
    "id": 1,
    "model": "8021182",
    "name": "Detachable Sleeve Puffer Jacket",
    "summary": "Outer: Leather 100%, Polyamide 100%\nLining: Polyester 100%, Goose Down 90%, Wool 70%, Polyamide 20%, Cashmere 10%, Feather 10%",
    "description": "A quintessentially British brand, Burberry creates iconic designs that seamlessly infuse their rich heritage with a contemporary aesthetic. This deep blue wool and cashmere blend detachable sleeve puffer jacket from Burberry features a hood, a high standing collar, a zip and press stud fastening, detachable long sleeves, a contrast logo patch to one side, zipped side slit pockets and a puffer style.",
    "type": "variant",
    "active": true,
    "visible": true,
    "attribute_groups_to_split_by": null,
    "published_at": "2025-06-13T07:34:34.000000Z",
    "manufacturer": {
        "id": 1,
        "name": "Burberry"
    },
    "images": [
        {
            "url": "https://picsum.photos/seed/first/600/400",
            "default": "1"
        },
        {
            "url": "https://picsum.photos/seed/second/600/400",
            "default": "1"
        },
        {
            "url": "https://picsum.photos/seed/third/600/400",
            "default": "1"
        },
    ],
    "categories": [
        {
            "id": 3,
            "name": "Padded Coats",
            "breadcrumb": "Mens » Coats » Padded Coats"
        }
    ],
    "tags": [
        {
            "id": 1,
            "name": "Blue",
            "reference": null,
            "group": {
                "id": 1,
                "name": "Colour",
                "reference": null
            }
        }
    ],
    "seo": {
        "heading": "test heading",
        "page_title": "test page title",
        "meta_description": "test meta description",
        "open_graph": "",
        "canonical": "",
        "noindex": null,
        "nofollow": null
    },
    "variants": [
        {
            "id": 1,
            "sku": "8021182-S",
            "reference": null,
            "name": "",
            "summary": "",
            "description": "",
            "barcode": null,
            "buyable": true,
            "visible": true,
            "shippable": true,
            "discountable": true,
            "infinite_stock": false,
            "stock_level": 5,
            "stock_buffer": 0,
            "weight": null,
            "weight_unit": null,
            "volume": null,
            "volume_unit": null,
            "hs": null,
            "origin_country": null,
            "goods_description": null,
            "cost": {
                "amount": 5623.54,
                "currency": "GBP"
            },
            "price": {
                "amount": 65833.33,
                "tax": 13166.669999999998,
                "currency": "GBP"
            },
            "retail": {
                "amount": null,
                "tax": null,
                "currency": "GBP"
            },
            "prices": [
                {
                    "id": 1,
                    "currency": "GBP",
                    "quantity": 1,
                    "value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "sale_value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "retail_value": {
                        "amount": null,
                        "tax": null
                    },
                    "start_at": null,
                    "end_at": null,
                    "reference": null
                }
            ],
            "images": [
                {
                    "url": "https://picsum.photos/seed/fourth/600/400",
                    "default": "1",
                    "attributes": [
                        {
                            "group": {
                                "name": "Size"
                            },
                            "name": "Small"
                        }
                    ]
                }
            ],
            "attributes": [
                {
                    "id": 1,
                    "name": "Small",
                    "display_name": "Small",
                    "reference": null,
                    "group": {
                        "id": 1,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "tags": [
                {
                    "id": 2,
                    "name": "Small",
                    "reference": null,
                    "group": {
                        "id": 2,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "additional_attributes": []
        },
        {
            "id": 2,
            "sku": "8021182-M",
            "reference": null,
            "name": "",
            "summary": "",
            "description": "",
            "barcode": null,
            "buyable": true,
            "visible": true,
            "shippable": true,
            "discountable": true,
            "infinite_stock": false,
            "stock_level": 5,
            "stock_buffer": 0,
            "weight": null,
            "weight_unit": null,
            "volume": null,
            "volume_unit": null,
            "hs": null,
            "origin_country": null,
            "goods_description": null,
            "cost": {
                "amount": null,
                "currency": null
            },
            "price": {
                "amount": 65833.33,
                "tax": 13166.669999999998,
                "currency": "GBP"
            },
            "retail": {
                "amount": null,
                "tax": null,
                "currency": "GBP"
            },
            "prices": [
                {
                    "id": 2,
                    "currency": "GBP",
                    "quantity": 1,
                    "value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "sale_value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "retail_value": {
                        "amount": null,
                        "tax": null
                    },
                    "start_at": null,
                    "end_at": null,
                    "reference": null
                }
            ],
            "images": [],
            "attributes": [
                {
                    "id": 2,
                    "name": "Medium",
                    "display_name": "Medium",
                    "reference": null,
                    "group": {
                        "id": 1,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "tags": [
                {
                    "id": 3,
                    "name": "Medium",
                    "reference": null,
                    "group": {
                        "id": 2,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "additional_attributes": []
        },
        {
            "id": 3,
            "sku": "8021182-L",
            "reference": null,
            "name": "",
            "summary": "",
            "description": "",
            "barcode": null,
            "buyable": true,
            "visible": true,
            "shippable": true,
            "discountable": true,
            "infinite_stock": false,
            "stock_level": 5,
            "stock_buffer": 0,
            "weight": null,
            "weight_unit": null,
            "volume": null,
            "volume_unit": null,
            "hs": null,
            "origin_country": null,
            "goods_description": null,
            "cost": {
                "amount": null,
                "currency": null
            },
            "price": {
                "amount": 65833.33,
                "tax": 13166.669999999998,
                "currency": "GBP"
            },
            "retail": {
                "amount": null,
                "tax": null,
                "currency": "GBP"
            },
            "prices": [
                {
                    "id": 3,
                    "currency": "GBP",
                    "quantity": 1,
                    "value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "sale_value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "retail_value": {
                        "amount": null,
                        "tax": null
                    },
                    "start_at": null,
                    "end_at": null,
                    "reference": null
                }
            ],
            "images": [],
            "attributes": [
                {
                    "id": 3,
                    "name": "Large",
                    "display_name": "Large",
                    "reference": null,
                    "group": {
                        "id": 1,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "tags": [
                {
                    "id": 4,
                    "name": "Large",
                    "reference": null,
                    "group": {
                        "id": 2,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "additional_attributes": []
        },
        {
            "id": 4,
            "sku": "8021182-XL",
            "reference": null,
            "name": "",
            "summary": "",
            "description": "",
            "barcode": null,
            "buyable": true,
            "visible": true,
            "shippable": true,
            "discountable": true,
            "infinite_stock": false,
            "stock_level": 5,
            "stock_buffer": 0,
            "weight": null,
            "weight_unit": null,
            "volume": null,
            "volume_unit": null,
            "hs": null,
            "origin_country": null,
            "goods_description": null,
            "cost": {
                "amount": null,
                "currency": null
            },
            "price": {
                "amount": 65833.33,
                "tax": 13166.669999999998,
                "currency": "GBP"
            },
            "retail": {
                "amount": null,
                "tax": null,
                "currency": "GBP"
            },
            "prices": [
                {
                    "id": 1,
                    "currency": "GBP",
                    "quantity": 1,
                    "value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "sale_value": {
                        "amount": 65833.33,
                        "tax": 13166.669999999998
                    },
                    "retail_value": {
                        "amount": null,
                        "tax": null
                    },
                    "start_at": null,
                    "end_at": null,
                    "reference": null
                }
            ],
            "images": [],
            "attributes": [
                {
                    "id": 4,
                    "name": "Extra Large",
                    "display_name": "Extra Large",
                    "reference": null,
                    "group": {
                        "id": 1,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "tags": [
                {
                    "id": 5,
                    "name": "Extra Large",
                    "reference": null,
                    "group": {
                        "id": 2,
                        "name": "Size",
                        "reference": null
                    }
                }
            ],
            "additional_attributes": []
        }
    ],
    "additional_attributes": [],
    "settings": []
}
```

</details>

# Create Product Endpoint

## Structure

### Product

<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>`id`</td><td>int</td><td>The id for the product</td><td>No</td></tr><tr><td>`model`</td><td>string</td><td>The **unique** model identifier for the product</td><td>Yes</td></tr><tr><td>`name`</td><td>string</td><td>The display name of the product</td><td>Yes</td></tr><tr><td>`manufacturer`</td><td>string</td><td>The manufacturer/brand of the product</td><td>No</td></tr><tr><td>`summary`</td><td>string</td><td>A short summary of the product</td><td>No</td></tr><tr><td>`description`</td><td>string</td><td>A detailed description of the product</td><td>No</td></tr><tr><td>`active`</td><td>boolean</td><td>Whether the product is active (available for purchase)</td><td>No</td></tr><tr><td>`visible`</td><td>boolean</td><td>Whether the product is visible in the storefront</td><td>No</td></tr><tr><td>`attribute_groups_to_split_by`</td><td>array</td><td>An array of attribute group names to split listings by (e.g., \["Size"\])</td><td>No</td></tr><tr><td>`published_at`</td><td>timestamp</td><td>When the product was published</td><td>No</td></tr><tr><td>`images`</td><td>array</td><td>An array of [Image](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-image) objects</td><td>No</td></tr><tr><td>`categories`</td><td>array</td><td>An array of [Category](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-category) objects</td><td>No</td></tr><tr><td>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-tag) objects</td><td>No</td></tr><tr><td>`variants`</td><td>array</td><td>An array of [Variant](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-variant) objects</td><td>Yes</td></tr><tr><td>`seo`</td><td>object</td><td>A [SEO](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-seo) object</td><td>No</td></tr><tr><td>`settings`</td><td>object</td><td>A [Settings](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td>No</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-additional-attribute) objects</td><td>No</td></tr><tr><td>`specifications` `*`</td><td>array</td><td>An array of [Specification](https://support.aerocommerce.com/books/api/page/create-product-endpoint#bkmrk-specification) objects</td><td>No</td></tr><tr><td>`specification_groups` `*`</td><td>array</td><td>An array of [Specification Group](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-specification-group) objects</td><td>No</td></tr><tr><td>`upsells`</td><td>array</td><td>An array of [Upsell](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-upsell) objects</td><td>No</td></tr><tr><td>`related_listings`</td><td>array</td><td>An array of[ Related Listing](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-related-listing) objects</td><td>No</td></tr></tbody></table>

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

### Category

<table border="1" id="bkmrk-name-type-descriptio-1" 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 category name or breadcrumb (e.g., "Coats" or "Mens &gt; "Coats")</td><td>Yes</td></tr></tbody></table>

### Variant

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

### Attribute 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 attribute group (e.g., "Size", "Colour")</td><td>Yes</td></tr></tbody></table>

### Tag

<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>`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/view-product-endpoint#bkmrk-tag-group) of the tag</td><td>Yes</td></tr></tbody></table>

### Tag Group

<table border="1" id="bkmrk-name-type-descriptio-6" style="border-collapse: collapse; width: 100%; height: 29.7969px;"><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><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-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>`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/view-product-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-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>`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-9" 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>

### SEO

<table border="1" id="bkmrk-name-type-descriptio-10" 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>`heading`</td><td>string</td><td>The SEO Heading</td><td>No</td></tr><tr><td>`page_title`</td><td>string</td><td>The SEO Page Title</td><td>No</td></tr><tr><td>`meta_description`</td><td>string</td><td>The SEO Meta Description</td><td>No</td></tr><tr><td>`canonical`</td><td>string</td><td>The SEO Canonical</td><td>No</td></tr><tr><td>`noindex`</td><td>boolean</td><td>The SEO No Index</td><td>No</td></tr><tr><td>`nofollow`</td><td>boolean</td><td>The SEO No Follow</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-11" 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/view-product-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/view-product-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/view-product-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/view-product-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/view-product-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/view-product-endpoint#bkmrk-specification) 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/view-product-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/view-product-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/view-product-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>

### Related Listing

<table border="1" id="bkmrk-name-type-descriptio-17" style="border-collapse: collapse; width: 100%; height: 245.969px;"><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 style="height: 29.7969px;">`id`</td><td style="height: 29.7969px;">int</td><td style="height: 29.7969px;">The id of the listing</td><td style="height: 29.7969px;">Conditional `*`</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`variant_id`</td><td style="height: 46.5938px;">int</td><td style="height: 46.5938px;">The id of the variant (of the listing)</td><td style="height: 46.5938px;">Conditional `*`</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`sku`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The SKU of the variant (of the listing)</td><td style="height: 46.5938px;">Conditional `*`</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`product_id`</td><td style="height: 46.5938px;">int</td><td style="height: 46.5938px;">The id of the product (of the listing)</td><td style="height: 46.5938px;">Conditional `*`</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`model`</td><td style="height: 46.5938px;">string</td><td style="height: 46.5938px;">The model of the product (of the listing)</td><td style="height: 46.5938px;">Conditional `*`</td></tr></tbody></table>

`*` At least one must be present, resolved in the order they are listed top-down.

## Example Requests

<details id="bkmrk-simple-product-%28one-"><summary>Simple Product (One variant without any attributes)</summary>

```
POST /api/products
```

```json
{
    "model": "9021182",
    "name": "Detachable Sleeve Puffer Jacket",
    "manufacturer": "Burberry",
    "categories": [
        { 
            "name": "Mens > Coats > Padded Coats"
        }
    ],
    "summary": "Summary",
    "description": "Description",
    "active": true,
    "visible": true,
    "images": [
        {
            "src": "https://picsum.photos/seed/first/600/400",
            "is_default": true
        }
    ],
    "variants": [
        {
            "sku": "9021182",
            "barcode": "abc123",
            "stock_level": 5,
            "prices": [
                {
                    "currency": "GBP",
                    "price": 790,
                    "quantity": 1
                }
            ],
            "tax_group": "Taxable Product"
        }
    ],
    "tags": [
        {
            "group": { 
                "name": "Colour"
            },
            "name": "Blue"
        }
    ],
    "seo": {
        "heading": "test heading",
        "page_title": "test page title",
        "meta_description": "test meta description",
        "noindex": 0,
        "nofollow": 0
    },
    "additional_attributes": [
        {
            "key": "test_name",
            "value": "test_value"
        }
    ]
}
```

</details><details id="bkmrk-variant-product-%28mul"><summary>Variant Product (Multiple variants with shared attribute matrix structure)</summary>

```
POST /api/products
```

```json
{
    "model": "9021182",
    "name": "Detachable Sleeve Puffer Jacket",
    "manufacturer": "Burberry",
    "categories": [
        {
            "name": "Mens > Coats > Padded Coats"
        }
    ],
    "summary": "Outer: Leather 100%, Polyamide 100%\nLining: Polyester 100%, Goose Down 90%, Wool 70%, Polyamide 20%, Cashmere 10%, Feather 10%",
    "description": "A quintessentially British brand, Burberry creates iconic designs that seamlessly infuse their rich heritage with a contemporary aesthetic. This deep blue wool and cashmere blend detachable sleeve puffer jacket from Burberry features a hood, a high standing collar, a zip and press stud fastening, detachable long sleeves, a contrast logo patch to one side, zipped side slit pockets and a puffer style.",
    "images": [
        {
            "src": "https://picsum.photos/seed/first/600/400",
            "is_default": "1"
        },
        {
            "src": "https://picsum.photos/seed/second/600/400",
            "is_default": "1"
        },
        {
            "src": "https://picsum.photos/seed/third/600/400",
            "is_default": "1"
        },
        {
            "src": "https://picsum.photos/seed/fourth/600/400",
            "is_default": "1",
            "attributes": [
                {
                    "group": {
                        "name": "Size"
                    },
                    "name": "Small"
                }
            ]
        }
    ],
    "variants": [
        {
            "sku": "9021182-S",
            "stock_level": "5",
            "prices": [
                {
                    "currency": "GBP",
                    "price": "790",
                    "quantity": 1
                }
            ],
            "tax_group": "Taxable Product",
            "attributes": [
                {
                    "group": {
                        "name": "Size"
                    },
                    "name": "Small",
                    "tags": [
                        {
                            "group": {
                                "name": "Size"
                            },
                            "name": "Small"
                        }
                    ]
                }
            ],
            "stock_buffer": 0,
            "minimum_quantity": 1,
            "multiples_of": 1
        },
        {
            "sku": "9021182-M",
            "stock_level": "5",
            "prices": [
                {
                    "currency": "GBP",
                    "price": "790",
                    "quantity": 1
                }
            ],
            "tax_group": "Taxable Product",
            "attributes": [
                {
                    "group": {
                        "name": "Size"
                    },
                    "name": "Medium",
                    "tags": [
                        {
                            "group": {
                                "name": "Size"
                            },
                            "name": "Medium"
                        }
                    ]
                }
            ],
            "stock_buffer": 0,
            "minimum_quantity": 1,
            "multiples_of": 1
        },
        {
            "sku": "9021182-L",
            "stock_level": "5",
            "prices": [
                {
                    "currency": "GBP",
                    "price": "790",
                    "quantity": 1
                }
            ],
            "tax_group": "Taxable Product",
            "attributes": [
                {
                    "group": {
                        "name": "Size"
                    },
                    "name": "Large",
                    "tags": [
                        {
                            "group": {
                                "name": "Size"
                            },
                            "name": "Large"
                        }
                    ]
                }
            ],
            "stock_buffer": 0,
            "minimum_quantity": 1,
            "multiples_of": 1
        },
        {
            "sku": "9021182-XL",
            "stock_level": "5",
            "prices": [
                {
                    "currency": "GBP",
                    "price": "790",
                    "quantity": 1
                }
            ],
            "tax_group": "Taxable Product",
            "attributes": [
                {
                    "group": {
                        "name": "Size"
                    },
                    "name": "Extra Large",
                    "tags": [
                        {
                            "group": {
                                "name": "Size"
                            },
                            "name": "Extra Large"
                        }
                    ]
                }
            ],
            "stock_buffer": 0,
            "minimum_quantity": 1,
            "multiples_of": 1
        }
    ],
    "tags": [
        {
            "group": {
                "name": "Colour"
            },
            "name": "Blue"
        }
    ],
    "active": true,
    "visible": true,
    "hide_when_no_stock": false,
    "seo": {
        "heading": "test heading",
        "page_title": "test page title",
        "meta_description": "test meta description",
        "noindex": 0,
        "nofollow": 0
    },
    "settings": {
        "_": {
            "no_group": "value"
        },
        "group": {
            "key": "value"
        }
    },
    "additional_attributes": [
        {
            "key": "test_name",
            "value": "test_value"
        }
    ]
}
```

</details>## Example Response

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

# Update Product Endpoint

## Structure

### Product

<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>`name`</td><td>string</td><td>The name of the product</td><td>No</td></tr><tr><td>`manufacturer`</td><td>string</td><td>The manufacturer of the product</td><td>No</td></tr><tr><td>`summary`</td><td>string</td><td>The summary of the product</td><td>No</td></tr><tr><td>`description`</td><td>string</td><td>The description of the product</td><td>No</td></tr><tr><td>`active`</td><td>boolean</td><td>Whether the product is active</td><td>No</td></tr><tr><td>`visible`</td><td>boolean</td><td>Whether the product is visible</td><td>No</td></tr><tr><td>`attribute_groups_to_split_by`</td><td>array</td><td>An array of attribute group names to split listings by (e.g., \["Size"\]</td><td>No</td></tr><tr><td>`published_at`</td><td>timestamp</td><td>When the product was published</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-product-endpoint#bkmrk-image) objects</td><td>No</td></tr><tr><td>`categories`</td><td>array</td><td>An array of [Category](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-category) objects</td><td>No</td></tr><tr><td>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-tag) objects</td><td>No</td></tr><tr><td>`variants`</td><td>array</td><td>An array of [Variant](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-variant) objects</td><td>No</td></tr><tr><td>`seo`</td><td>object</td><td>A [SEO](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-seo) object</td><td>No</td></tr><tr><td>`settings`</td><td>object</td><td>A [Settings](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td>No</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-additional-attribute) objects</td><td>No</td></tr><tr><td>`specifications` `*`</td><td>array</td><td>An array of [Specification](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-specification) objects</td><td>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-product-endpoint#bkmrk-specification-group) objects</td><td>No</td></tr><tr><td>`upsells`</td><td>array</td><td>An array of [Upsell](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-upsell) objects</td><td>No</td></tr><tr><td>`related_listings`</td><td>array</td><td>An array of [Related Listing](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-related-listing) objects</td><td>No</td></tr></tbody></table>

<p class="callout info">`*` `specifications` is if using `<1.0.0` version of `aerocargo/specifications`, otherwise use `specification_groups`.</p>

### Category

<table border="1" id="bkmrk-name-type-descriptio-1" 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 category name or breadcrumb (e.g., "Coats" or "Mens &gt; "Coats")</td><td>Yes</td></tr></tbody></table>

### Variant

<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>`sku`</td><td>string</td><td>The **unique** SKU for the variant to be updated</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>`stock_action`</td><td>string</td><td>The stock action (e.g., set, add, remove &amp; multiply). Defaults to set</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>`tags`</td><td>array</td><td>An array of [Tag](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-tag) 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-product-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-product-endpoint#bkmrk-price) objects</td><td>No</td></tr><tr><td>`additional_attributes`</td><td>array</td><td>An array of [Additional Attribute](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-additional-attribute) objects</td><td>No</td></tr><tr><td>`specifications` `*`</td><td>array</td><td>An array of [Specification](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-specification) objects</td><td>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-product-endpoint#bkmrk-specification-group) objects</td><td>No</td></tr><tr><td>`upsells`</td><td>array</td><td>An array of [Upsell](https://support.aerocommerce.com/books/api/page/view-product-endpoint#bkmrk-upsell) objects</td><td>No</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-product-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-product-endpoint#bkmrk-attribute) objects that apply to this image</td><td>No</td></tr></tbody></table>

### Attribute

<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>`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-product-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-product-endpoint#bkmrk-attribute-group) of the attribute</td><td>Yes</td></tr></tbody></table>

### Attribute Group

<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>`name`</td><td>string</td><td>The name of the attribute group (e.g., "Size", "Colour")</td><td>Yes</td></tr></tbody></table>

### Cost Price

<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>`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-9" 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>

### SEO

<table border="1" id="bkmrk-name-type-descriptio-10" 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>`heading`</td><td>string</td><td>The SEO Heading</td><td>No</td></tr><tr><td>`page_title`</td><td>string</td><td>The SEO Page Title</td><td>No</td></tr><tr><td>`meta_description`</td><td>string</td><td>The SEO Meta Description</td><td>No</td></tr><tr><td>`canonical`</td><td>string</td><td>The SEO Canonical</td><td>No</td></tr><tr><td>`noindex`</td><td>boolean</td><td>The SEO No Index</td><td>No</td></tr><tr><td>`nofollow`</td><td>boolean</td><td>The SEO No Follow</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-11" 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-product-endpoint#bkmrk-media) objects</td><td>`*`</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 Group for `1.x` structure.</p>

### Specification Group

<table border="1" id="bkmrk-name-type-descriptio-13" style="border-collapse: collapse; width: 100%; height: 229.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</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</td><td style="height: 46.5938px;">`*`</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`fields`</td><td style="height: 29.7969px;">array</td><td style="height: 29.7969px;">An array of [Field](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-specification-group-) objects</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">`media`</td><td style="height: 29.7969px;">array</td><td style="height: 29.7969px;">An array of [Media](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-media) objects</td><td style="height: 29.7969px;">No</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">`settings`</td><td style="height: 46.5938px;">object</td><td style="height: 46.5938px;">A [Settings](https://support.aerocommerce.com/books/api/page/update-product-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td style="height: 46.5938px;">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 for `0.x` structure.</p>

### Specification Group Field

<table border="1" id="bkmrk-name-type-descriptio-14" 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 field</td><td>`*`</td></tr><tr><td>`name`</td><td>string</td><td>The name of the specification group field</td><td>`*`</td></tr><tr><td>`value`</td><td>string</td><td>The value of the specification group field</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-product-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-product-endpoint#bkmrk-settings) object with grouped key-value pairs</td><td>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>

### 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.name`</td><td>string</td><td>The upsell group name</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-product-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>

### Related Listing

<table border="1" id="bkmrk-name-type-descriptio-17" 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 listing</td><td>Conditional `*`</td></tr><tr><td>`variant_id`</td><td>int</td><td>The id of the variant (of the listing)</td><td>Conditional `*`</td></tr><tr><td>`sku`</td><td>string</td><td>The SKU of the variant (of the listing)</td><td>Conditional `*`</td></tr><tr><td>`product_id`</td><td>int</td><td>The id of the product (of the listing)</td><td>Conditional `*`</td></tr><tr><td>`model`</td><td>string</td><td>The model of the product (of the listing)</td><td>Conditional `*`</td></tr></tbody></table>

`*` At least one must be present, resolved in the order they are listed top-down.

## Example Requests

<details id="bkmrk-update-basic-product"><summary>Update Basic Product Details</summary>

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

```json
{
    "name": "Detachable Sleeve Puffer Jacket v2",
    "manufacturer": "Burberry v2",
    "summary": "A lightweight puffer with removable sleeves.",
    "description": "This updated puffer jacket offers versatility with detachable sleeves, premium fill, and water-resistant fabric.",
    "active": true,
    "visible": true
}
```

</details><details id="bkmrk-add-categories-to-pr"><summary>Add Categories to Product</summary>

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

```json
{
    "categories": [
        { 
            "name": "Mens > Jackets",
        },
        { 
            "name": "Winter Collection"
        }
    ]
}
```

</details><details id="bkmrk-add-tags-to-product-"><summary>Add Tags to Product</summary>

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

```json
{
    "tags": [
        {
            "group": {
                "name": "Colour"
            },
            "name": "Indigo"
        },
        {
            "group": {
                "name": "Season"
            },
            "name": "Winter 2023"
        }
    ]
}
```

</details><details id="bkmrk-update-variant-by-sk"><summary>Update Variant by Sku</summary>

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

```json
{
    "variants": [
        {
            "sku": "9021182-S",
            "stock_level": 50,
            "buyable": true,
            "tags": [
                {
                    "group": {
                        "name": "Style"
                    },
                    "name": "Casual"
                }
            ],
            "prices": [
                {
                    "price": 199.99,
                    "sale_price": 179.99,
                    "currency": "GBP"
                }
            ],
            "cost": {
                "amount": 350,
                "currency": "GBP"
            }
        }
    ]
}
```

</details><details id="bkmrk-update-images-put-%2Fa"><summary>Update Images</summary>

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

```json
{
    "images": [
        {
            "src": "https://picsum.photos/seed/front/600/400",
            "alt": "Front view of detachable sleeve puffer jacket",
            "is_default": true,
            "position": 1
        },
        {
            "src": "https://picsum.photos/seed/back/600/400",
            "alt": "Back view of detachable sleeve puffer jacket",
            "position": 2
        }
    ]
}
```

</details><details id="bkmrk-update-product-seo-%26"><summary>Update Product SEO &amp; Settings</summary>

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

```json
{
    "seo": {
        "heading": "Detachable Sleeve Puffer Jacket",
        "page_title": "Men’s Detachable Sleeve Puffer Jacket | Burberry",
        "meta_description": "Shop the Burberry detachable sleeve puffer jacket – versatile winterwear with premium fill and removable sleeves.",
        "canonical": "https://shop.example.com/mens/detachable-sleeve-puffer",
        "noindex": false,
        "nofollow": false
    },
    "settings": {
        "_": {
            "featured": "true"
        },
        "shipping": {
            "oversized": "false"
        }
    }
}
```

</details><p class="callout info">You can use `PUT /api/products?model=model` if your model is numeric and might clash with an `id`.</p>

## Example Response  


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