Update a product

POST https://api.squarespace.com/{api-version}/commerce/products/{id}

Updates information for a product.

v2 Support: The v2 API supports updating physical, service, gift card, and download products. The v1.0 and v1.1 APIs only support updating physical products.

Note: Adding or removing an image from a product or updating a product’s variants cannot be done through this endpoint. See the "Related endpoints" section to learn how to add or remove images, or update a variant.

A successful request returns the updated Product resource. Read the Overview to learn more about Products.

Parameters

If needed, see the "Related endpoints" section to learn how to retrieve a resource id.

{api-version} string
required

See the Products API Overview page for the current API version.

{id} string
required

Specifies the Product to update.

Request examples

Read the Making requests guide to learn why specific headers are necessary, and why some are omitted. Every request should also abide by Squarespace rate limits.

Note: The endpoint supports partial updates so any field marked as "Optional" or "Conditional" may be omitted from the request.

Updating a Physical Product

curl "https://api.squarespace.com/{api-version}/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 '{'
  # Optional; string, 200 char limit. Product name.
  '"name": "Artisanal Steak Dry Rub",' \
  # Optional; string, 102,400 char limit.
  # Long-form product description represented in HTML.
  # Value must be a simple snippet, so common block and formatting elements,
  # links, and certain safe CSS properties in the `style` attribute are allowed.
  '"description": "This can be a few words or even a few paragraphs.",' \
  # Optional; string, 200 char limit. URL slug for the new product.
  # Value can only consist of alphanumeric characters and non-contiguous hyphens.
  # The slug must also be unique among the products of a Store Page (formerly Products  Page).
  # Slugs are automatically downcased for the new product.
  '"urlSlug": "artisanal-steak-dry-rub",' \
  # Optional; array of strings, 100 char limit per string and no more than 100 strings.
  # Keywords for search and organization purposes.
  # Strings are not case-sensitive, so the string "steak"
  # allows both "steak" and "Steak" to be searched on a site.
  '"tags": ["artisanal", "steak"],' \
  # Optional; boolean.
  # Indicates whether the product is available for purchase.
  # If `true`, the product is listed as ‘Visible` in the Squarespace UI’s product editor;
  # if `false` the product is marked as `Hidden`.
  # If not specified, then the new product is marked as `Hidden`.
  '"isVisible": true,' \
  # Conditional; array of case-sensitive strings,
  # 100 char limit per string with no more than six strings.
  # A `null` array is not allowed else the request fails.
  # List of attributes to distinguish variants of the product.
  # Supported for PHYSICAL and SERVICE products only.
  # Read the guide below for request validations between this field and the product's variants.
  # https://developers.squarespace.com/commerce-apis/managing-attributes
  '"variantAttributes": ["Flavor"],' \
  # Optional; object.
  # Options for search engine optimization.
  '"seoOptions": {' \
    # Optional; string, 100 char limit.
    # Page title that appears in search results and browser tabs;
    # indexed by search engines
    '"title": "Artisanal Cooking",' \
    # Optional; string, 400 char limit.
    # Page description that appears below the title or link in search results.
    '"description": "A one-stop shop for artisanal cooking tips and products."' \
  '}' \
'}' \

Updating a Digital Product

curl "https://api.squarespace.com/{api-version}/commerce/products/456" \
  -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 '{'
  # Optional; string, 200 char limit. Product name.
  '"name": "The Artisan’s Cookbook (eBook)",' \
  # Optional; string, 102,400 char limit.
  # Long-form product description represented in HTML.
  # Value must be a simple snippet, so common block and formatting elements,
  # links, and certain safe CSS properties in the `style` attribute are allowed.
  '"description": "This can be a few words or even a few paragraphs.",' \
  # Optional; string, 200 char limit. URL slug for the new product.
  # Value can only consist of alphanumeric characters and non-contiguous hyphens.
  # The slug must also be unique among the products of a Store Page (formerly Products  Page).
  # Slugs are automatically downcased for the new product.
  '"urlSlug": "the-artisans-cookbook-ebook",' \
  # Optional; array of strings, 100 char limit per string and no more than 100 strings.
  # Keywords for search and organization purposes.
  # Strings are not case-sensitive, so the string "steak"
  # allows both "steak" and "Steak" to be searched on a site.
  '"tags": ["artisanal", "cookbook", "ebook"],' \
  # Optional; boolean.
  # Indicates whether the product is available for purchase.
  # If `true`, the product is listed as 'Visible' in the Squarespace UI's product editor;
  # if `false` the product is marked as `Hidden`.
  # If not specified, then the new product is marked as `Hidden`.
  '"isVisible": true,' \
  # Optional; object.
  # Options for search engine optimization.
  '"seoOptions": {' \
    # Optional; string, 100 char limit.
    # Page title that appears in search results and browser tabs;
    # indexed by search engines
    '"title": "Artisanal Cooking",' \
    # Optional; string, 400 char limit.
    # Page description that appears below the title or link in search results.
    '"description": "A one-stop shop for artisanal cooking tips and products."' \
  '},' \
  # Optional; object. Pricing data for the digital product.
  # Digital products have pricing at the product level since they don't have variants.
  '"pricing": {' \
    # Optional; object. Amount per unit to charge for the product.
    '"basePrice": {' \
      # Required; ISO 4217 currency code string.
      '"currency": "USD",' \
      # Required; string. Monetary amount.
      # Amount has no currency markers and conforms to the selected
      # ISO currency's precision (e.g., JPY as 123; USD as 123.00 or 123).
      # Amount must not be more than 1,000,000.
      '"value": "3.99"' \
    '},' \
    # Optional; boolean.
    # Indicates whether the product is sold according to its sale price.
    # If not specified, then the field defaults to `false` and the product is not on sale.
    '"onSale": true,' \
    # Optional; money object. Amount per unit charged when the product is on sale.
    # If `onSale` is `false`, the field is not required.
    # If `onSale` is `true` then all salePrice fields are required.
    '"salePrice": {' \
      # Required; ISO 4217 currency code string.
      # If `onSale` is false; field defaults to the merchant site's currency setting.
      '"currency": "USD",' \
      # Required; string. Monetary amount.
      # Amount has no currency markers and conforms to the selected
      # ISO currency's precision (e.g., JPY as 123; USD as 123.00 or 123).
      # Amount must not be more than 1,000,000.
      # If `onSale` is false, field coalesces to the lesser of this and `basePrice.value`.
      '"value": "2.99"' \
    '}' \
  '}' \
'}' \

Note: Updating a digital good (the downloadable file) is not allowed through this endpoint. The digitalGood field cannot be modified via API at this time.

Response examples

A response to a successful request will contain the updated Product. The examples below show the response structure for different product types.

Physical Product Response

{
  // Unique Product id.
  "id": "5ed539b66505ca7c5f4a3a5a",
  // Product type indicator.
  // Value may be: `PHYSICAL`, `SERVICE`, `GIFT_CARD`, or `DIGITAL`.
  "type": "PHYSICAL",
  // Identifier of the product's Store Page.
  "storePageId": "5d7ba084a63ee8bb410ce0b1",
  // Product name.
  "name": "Artisanal Steak Dry Rub",
  // Long-form product description represented in HTML.
  "description": "<p>This can be a few words or even a few <i>paragraphs</i>.</p>",
  // Absolute URL of the product details page.
  "url": "https://example.com/store/artisanal-steak-dry-rub",
  // URL slug for the new product.
  "urlSlug": "artisanal-steak-dry-rub",
  // Keywords for search and organization purposes.
  "tags": ["artisanal", "steak"],
  // Indicates whether the Product is available for purchase.
  "isVisible": true,
  // Options for search engine optimization.
  "seoOptions": {
    // Page title that appears in search results and browser tabs;
    // indexed by search engines.
    "title": "Artisanal Cooking",
    // Page description that appears below the title or link in search results.
    "description": "A one-stop shop for artisanal cooking tips and products."
  },
  // List of attributes to distinguish variants of the product.
  // Present for PHYSICAL and SERVICE products only.
  "variantAttributes": ["Flavor"],
  // List of variants of the product.
  // Present for PHYSICAL, SERVICE, and GIFT_CARD products only.
  "variants": [{
    // Unique ProductVariant id.
    "id": "6b76dad2-a15a-4dfc-97e1-47427e12061f",
    // Merchant-defined code that identifies the product variant.
    "sku": "SQ0557856",
    // Pricing data for the variant.
    "pricing": {
      // Amount per unit charged for the variant.
      "basePrice": {
        // ISO 4217 currency code string.
        "currency": "USD",
        // Monetary amount.
        "value": "12.95"
      },
      // Amount per unit charged when the variant is on sale.
      // Present for PHYSICAL and SERVICE products only.
      "salePrice": {
        // ISO 4217 currency code string.
        // If `onSale` is false; field defaults to the merchant site's currency setting.
        "currency": "USD",
        // Monetary amount.
        // If `onSale` is false, field coalesces to the lesser of this and `basePrice.value`.
        "value": "0.00"
      },
      // Indicates whether the variant is sold according to its sale price.
      // Present for PHYSICAL and SERVICE products only.
      "onSale": false
    },
    // Available stock for the variant.
    // Present for PHYSICAL and SERVICE products only.
    "stock": {
      // Number of units that can be purchased.
      "quantity": 10,
      // Indicates whether the variant has unlimited stock.
      "unlimited": false
    },
    // Specifies attribute-value pairs for the variant.
    // Present for PHYSICAL and SERVICE products only.
    "attributes": {
      "Flavor": "Habanero"
    },
    // Measurements of the variant when it's shipped.
    // Present for PHYSICAL products only.
    "shippingMeasurements": {
      // Weight of the variant.
      "weight": {
        // Unit of measurement.
        // Supported values: `KILOGRAM`, `POUND`.
        "unit": "POUND",
        // Weight amount.
        "value": 2.0
      },
      // Physical dimensions of the variant.
      "dimensions": {
        // Unit of measurement.
        // Supported values: `INCH`, `CENTIMETER`.
        "unit": "INCH",
        // Length of the variant.
        "length": 7.0,
        // Width of the variant.
        "width": 5.0,
        // Height of the variant.
        "height": 5.0
      }
    },
    // Product image assigned to the variant.
    // See `images` for field descriptions."
    "image": {
      "id": "5ed539bc8367410cdc0c984a",
      "title": "Steak",
      "url": "https://static1.squarespace.com/static/steak.png",
      "originalSize": {
        "width": 512,
        "height": 256
      },
      "availableFormats": ["100w", "300w", "500w"]
    }
  }],
  // List of product images.
  "images": [{
    // Unique ProductImage id.
    "id": "5ed539bc8367410cdc0c984a",
    // Alt text for the image; impacts SEO and appears in search results.
    "altText": "Steak",
    // Absolute URL of the image hosted on Squarespace.
    "url": "https://static1.squarespace.com/static/steak.png",
    // Image size when first uploaded.
    "originalSize": {
      // Width in pixels.
      "width": 512,
      // Height in pixels.
      "height": 256
    },
    // Available image sizes. Use with `images.url` and a `format` query parameter
    // to retrieve the image at a particular width.
    // E.g., https://static1.squarespace.com/static/steak.png?format=300w
    "availableFormats": ["100w", "300w", "500w"]
  }],
  // ISO 8601 UTC date and time string; represents when the Product was created.
  "createdOn": "2020-06-01T17:24:06.048Z",
  // ISO 8601 UTC date and time string; represents when the Product was last modified.
  "modifiedOn": "2020-06-04T20:12:18.163Z"
}

Digital Product Response

