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.

• Retrieve all products
• Retrieve specific products

Add or update attributes

Use the endpoint sequence below when adding or updating attributes. See "Examples" for further details.

1. 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 with variantAttributes cannot list more than six attributes. If variantAttributes specifies new attributes, then a successful request adds the new attributes to each Product.variants.attributes automatically. Each variant uses placeholders values for the new attributes until the variant is updated with correct values.

2. Update a product variant
   Call the endpoint to update attribute values for each variant of the parent Product. 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.

• Create a product variant
• Update a product variant

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.

• Update a product

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.

• Update a product

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: