Update a product variant

POST https://api.squarespace.com/{api-version}/commerce/products/{productId}/variants/{variantId}

Updates a variant of a physical product.

Note: Images and stock quantity can’t be updated by this endpoint. See the "Related endpoints" section to learn how to update an image or adjust stock.

A successful request returns the updated ProductVariant resource. Read the Overview to learn more about this resource.

Parameters

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

{api-version} string
required

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

{productId} string
required

Specifies the Product that owns the ProductVariant to update.

{variantId} string
required

Specifies the ProductVariant to update.

Request example

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; any field marked as "Optional" or "Conditional" omitted from the request will not be modified.

curl "https://api.squarespace.com/1.0/commerce/products/123/variants/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, 60 char limit, `null` not allowed.
  # Merchant-defined code that identifies the product variant.
  # Value must be unique among variants[]. Leading and trailing whitespace is removed.
  '"sku": "SQ2826308",' \
  # Optional; object, `null` not allowed.
  # Pricing data for the variant.
  '"pricing": {' \
    # Optional; object, `null` not allowed.
    # Amount per unit to charge for the variant.
    '"basePrice": {' \
      # Required; ISO 4217 currency code string.
      '"currency": "USD",' \
      # Required; string.
      # Monetary amount; not more than 1,000,000.
      # 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).
      '"value": "22.95"' \
    '},' \
    # Conditional; money object.
    # Amount per unit charged when the variant 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; not more than 1,000,000.
      # 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).
      # If `onSale` is false, field coalesces to the lesser of this and `basePrice.value`.
      '"value": "17.99"' \
    '},' \
    # Optional; boolean, `null` allowed.
    # Indicates whether the variant is sold according to its sale price.
    # If not specified, then the field defaults to `false` and the variant is not on sale.
    '"onSale": true' \
  '},' \
  # Optional; object of key-value pairs,
  # 100 char limit per key and per value with no more than six key-value pairs.
  # Specifies attribute-value pairs for the variant.
  # Read the guide below to learn about request validations
  # between this field and the product's attributes.
  # https://developers.squarespace.com/commerce-apis/manage-attributes
  '"attributes" : {' \
    '"Flavor": "Buffalo"' \
  '},' \
  # Optional; object.
  # Measurements of the variant when it’s shipped.
  # Values are used for calculating shipping costs at checkout.
  '"shippingMeasurements": {' \
    # Optional; object.
    # Weight of the variant.
    # If not specified, then the new variant uses the default
    # values described below. Otherwise, all weight fields are required.
    '"weight": {' \
      # Required; string.
      # Unit of measurement. Supported values: `KILOGRAM`, `POUND`,
      # but it must be based on the merchant site’s
      # measurement standard (e.g. use `KILOGRAM` for the metric system).
      # To retrieve the measurement standard, visit the FAQ link and scroll to
      # ‘How can I determine the Squarespace site that owns a particular API key or OAuth token?`
      # https://developers.squarespace.com/commerce-apis/faq
      '"unit": "POUND",' \
      # Required; decimal.
      # Weight amount; less than 10,000 and rounded to the nearest ten thousandth.
      # If not specified, then value defaults to 0.0 for the product variant.
      '"value": 11.0' \
    '},' \
    # Optional; object.
    # Physical dimensions of the variant.
    # If not specified, then the new variant ses the default values described below.
    # Otherwise, all dimensions fields are required and each decimal field
    # must be less than 10,000 and rounded to the nearest ten thousandth.
    '"dimensions": {' \
      # Required; string.
      # Unit of measurement. Supported values: `CENTIMETER`, `INCH`,
      # but it must be based on the merchant site’s
      # measurement standard (e.g. use `CENTIMETER` for the metric system).
      # To retrieve the measurement standard, visit the FAQ link and scroll to:
      # "How can I determine the Squarespace site that owns a particular API key or OAuth token?"
      # https://developers.squarespace.com/commerce-apis/faq
      '"unit": "INCH",' \
      # Required; decimal.
      # Length of the variant; defaults to 0.0.
      '"length": 12.0,' \
      # Required; decimal.
      # Width of the variant; defaults to 0.0.
      '"width": 11.5,' \
      # Required; decimal.
      # Height of the variant; defaults to 0.0.
      '"height": 10.5' \
    '}' \
  '}' \
'}' \

Response example

A response to a successful request will contain the updated ProductVariant.

{
  // Unique ProductVariant id.
  "id": "6b76dad2-a15a-4dfc-97e1-47427e12061f",
  // Merchant-defined code that identifies the product variant.
  "sku": "SQ2826308",
  // Pricing data for the variant.
  "pricing": {
    // Amount per unit charged for the variant.
    "basePrice": {
      // ISO 4217 currency code string.
      "currency": "USD",
      // Monetary amount.
      "value": "22.95"
    },
    // Amount per unit charged when the variant is on sale.
    "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": "17.99"
    },
    // Indicates whether the variant is sold according to its sale price.
    "onSale": true
  },
  // Available stock for the variant.
  "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.
  "attributes": {
    "Flavor": "Buffalo"
  },
  // Measurements of the variant when it's shipped.
  "shippingMeasurements": {
    // Weight of the variant.
    "weight": {
      // Unit of measurement.
      // Supported values: `KILOGRAM`, `POUND`.
      "unit": "POUND",
      // Weight amount.
      "value": 11.0
    },
    // Physical dimensions of the variant.
    "dimensions": {
      // Unit of measurement.
      // Supported values: `INCH`, `CENTIMETER`.
      "unit": "INCH",
      // Length of the variant.
      "length": 12.0,
      // Width of the variant.
      "width": 11.5,
      // Height of the variant.
      "height": 10.5
    }
  },
  // Product image assigned to the variant.
  "image": {
    // 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"]
  }
}

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
Either the Product or the ProductVariant was not found.

405 METHOD NOT ALLOWED

Type: METHOD_NOT_ALLOWED

Subtype: OPERATION_NOT_ALLOWED_FOR_PRODUCT_TYPE
The Product requested is not a physical Product.

409 CONFLICT

Type: CONFLICT

Subtype: SKU_UNAVAILABLE
The provided SKU is already in use by the requested Product.

Related endpoints

Ids
To retrieve an id for a Product or its ProductVariants, use these suggested endpoints:

• Retrieve all products
• Retrieve specific products

Update stock
Use the adjust stock quantities endpoint from the Inventory API.

Images
Use the assign a product image to a variant endpoint.