Skip to main content
Books / API / Variants / Create Variant Endpoint
Variants · Revision #4

Create Variant Endpoint

Updated 18 hours ago by Ethan Payne

Create Variant Endpoint

Structure

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 Yes
tags array An array of Tag objects No
images array An array of Image 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
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, 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

Example Request

POST /api/products/{id|model}/variants
POST /api/products/variants?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 Response

{
    "sku": "9021182-XS",
    "stock_level": "5",
    "prices": [
        {
            "currency": "GBP",
            "price": "790",
            "quantity": 1
        }
    ],
    "tax_group": "Taxable Product",
    "attributes": [
        {
            "group": {
                "name": "Size"
            },
            "name": "Extra Small",
            "tags": [
                {
                    "group": {
                        "name": "Size"
                    },
                    "name": "Extra Small"
                }
            ]
        }
    ],
    "stock_buffer": 0,
    "minimum_quantity": 1,
    "multiples_of": 1
}

← PREVIOUS
Variants
NEXT →
Update Variant Endpoint
Back to top