Products

Product Index Endpoint

Structure

See View Product Endpoint for the structure of the order payload inside the data array.

Scopes

Name
 Description
 Example
active Only return active products ?scope=active
inactive Only return inactive products ?scope=inactive
visible Only return visible products ?scope=visible
hidden Only return hidden products ?scope=hidden
published Only return published products ?scope=published
unpublished Only return unpublished products ?scope=unpublished
scheduled Only return scheduled to be published products ?scope=scheduled

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.

Filters

Name
 Description
 Example
models Only return products with specific models (note: singular form ?model not supported) ?models=ABC,DEF
skus Only return products with variants that have specific SKUs ?skus=ABC-123,DEF-456

Plural filters can also be used in singular form (unless otherwise stated), e.g. ?sku=ABC-123 for ?skus=ABC-123.

Example Request

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

Example Response

{
    "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

You must run this command after installing the API.

Structure

See View Product Endpoint for the structure of the order payload inside the data array.

Name
 Description
 Example
active Only return active products ?scope=active
inactive Only return inactive products ?scope=inactive
visible Only return visible products ?scope=visible
hidden Only return hidden products ?scope=hidden
categorised Only return products that are in a category ?scope=categorised
un-categorised Only return products that aren't in a category ?scope=un-categorised
published Only return published products ?scope=published
unpublished Only return unpublished products ?scope=unpublished
scheduled Only return scheduled to be published products ?scope=scheduled
has-stock Only return products that have stock ?scope=has-stock
out-of-stock Only return products that don't have stock ?scope=out-of-stock
not-tracking-stock Only return products that aren't tracking stock ?scope=not-tracking-stock
reduced Only return reduced products ?scope=reduced
not-reduced Only return non-reduced products ?scope=not-reduced
has-images Only return products that have images ?scope=has-images
no-images Only return products that don't have images ?scope=no-images

Filters

Name
 Description
 Example
manufacturers Only return products with specific manufacturer ids (or names) ?manufacturers=1,burberry
tags Only return products with specific tag ids (or names formatted as group|name) ?tags=1,colour|red
barcodes Only return products with specific barcodes ?barcodes=123,abc
references Only return products with specific references ?references=123,abc
price Only return products with specific price in whole units (e.g. pounds, not pence) ?price=123
min_price Only return products with price above min price in whole units (e.g. pounds, not pence) ?min_price=123
max_price Only return products with price below max price in whole units (e.g. pounds, not pence) ?max_price=123
stock_level Only return products with specific stock level ?stock_level=1
min_stock_level Only return products with stock above specific stock level ?min_stock_level=1
max_stock_level Only return products with stock below specific stock level ?max_stock_level=10
type Only return products of a certain type (e.g. simple or variant) ?type=variant
models Only return products with specific models ?models=ABC,DEF
skus Only return products with variants that have specific SKUs ?skus=ABC-123,DEF-456

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.

Plural filters can also be used in singular form, e.g. ?manufacturer=burberry for ?manufacturers=burberry.

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

{
    "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

Name
 Type
 Description
model string The unique model identifier for the product
name string The display name of the product
manufacturer object The Manufacturer object (null when none)
summary string A short summary of the product
description string A detailed description of the product
active boolean Whether the product is active (available for purchase)
visible boolean Whether the product is visible in the storefront
attribute_groups_to_split_by ?array The attribute groups to split listings by (null when none)
published_at timestamp When the product was published
images array An array of Image objects
categories array An array of Category objects
tags array An array of Tag objects
variants array An array of Variant objects
seo object A SEO object
settings object A Settings object with grouped key-value pairs
additional_attributes array An array of Additional Attribute objects
specifications * array An array of Specification objects
specification_groups * array An array of Specification Group objects
upsells array An array of Upsell objects
related_listings array An array of Related Listing objects

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

Manufacturer

Name
 Type
 Description
id int The id of the manufacturer
name string The name of the manufacturer

Image

Name
 Type
 Description
url string The url of the image
default bool Whether the image is default
attributes array An array of Attribute objects

Category

Name
 Type
 Description
id int The id of the category
name string The name of the category (e.g., Coats)
breadcrumb string The breadcrumb path for the category (e.g., Mens > Coats)

Variant

Name
 Type
 Description
sku string The unique SKU for the variant
reference string The unique reference for the variant
name string Display name of the variant
summary string A short summary of the variant
description string A detailed description of the variant
barcode string The barcode/UPC/EAN of the variant
buyable boolean Whether the variant can be purchased
visible boolean Whether the variant is visible in listings
shippable boolean Whether the variant is shippable
discountable boolean Whether discounts can be applied to this variant
hide_when_no_stock boolean Whether the variant should be hidden when out of stock
infinite_stock boolean Whether the variant has unlimited stock
stock_level int Current stock level
stock_buffer int The stock buffer
tax_group string The tax group applied to the variant
minimum_quantity int Minimum quantity per purchase
maximum_quantity int Maximum quantity per purchase
multiples_of int Purchasable only in multiples of this number
weight float Weight of the variant
weight_unit string Unit of weight (e.g., kg, lb)
volume float Volume of the variant
volume_unit string Unit of volume (e.g., m^3, cm^3)
hs string HS (Harmonized System) code for customs
price.amount float The current price of the variant excluding tax
price.tax float The tax of the current price
price.currency string The currency of the current price
retail.amount float The RRP for the variant excluding tax
retail.tax float The tax of the RRP
retail.currency string The currency of the RRP
origin_country string ISO country code of origin (e.g., US, GB)
goods_description string Description of goods for customs
attributes array An array of Attribute objects
tags array An array of Tag objects
cost object The Cost Price of the variant
prices array An array of Price objects
additional_attributes array An array of Additional Attribute objects
specifications * array An array of Specification objects
specification_groups * array An array of Specification Group objects
upsells array An array of Upsell objects

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

Attribute

Name
 Type
 Description
id int The id of the attribute
name string The name of the attribute
reference string The reference of the attribute
group object The Attribute Group object

Attribute Group

Name
 Type
 Description
id int The id of the tag group
name string The name of the tag group
reference string The reference of the tag group

Tag

Name
 Type
 Description
id int The id of the tag
name string The name of the tag
reference string The reference of the tag
group object The Tag Group object

Tag Group

Name
 Type
 Description
id int The id of the tag group
name string The name of the tag group
reference string The reference of the tag group

Cost Price

Name
 Type
 Description
amount float The cost price including tax
currency string Currency code (defaults to store default if not provided)

Price

Name
 Type
 Description
id int The id of the price
currency string The currency code for the price
quantity int The quantity required for the price to be detected/applied
value.amount float The normal price excluding tax
value.tax float The tax for the normal price
sale_value.amount float The sale price excluding tax
sale_value.tax float The tax for the sale price
retail_value.amount float The retail price excluding tax
retail_value.tax float The tax for the retail price
start_at timestamp The start date for when the price is active
end_at timestamp The end date for when the price is active
reference string The reference for the price

SEO

Name
 Type
 Description
heading string The SEO Heading
page_title string The SEO Page Title
meta_description string The SEO Meta Description
canonical string The SEO Canonical
noindex boolean The SEO No Index
nofollow boolean The SEO No Follow

Settings

Settings are grouped as key-value pairs.

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

Additional Attribute

Name
 Type
 Description
key string The key of the additional attribute
value string The value of the additional attribute

Specification

Name
 Type
 Description
group.name string The name of the specification group
name string The name of the specification
value string The value of the specification
media array An array of Media objects

This is only for <1.0.0 version of aerocargo/specifications. See Specification Group for 1.x structure.

Specification Group

Name
 Type
 Description
id int The id of the specification group
name string The name of the specification group
fields array An array of Field objects
media array An array of Media objects
settings object A Settings object with grouped key-value pairs

This is only for >=1.0.0 version of aerocargo/specifications. See Specification for 0.x structure.

Specification Group Field

Name
 Type
 Description
id int The id of the specification group field
name string The name of the specification group field
value string The value of the specification group field
media array An array of Media objects
settings object A Settings object with grouped key-value pairs

Media

Name
 Type
 Description
id int The id of the media
slug string The slug of the media
disk string The disk used to store the media
path string The path of the media on the disk
title string The title of the media
type string The mimetype of the media
extension string The file extension of the media
size int The file size of the media in bytes
meta object The meta data of the media
source string The source file name of the media
is_protected bool Whether the media is protected

Upsell

Name
 Type
 Description
group object The Upsell Group object (null when none)
attributes array An array of Attribute objects that the upsell shows for
models array And array of models for the upsell
skus array And array of SKUs for the upsell

Upsell Group

Name
 Type
 Description
key string The key of the upsell group
name string The name of the upsell group
Name
 Type
 Description
id int The id of the listing
product.id int The id of the product linked to the listing
product.model string The model of the product linked to the listing
variants.*.id id The id of the variants linked to the listing
variants.*.sku string The sku of the variants linked to the listing
sort int The sort of the listing within the group

Example Requests

GET /api/products/{id|model}
GET /api/products?model=model

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.

Example Responses

Simple Product 
{
    "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"
        }
    ]
}
Variant Product 
{
    "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": []
}

Create Product Endpoint

Structure

Product

Name
 Type
 Description
 Required
id int The id for the product No
model string The unique model identifier for the product Yes
name string The display name of the product Yes
manufacturer string The manufacturer/brand of the product No
summary string A short summary of the product No
description string A detailed description of the product No
active boolean Whether the product is active (available for purchase) No
visible boolean Whether the product is visible in the storefront No
attribute_groups_to_split_by array An array of attribute group names to split listings by (e.g., ["Size"]) No
published_at timestamp When the product was published No
images array An array of Image objects No
categories array An array of Category objects No
tags array An array of Tag objects No
variants array An array of Variant objects Yes
seo object A SEO object No
settings object A Settings object with grouped key-value pairs No
additional_attributes array An array of Additional Attribute objects No
specifications * array An array of Specification objects No
specification_groups * array An array of Specification Group objects No
upsells array An array of Upsell objects No
related_listings array An array of Related Listing objects No

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

Category

Name
 Type
 Description
 Required
name string The category name or breadcrumb (e.g., "Coats" or "Mens > "Coats") Yes

Variant

Name
 Type
 Description
 Required
id int The id for the variant No
sku string The unique SKU for the variant Yes
reference string The unique reference for the variant No
name string Display name of the variant No
summary string A short summary of the variant No
description string A detailed description of the variant No
barcode string The barcode/UPC/EAN of the variant No
buyable boolean Whether the variant can be purchased No
visible boolean Whether the variant is visible in listings No
shippable boolean Whether the variant is shippable No
discountable boolean Whether discounts can be applied to this variant No
hide_when_no_stock boolean Whether the variant should be hidden when out of stock No
infinite_stock boolean Whether the variant has unlimited stock No
stock_level int Current stock level No
stock_buffer int The stock buffer No
tax_group string The tax group applied to the variant No
minimum_quantity int Minimum quantity per purchase No
maximum_quantity int Maximum quantity per purchase No
multiples_of int Purchasable only in multiples of this number No
weight float Weight of the variant No
weight_unit string Unit of weight (e.g., kg, lb) No
volume float Volume of the variant No
volume_unit string Unit of volume (e.g., m^3, cm^3) No
hs string HS (Harmonized System) code for customs No
origin_country string ISO country code of origin (e.g., US, GB) No
goods_description string Description of goods for customs No
attributes array An array of Attribute objects If product has variants
tags array An array of Tag objects No
cost object The Cost Price of the variant No
prices array An array of Price objects Yes
additional_attributes array An array of Additional Attribute objects No
specifications * array An array of Specification objects No
specification_groups * array An array of Specification Group objects No
upsells array An array of Upsell objects No

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

Attribute

Name
 Type
 Description
 Required
name string The name of the attribute (e.g., "Small" or "Red") Yes
tags array An array of Tag objects linked to the attribute No
group object The Attribute Group of the attribute Yes

Attribute Group

Name
 Type
 Description
 Required
name string The name of the attribute group (e.g., "Size", "Colour") Yes

Tag

Name
 Type
 Description
 Required
name string The name of the tag (e.g., "Small" or "Red") Yes
group object The Tag Group of the tag Yes

Tag Group

Name
 Type
 Description
 Required
name string The name of the tag group (e.g., "Size" or "Colour" Yes

Image

Name
 Type
 Description
 Required
src string The source url of the image Yes
alt string Alt text for accessibility and SEO No
is_default boolean Whether this is a default image No
position int Sort order position of the image No
attributes array An array of Attribute objects that apply to this image No

Cost Price

Name
 Type
 Description
 Required
amount float The cost price including tax Yes
currency string Currency code (defaults to store default if not provided) No

Price

Name
 Type
 Description
 Required
price float The base price including tax Yes
sale_price float The sale price including tax No
retail_price float The retail price including tax No
quantity int Quantity required for this price tier (default: 1) No
currency string Currency code (defaults to store default) No
start_at timestamp When this price becomes active (e.g., 2023-09-01 09:29:41) No
end_at timestamp When this price expires No
reference string The unique reference for the price No

SEO

Name
 Type
 Description
 Required
heading string The SEO Heading No
page_title string The SEO Page Title No
meta_description string The SEO Meta Description No
canonical string The SEO Canonical No
noindex boolean The SEO No Index No
nofollow boolean The SEO No Follow No

Settings

Settings are grouped as key-value pairs.

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

Additional Attribute

Name
 Type
 Description
 Required
key string The key of the additional attribute Yes
value string The value of the additional attribute Yes

Specification

Name
 Type
 Description
 Required
group.name string The name of the specification group Yes
name string The name of the specification *
value string The value of the specification No
media array An array of Media objects *

* 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.

This is only for <1.0.0 version of aerocargo/specifications. See Specification Group for 1.x structure.

Specification Group

Name
 Type
 Description
 Required
id int The id of the specification group *
name string The name of the specification group *
fields array An array of Field objects Yes
media array An array of Media objects No
settings object A Settings object with grouped key-value pairs No

* At least one must be present.

This is only for >=1.0.0 version of aerocargo/specifications. See Specification for 0.x structure.

Specification Group Field

Name
 Type
 Description
 Required
id int The id of the specification group field *
name string The name of the specification group field *
value string The value of the specification group field Yes
media array An array of Media objects No
settings object A Settings object with grouped key-value pairs No

* At least one must be present.

Media

Name
 Type
 Description
 Required
id int The id of the media *
source string The source of the media, e.g. test.png *

* At least one must be present.

Upsell

Name
 Type
 Description
 Required
group.key string The upsell group key Yes
attributes array An array of Attribute objects that the upsell shows for No
models array And array of models for the upsell No
skus array And array of SKUs for the upsell No
Name
 Type
 Description
 Required
id int The id of the listing Conditional *
variant_id int The id of the variant (of the listing) Conditional *
sku string The SKU of the variant (of the listing) Conditional *
product_id int The id of the product (of the listing) Conditional *
model string The model of the product (of the listing) Conditional *

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

Example Requests

Simple Product (One variant without any attributes) 
POST /api/products
{
    "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"
        }
    ]
}
Variant Product (Multiple variants with shared attribute matrix structure) 
POST /api/products
{
    "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"
        }
    ]
}