{
  // Unique Product id.
  "id": "5ff738b49506ca7c5g1b3c4a",
  // Product type indicator.
  // Value may be: `PHYSICAL`, `SERVICE`, `GIFT_CARD`, or `DIGITAL`.
  "type": "DIGITAL",
  // Identifier of the product's Store Page.
  "storePageId": "5d7ba084a63ee8bb410ce0b1",
  // Product name.
  "name": "The Artisan's Cookbook (eBook)",
  // Long-form product description represented in HTML.
  "description": "<p>This can be a few words or even a few <i>paragraphs</i>.</p>",
  // Absolute URL of the product details page.
  "url": "https://example.com/store/the-artisans-cookbok-ebook",
  // URL slug for the new product.
  "urlSlug": "the-artisans-cookbook-ebook",
  // Keywords for search and organization purposes.
  "tags": ["artisanal", "cookbook", "ebook"],
  // Indicates whether the Product is available for purchase.
  "isVisible": true,
  // Options for search engine optimization.
  "seoOptions": {
    // Page title that appears in search results and browser tabs;
    // indexed by search engines.
    "title": "Artisanal Cooking",
    // Page description that appears below the title or link in search results.
    "description": "A one-stop shop for artisanal cooking tips and products."
  },
  // List of product images.
  "images": [{
    // Unique ProductImage id.
    "id": "60e359bd8467521dff3e993b",
    // Alt text for the image; impacts SEO and appears in search results.
    "altText": "Cover",
    // Absolute URL of the image hosted on Squarespace.
    "url": "https://static1.squarespace.com/static/cookbook-cover.png",
    // Image size when first uploaded.
    "originalSize": {
      // Width in pixels.
      "width": 512,
      // Height in pixels.
      "height": 256
    },
    // Available image sizes. Use with `images.url` and a `format` query parameter
    // to retrieve the image at a particular width.
    // E.g., https://static1.squarespace.com/static/cookbook-cover.png?format=300w
    "availableFormats": ["100w", "300w", "500w"]
  }],
  // Present for DIGITAL products only.
  // Digital products don't have variants, so pricing is at the product level.
  "pricing": {
    // Amount per unit charged for the product.
    "basePrice": {
      // ISO 4217 currency code string.
      "currency": "USD",
      // Monetary amount.
      "value": "4.95"
    },
    // Amount per unit charged when the product is on sale.
    // Present for DIGITAL products only.
    "salePrice": {
      // ISO 4217 currency code string.
      // If `onSale` is false; field defaults to the merchant site's currency setting.
      "currency": "USD",
      // Monetary amount.
      // If `onSale` is false, field coalesces to the lesser of this and `basePrice.value`.
      "value": "2.95"
    },
    // Indicates whether the product is sold according to its sale price.
    // Present for DIGITAL products only.
    "onSale": true
  },
  // Present for DIGITAL products only.
  "digitalGood": {
    // Unique DigitalGood id.
    "id": "643bc32ffb58f41fb9f611a8",
    // Filename of the downloadable file.
    "filename": "cookbook.pdf"
  },
  // ISO 8601 UTC date and time string; represents when the Product was created.
  "createdOn": "2020-07-02T18:33:46.657Z",
  // ISO 8601 UTC date and time string; represents when the Product was last modified.
  "modifiedOn": "2020-08-04T10:42:29.269Z"
}

Status codes and error conditions

200 OK

The request was successful. The message body contains data in the format specified above.

400 BAD REQUEST

Type: INVALID_REQUEST_ERROR

Subtype: null
The request body does not conform to the required specification.

404 NOT FOUND

Type: INVALID_REQUEST_ERROR

Subtype: INVALID_ARGUMENT
The requested Product was not found.

405 METHOD NOT ALLOWED

Type: METHOD_NOT_ALLOWED

Subtype: OPERATION_NOT_ALLOWED_FOR_PRODUCT_TYPE
The Product requested is not a supported product type for this operation.

409 CONFLICT

Type: CONFLICT

Subtype: URL_SLUG_IN_USE
The provided URL slug is already in use.

Related endpoints

Ids
To retrieve ids for Products, the retrieve all products endpoint is suggested, though other Products API endpoints may be used.

Images
To modify a product’s collection of images, use the upload a product image and delete a product image endpoints.

Variants
Modify variants of a product using any of the following:

• Create a product variant
• Update a product variant
• Delete a product variant