Skip to main content
Books / API / Products / Update Product Endpoint
Products · Revision #2

Update Product Endpoint

Updated 17 hours ago by Ethan Payne

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.

  • Use "_" for ungrouped settings.
  • Each group contains its own object of 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
    }
}

← PREVIOUS
Create Product Endpoint
NEXT →
Variants
Back to top