Overview Authentication and permissions Making requests Retrieve basic site information

Idempotency-Key header Rate limits Responses & error handling Upgrade Changelog Glossary FAQ

Overview GET: Retrieve all inventory GET: Retrieve specific inventory POST: Adjust stock quantities

Overview POST: Create an order POST: Fulfill an order GET: Retrieve all orders GET: Retrieve a specific order

Overview About product attributes Managing attributes POST: Create a product POST: Create a product variant POST: Upload a product image GET: Retrieve all Store Pages GET: Retrieve all products GET: Retrieve specific products GET: Product image upload status POST: Assign a product image to variant POST: Reorder a product image POST: Update a product POST: Update a product variant POST: Update a product image DEL: Delete a product DEL: Delete a product variant DEL: Delete a product image

Overview GET: Retrieve all profiles GET: Retrieve specific profiles

Overview GET: Retrieve all transactions GET: Retrieve specific transactions

Overview POST: Create a webhook subscription POST: Update a webhook subscription GET: Retrieve all webhook subscriptions GET: Retrieve a specific webhook subscription DEL: Delete a webhook subscription POST: Send test notification POST: Rotate a subscription secret

Products API overview

Current version: v2 (Beta) | Legacy versions: v1.1, v1.0

For versioning details, read the Upgrade guide.

Use the Products API to manage product information on a Squarespace merchant site, including variants of a product and product images. This API allows products to be retrieved, added, deleted, or modified with information such as a name or URL slug, a variant's color, size, or weight, or a new product image.

API Versions

v2 (Beta) - The latest version of the Products API with enhanced product type support. v2 endpoints support physical, service, gift card, and download products for most operations. Note: Download products cannot be created or deleted via v2 API.

v1.1, v1.0 (Legacy) - The stable versions of the Products API. v1.0 and v1.1 endpoints will continue to be supported, but we recommend using v2 for new integrations.

What information isn't available?

Categories used by a Store Page to group products

Product visibility for purchase

Read the How Squarespace organizes products knowledge base article to better understand how merchants organize and display products on their site.

In general, a Store Page is a collection of products, and every product details page is a child page of a Store Page. Consequently, a product details page may not belong to more than one Store Page.

Characteristics of Store Pages and product details pages directly impacts if a product is visible for purchase. A product is unavailable for purchase if a product’s Store Page is "Disabled" and/or if the status on a product details page is "Hidden". How a merchant configures their site navigation for visitors (i.e., "Not linking" the Store Page, grouping products under a category etc.) has no effect on product visibility for purchases.

Characteristics

Enabled or disabled page setting
Squarespace UI > Pages > any Store Page > gear icon > Store Settings editor > General

A newly added Store Page in the Squarespace UI is enabled by default. Enabled Store Pages are immediately available on the merchant site and can be indexed by search engines. A disabled Store Page can’t be accessed by site visitors. This applies to all product details pages within the Store Page.

Status on the product details page
Squarespace UI > Pages > any Store Page > any product card > product editor
OR
Squarespace UI > Commerce > Inventory > any product row > product editor

Each product has a "Visible" or "Hidden" status, where "Hidden" makes a product details page unavailable to customers while browsing products on a Store Page or via its direct URL.

API resources

The Products API is responsible for the resources below. All resource fields are described under Response example in the listed endpoints.

Store pages

StorePage represents information for a Store Page on a merchant site. Each Product on a merchant site belongs to a single StorePage.

Retrieve all Store Pages

Products

Product represents information for a product on a merchant site. Product information always includes name, description, type, URL, SEO options, tags and whether the product is visible for purchase. A Product may include up to 100 ProductImage subresources as well. A Product without a ProductImage is still a valid Product.

v2 Product Types (Beta)

v2 endpoints support four product types:

Physical Products - Tangible goods that require shipping or pick up
Service Products - Services or experiences offered by the merchant
Gift Card Products - Digital gift cards for the merchant site
Download Products - Digital files that customers can download

Physical Products

Physical product information always includes at least one ProductVariant subresource. It can also include attributes, if used for multiple variants. Physical products can have multiple variants (e.g., different sizes, colors) and can be accessed and modified in v1.0, v1.1, and v2.

Service Products (v2 Beta)

Service products represent services or experiences offered by the merchant, such as consulting, coaching, camps, retreats, or group trips. Service products can have multiple variants (e.g., different service tiers, durations) and can be accessed and modified in v2 only.

Gift Card Products (v2 Beta)

Gift card products represent digital gift cards for the merchant site. Gift card products can have multiple variants (e.g., different denominations) and can be created, accessed, and modified in v2 only.

Download Products

Download product information can include at most one DigitalGood subresource. Though typically a DigitalGood will be included, it is possible for a download product to not include one due to the product being improperly created or edited. Download products cannot have variants. In v2, download products can be accessed and modified, but not created nor deleted. In v1.1, download products can only be accessed. In v1.0, download products cannot be accessed.

Product variants

ProductVariant represents information for a variant of a product on a merchant site. Each variant contains information like a unique SKU, pricing, stock quantity, product dimensions, values for product attributes (if listed), etc.

Product types that support variants:

Physical Products - Can have multiple variants (e.g., different sizes, colors)
Service Products - Can have multiple variants (e.g., different service tiers, durations)
Gift Card Products - Can have multiple variants (e.g., different denominations)

Product types that do NOT support variants:

Download Products - Cannot have variants

Service and gift card variants are supported in v2 only. Physical variants are supported in v1.0, v1.1, and v2.

Product images

ProductImage represents information for an image in a product's collection of images. If desired, a ProductImage can be assigned to any ProductVariant of a Product — even if it's the same ProductImage. However, a ProductVariant can reference one ProductImage at most. Product images are supported in v1.0, v1.1, and v2.

Digital goods

DigitalGood represents information for the purchasable file of the product. A DigitalGood can not yet be accessed or modified separately from the owning Product. Digital goods are supported in both v1.1 and v2.