Managing product attributes
Before managing attributes for a physical product and its variants, learn what attributes are, how they're created, and when they're required.
In the Products API, a Product
may define attributes for its ProductVariant
subresources in the Product.variantAttributes
field.
The order they’re specified in determines how attributes are displayed in the Squarespace product editor and product details page.
(See "Examples" > "Reorder attributes" for more information.)
{
// ...
"variantAttributes": ["Color", "Size"],
// ...
}
The following specifications always apply with regard to attributes:
1. A request to create or update a Product
has at most six attributes and no duplicate attributes.
{
// ...
"variantAttributes": ["Color", "Size", "Material", "Style", "Season", "Year"],
// ...
}
2. Attributes between a Product
and its ProductVariants
always match.
{
// ...
"variantAttributes": ["Color", "Size"],
// List of ProductVariant subresources
"variants": [{
// ...
"attributes": {
"Color": "Red",
"Size": "Small"
}
}, {
// ...
"attributes": {
"Color": "Yellow",
"Size": "Large"
}
}
}
3. Each ProductVariant
of a Product
has a unique set of attribute values.
{
// ...
"variantAttributes": ["Color", "Size"],
// List of ProductVariant subresources
"variants": [{
// ...
"attributes": {
"Color": "Red",
"Size": "Small"
}
}, {
// ...
"attributes": {
"Color": "Red",
"Size": "Large"
}
}
}
For every request that affects either the Products
or ProductVariant
resources,
the Products API validates variantAttributes
and attributes
to the specifications above.
Adding, updating, or deleting attributes and their values
Before modifying attributes, use the endpoints below to retrieve existing attributes for the product.
This is because a request body with variantAttributes
always updates the product with the specified attributes.
Existing attributes that are not specified in variantAttributes
are deleted from the product.
Add or update attributes
Use the endpoint sequence below when adding or updating attributes. See "Examples" for further details.
- Update a product
Products
with more than six attributes can be updated, but some attributes need to be unspecified for a successful request. This is because update requests withvariantAttributes
cannot list more than six attributes. IfvariantAttributes
specifies new attributes, then a successful request adds the new attributes to eachProduct.variants.attributes
automatically. Each variant uses placeholders values for the new attributes until the variant is updated with correct values.
- Update a product variant
Call the endpoint to update attribute values for each variant of the parentProduct
. The endpoint doesn’t support batch updates.
Create or update attribute values for a variant
Use either of the endpoints below.
The ProductVariant
in the request body must specify all existing attributes defined by the Product
,
even if the Product
has more than six attributes.
Delete attributes
A request with Product.variantAttributes
always updates the product with the specified attributes.
Existing attributes that are not specified in variantAttributes
are deleted from the product.
A successful request deletes unspecified attributes from the product and its variants.
Reorder attributes
Attributes are always displayed on the merchant site in the order listed by Product.variantAttributes
.
A successful request reorders attributes for the product and its variants in the Squarespace UI only,
not in the Product
resource.
Examples
Add a new attribute
Let’s say a Product
has the following attributes and variants:
{
// ...
"variantAttributes": ["Color"],
"variants": [{
// ...
"attributes": {
"Color": "Red"
}
}, {
// ...
"attributes": {
"Color": "Yellow"
}
}
}
To create a new attribute size
, first call the Update a product endpoint:
curl "https://api.squarespace.com/1.0/commerce/products/123" \
-i \
-H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
-H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
-H "Content-Type: application/json" \
-X POST \
-d '{'
# Note that the existing attribute "Color" is included in the request body.
# If not included, the "Color" attribute is deleted by the request.
'"variantAttributes": ["Color", "Size"],' \
'}'
The Product
now looks like this:
{
// ...
"variantAttributes": ["Color", "Size"],
"variants": [{
// ...
"attributes": {
"Color": "Red",
"Size": "Value1"
}
}, {
// …
"attributes": {
"Color": "Yellow",
"Size": "Value2"
}
}
}
Next, call the Update a product variant endpoint on each variant to set values for the new attribute.
curl "https://api.squarespace.com/1.0/commerce/products/123/variants/{variants[0].id}" \
-i \
-H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
-H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
-H "Content-Type: application/json" \
-X POST \
-d '{'
'"attributes" : {' \
# Any existing attributes not specified will be deleted,
# along with their values.
'"Color": "Red",' \
'"Size": "Small"' \
'}' \
'}'
After the first call, the Product
now looks like this:
{
// ...
"variantAttributes": ["Color", "Size"],
"variants": [{
// ...
"attributes": {
"Color": "Red",
"Size": "Small"
}
}, {
// ...
"attributes": {
"Color": "Yellow",
"Size": "Value2"
}
}
}
To update the second ProductVariant
, another request to Update a product variant needs to be made.
Reorder attributes
Let’s say a Product
has the following attributes and variants:
{
// ...
"variantAttributes": ["Color", "Size"],
"variants": [{
// ...
"attributes": {
"Color": "Red",
"Size": "Small"
}
}, {
// ...
"attributes": {
"Color": "Yellow",
"Size": "Large"
}
}
}
The information above is displayed like this in the Squarespace product editor:
And the product details page:
To reorder the attributes, call the Update a product endpoint:
curl "https://api.squarespace.com/1.0/commerce/products/123" \
-i \
-H "Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN" \
-H "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"
-H "Content-Type: application/json" \
-X POST \
-d '{'
# Any existing attributes must be specified in the request;
# if not, attributes are deleted.
'"variantAttributes": ["Size", "Color"],' \
'}'
The changes are reflected both in the product editor and product details page: