Squarespace Developer Platform: APIs, Apps, and Docs
Commerce API

List products

GET
https://api.squarespace.com
/v2/commerce/products

Retrieves information for products; products can be filtered within a date range and by product type. The response contains product information in a Product, up to 50 Products ordered by their modification date (modifiedOn), and supports dynamic cursors for pagination.

List products › query Parameters

modifiedAfter
​string
modifiedBefore
​string
cursor
​string
query
​string
type
​string[]

List products › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

List products › Responses

A paginated list of products.

​object
​array

Create product

POST
https://api.squarespace.com
/v2/commerce/products

Creates a product with appropriate subresources based on product type.

Create product › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Create product › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
type = object
type = object
Properties for CreateGiftCardProductRequest:
Request payload to create a GIFT_CARD product.
description
​string
isVisible
​boolean
name
​string
storePageId
​string
tags
​string[]
type
​string
urlSlug
​string

Create product › Responses

The product was created successfully.

createdOn
​string · date-time · required
id
​string · required
modifiedOn
​string · date-time · required
storePageId
​string · required
type
​ProductTypeV2 · enum · required
Enum values:
PHYSICAL
SERVICE
GIFT_CARD
DIGITAL
description
​string
isVisible
​boolean
name
​string
​SeoOptions

Options for search engine optimization.

tags
​string[]
url
​string
urlSlug
​string

Get products

GET
https://api.squarespace.com
/v2/commerce/products/{productIdCsvs}

Retrieves information for specific products, including information for any variants or images. Up to 50 products can be retrieved per request.

Get products › path Parameters

productIdCsvs
​string · required

Get products › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Get products › Responses

The requested products.

​array

Update product

POST
https://api.squarespace.com
/v2/commerce/products/{productId}

Updates information for a product. The endpoint supports partial updates.

Update product › path Parameters

productId
​string · required

Update product › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Update product › Request Body

​ChangeString

Optional; HTTPS URL to receive webhook notifications.

​ChangeBoolean

Optional; HTTPS URL to receive webhook notifications.

Pricing data for the product.

​ChangeListString

Optional; list of event topics that trigger a webhook notification. Possible values include: extension.uninstall, order.create, order.update.

Options for search engine optimization.

Optional; list of event topics that trigger a webhook notification. Possible values include: extension.uninstall, order.create, order.update.

​ChangeString

Optional; HTTPS URL to receive webhook notifications.

Update product › Responses

Return the updated Product

createdOn
​string · date-time · required
id
​string · required
modifiedOn
​string · date-time · required
storePageId
​string · required
type
​ProductTypeV2 · enum · required
Enum values:
PHYSICAL
SERVICE
GIFT_CARD
DIGITAL
description
​string
isVisible
​boolean
name
​string
​SeoOptions

Options for search engine optimization.

tags
​string[]
url
​string
urlSlug
​string

Delete specified product

DELETE
https://api.squarespace.com
/v2/commerce/products/{productId}

Delete specified product

Delete specified product › path Parameters

productId
​string · required

Delete specified product › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Delete specified product › Responses

The Product was deleted successfully.

No data returned

Upload product image

POST
https://api.squarespace.com
/v2/commerce/products/{productId}/images

Uploads an image for a product. Uploading an image doesn't set the product's featured image. A successful request creates a ProductImage subresource of the Product.

Upload product image › path Parameters

productId
​string · required

Upload product image › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Upload product image › Responses

The request was accepted and the uploaded image is being processed.

imageId
​string

Unique ProductImage id.


Update product image

POST
https://api.squarespace.com
/v2/commerce/products/{productId}/images/{imageId}

Updates information for a product image. Currently, the endpoint only supports updates to the alt text for an image.

Update product image › path Parameters

productId
​string · required
imageId
​string · required

Update product image › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Update product image › Request Body

​ChangeString

Optional; HTTPS URL to receive webhook notifications.

Update product image › Responses

Return the updated ProductImage

Product image assigned to the variant.
altText
​string

Alt text for the image; impacts SEO and appears in search results.

availableFormats
​string[]

Available image sizes. Use with images.url and a format query parameter to retrieve the image at a particular width.

id
​string

Unique ProductImage id.

orderIndex
​integer · int32

Position of the image in the product's image list.

originalSize
​object

Image size when first uploaded.

url
​string

Absolute URL of the image hosted on Squarespace.


Delete one product image

DELETE
https://api.squarespace.com
/v2/commerce/products/{productId}/images/{imageId}

Delete one product image

Delete one product image › path Parameters

productId
​string · required
imageId
​string · required

Delete one product image › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Delete one product image › Responses

The ProductImage was deleted successfully.

No data returned

Update product image order

POST
https://api.squarespace.com
/v2/commerce/products/{productId}/images/{imageId}/order

Updates the ordering of a product image on the product details page.

Update product image order › path Parameters

productId
​string · required
imageId
​string · required

Update product image order › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Update product image order › Request Body

​ChangeString

Optional; HTTPS URL to receive webhook notifications.

Update product image order › Responses

The request was successful.

No data returned

Get image processing status

GET
https://api.squarespace.com
/v2/commerce/products/{productId}/images/{imageId}/status

Retrieves the processing status for an uploaded product image. A successful request indicates that a ProductImage is processing, ready, or in an error state.

Get image processing status › path Parameters

productId
​string · required
imageId
​string · required

Get image processing status › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Get image processing status › Responses

Return the processing status for the ProductImage

id
​string
status
​ImageProcessingStatus · enum
Enum values:
QUEUED
PROCESSING
READY
ERROR

Create product variant

POST
https://api.squarespace.com
/v2/commerce/products/{productId}/variants

Creates a variant of a product. Creating a variant for a physical or service product requires that the product already has at least one attribute.

Create product variant › path Parameters

productId
​string · required

Create product variant › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Create product variant › Request Body

​ProductPricing · required

Present for DIGITAL products only. Digital products don't have variants, so pricing is at the product level.

sku
​string · maxLength: 60 · required

Merchant-defined code that identifies the product variant. Value must be unique among variants. Leading and trailing whitespace is removed.

​object

Specifies attribute-value pairs for the variant. 100 char limit per key and per value with no more than six key-value pairs. Supported for PHYSICAL products only.

gtin
​string

Global Trade Item Number (GTIN). Optional. Must be 8, 12, 13, or 14 numeric digits. Whitespace, hyphens, and underscores are stripped before validation. Supported for PHYSICAL products only.

Example: 01234567890128
mpn
​string

Manufacturer Part Number (MPN). Optional. Must be alphanumeric and 70 characters or fewer. Whitespace, hyphens, and underscores are stripped before validation. Supported for PHYSICAL products only.

Example: MPN-1234
​ProductMeasurements

Measurements of the variant when it's shipped. Present for PHYSICAL products only.

​ProductStock

Available stock for the variant. Present for PHYSICAL products only.

Create product variant › Responses

The ProductVariant was created successfully.

A product variant. The shape depends on the product type.
id
​string
​ProductImage

Product image assigned to the variant.

sku
​string
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
type = object
type = object
Properties for PhysicalProductVariant:
A variant of a PHYSICAL product.
​object
gtin
​string
id
​string
​ProductImage

Product image assigned to the variant.

mpn
​string
​ProductMeasurements

Measurements of the variant when it's shipped. Present for PHYSICAL products only.

sku
​string
​ProductStock

Available stock for the variant. Present for PHYSICAL products only.


Update product variant

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

Updates a variant of a product. The endpoint supports partial updates.

Update product variant › path Parameters

productId
​string · required
variantId
​string · required

Update product variant › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Update product variant › Request Body

Specifies attribute-value pairs for the variant. Supported for PHYSICAL products only.

Optional; HTTPS URL to receive webhook notifications.

Optional; HTTPS URL to receive webhook notifications.

Pricing data for the product.

​ChangeUpdateProductMeasurements

Measurements of the variant when it's shipped. Supported for PHYSICAL products only.

Optional; HTTPS URL to receive webhook notifications.

Update product variant › Responses

Return the updated ProductVariant

A product variant. The shape depends on the product type.
id
​string
​ProductImage

Product image assigned to the variant.

sku
​string
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
type = object
type = object
Properties for PhysicalProductVariant:
A variant of a PHYSICAL product.
​object
gtin
​string
id
​string
​ProductImage

Product image assigned to the variant.

mpn
​string
​ProductMeasurements

Measurements of the variant when it's shipped. Present for PHYSICAL products only.

sku
​string
​ProductStock

Available stock for the variant. Present for PHYSICAL products only.


Delete one product variant

DELETE
https://api.squarespace.com
/v2/commerce/products/{productId}/variants/{variantId}

Delete one product variant

Delete one product variant › path Parameters

productId
​string · required
variantId
​string · required

Delete one product variant › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Delete one product variant › Responses

The ProductVariant was deleted successfully.

No data returned

Associate variant image

POST
https://api.squarespace.com
/v2/commerce/products/{productId}/variants/{variantId}/image

Assigns a product image to a product variant. Specifying imageId of null will delete the association.

Associate variant image › path Parameters

productId
​string · required
variantId
​string · required

Associate variant image › Headers

Authorization
​string · required

API key or OAuth access token

Default: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN
User-Agent
​string · required

User Agent

Default: YOUR_CUSTOM_APP_DESCRIPTION

Associate variant image › Request Body

​ChangeString · required

Optional; HTTPS URL to receive webhook notifications.

Associate variant image › Responses

The request was successful.

No data returned