Example Response

{
    "product": {
        "id": 1
    }
}

Update Product Endpoint

Structure

Product

Name
 Type
 Description
 Required
name string The name of the product No
manufacturer string The manufacturer of the product No
summary string The summary of the product No
description string The description of the product No
active boolean Whether the product is active No
visible boolean Whether the product is visible No
attribute_groups_to_split_by array An array of attribute group names to split listings by (e.g., ["Size"] No
published_at timestamp When the product was published No
images array An array of Image objects No
categories array An array of Category objects No
tags array An array of Tag objects No
variants array An array of Variant objects No
seo object A SEO object No
settings object A Settings object with grouped key-value pairs No
additional_attributes array An array of Additional Attribute objects No
specifications * array An array of Specification objects No
specification_groups * array An array of Specification Group objects No
upsells array An array of Upsell objects No
related_listings array An array of Related Listing objects No

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

Category

Name
 Type
 Description
 Required
name string The category name or breadcrumb (e.g., "Coats" or "Mens > "Coats") Yes

Variant

Name
 Type
 Description
 Required
sku string The unique SKU for the variant to be updated Yes
reference string The unique reference for the variant No
name string Display name of the variant No
summary string A short summary of the variant No
description string A detailed description of the variant No
barcode string The barcode/UPC/EAN of the variant No
buyable boolean Whether the variant can be purchased No
visible boolean Whether the variant is visible in listings No
shippable boolean Whether the variant is shippable No
discountable boolean Whether discounts can be applied to this variant No
hide_when_no_stock boolean Whether the variant should be hidden when out of stock No
infinite_stock boolean Whether the variant has unlimited stock No
stock_level int Current stock level No
stock_buffer int The stock buffer No
stock_action string The stock action (e.g., set, add, remove & multiply). Defaults to set No
tax_group string The tax group applied to the variant No
minimum_quantity int Minimum quantity per purchase No
maximum_quantity int Maximum quantity per purchase No
multiples_of int Purchasable only in multiples of this number No
weight float Weight of the variant No
weight_unit string Unit of weight (e.g., kg, lb) No
volume float Volume of the variant No
volume_unit string Unit of volume (e.g., m^3, cm^3) No
hs string HS (Harmonized System) code for customs No
origin_country string ISO country code of origin (e.g., US, GB) No
goods_description string Description of goods for customs No
tags array An array of Tag objects No
cost object The Cost Price of the variant No
prices array An array of Price objects No
additional_attributes array An array of Additional Attribute objects No
specifications * array An array of Specification objects No
specification_groups * array An array of Specification Group objects No
upsells array An array of Upsell objects No

Tag

Name
 Type
 Description
 Required
name string The name of the tag (e.g., "Small" or "Red") Yes
group object The Tag Group of the tag Yes

Tag Group

Name
 Type
 Description
 Required
name string The name of the tag group (e.g., "Size" or "Colour" Yes

Image

Name
 Type
 Description
 Required
src string The source url of the image Yes
alt string Alt text for accessibility and SEO No
is_default boolean Whether this is a default image No
position int Sort order position of the image No
attributes array An array of Attribute objects that apply to this image No

Attribute

Name
 Type
 Description
 Required
name string The name of the attribute (e.g., "Small" or "Red") Yes
tags array An array of Tag objects linked to the attribute No
group object The Attribute Group of the attribute Yes

Attribute Group

Name
 Type
 Description
 Required
name string The name of the attribute group (e.g., "Size", "Colour") Yes

Cost Price

Name
 Type
 Description
 Required
amount float The cost price including tax Yes
currency string Currency code (defaults to store default if not provided) No

Price

Name
 Type
 Description
 Required
price float The base price including tax Yes
sale_price float The sale price including tax No
retail_price float The retail price including tax No
quantity int Quantity required for this price tier (default: 1) No
currency string Currency code (defaults to store default) No
start_at timestamp When this price becomes active (e.g., 2023-09-01 09:29:41) No
end_at timestamp When this price expires No
reference string The unique reference for the price No

SEO

Name
 Type
 Description
 Required
heading string The SEO Heading No
page_title string The SEO Page Title No
meta_description string The SEO Meta Description No
canonical string The SEO Canonical No
noindex boolean The SEO No Index No
nofollow boolean The SEO No Follow No

Settings

Settings are grouped as key-value pairs.

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

Additional Attribute

Name
 Type
 Description
 Required
key string The key of the additional attribute Yes
value string The value of the additional attribute Yes

Specification

Name
 Type
 Description
 Required
group.name string The name of the specification group Yes
name string The name of the specification *
value string The value of the specification No
media array An array of Media objects *

* At least one must be present.

This is only for <1.0.0 version of aerocargo/specifications. See Specification Group for 1.x structure.

Specification Group

Name
 Type
 Description
 Required
id int The id of the specification group *
name string The name of the specification group *
fields array An array of Field objects No
media array An array of Media objects No
settings object A Settings object with grouped key-value pairs No

* At least one must be present.

This is only for >=1.0.0 version of aerocargo/specifications. See Specification for 0.x structure.

Specification Group Field

Name
 Type
 Description
 Required
id int The id of the specification group field *
name string The name of the specification group field *
value string The value of the specification group field No
media array An array of Media objects No
settings object A Settings object with grouped key-value pairs No

* At least one must be present.

Media

Name
 Type
 Description
 Required
id int The id of the media *
source string The source of the media, e.g. test.png *

Upsell

Name
 Type
 Description
 Required
group.name string The upsell group name No
attributes array An array of Attribute objects that the upsell shows for No
models array And array of models for the upsell No
skus array And array of SKUs for the upsell No
Name
 Type
 Description
 Required
id int The id of the listing Conditional *
variant_id int The id of the variant (of the listing) Conditional *
sku string The SKU of the variant (of the listing) Conditional *
product_id int The id of the product (of the listing) Conditional *
model string The model of the product (of the listing) Conditional *

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

Example Requests

Update Basic Product Details 
PUT /api/products/{id|model}
{
    "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
}
Add Categories to Product 
PUT /api/products/{id|model}
{
    "categories": [
        { 
            "name": "Mens > Jackets",
        },
        { 
            "name": "Winter Collection"
        }
    ]
}
Add Tags to Product 
PUT /api/products/{id|model}
{
    "tags": [
        {
            "group": {
                "name": "Colour"
            },
            "name": "Indigo"
        },
        {
            "group": {
                "name": "Season"
            },
            "name": "Winter 2023"
        }
    ]
}
Update Variant by Sku 
PUT /api/products/{id|model}
{
    "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"
            }
        }
    ]
}
Update Images 
PUT /api/products/{id|model}
{
    "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
        }
    ]
}
Update Product SEO & Settings 
PUT /api/products/{id|model}
{
    "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"
        }
    }
}

You can use PUT /api/products?model=model if your model is numeric and might clash with an id.

Example Response

{
    "product": {
        "id": 1
    }
}