The Squarespace Products API allows developers to manage the product catalog of a Squarespace merchant site. It supports physical products, service products, gift cards, and digital downloads, along with their images and variants.
openapi: 3.1.0
info:
title: Squarespace Products API
description: >-
The Squarespace Products API allows developers to manage the product catalog
of a Squarespace merchant site. It supports physical products, service products,
gift cards, and digital downloads, along with their images and variants.
Developers can create, update, retrieve, and delete products programmatically,
enabling catalog synchronization with external systems. The API is well-suited
for building product import tools, headless commerce integrations, or multi-channel
retail management applications.
version: '1.0'
contact:
name: Squarespace Developer Support
url: https://developers.squarespace.com/commerce-apis/products-overview
termsOfService: https://www.squarespace.com/terms-of-service
externalDocs:
description: Squarespace Products API Documentation
url: https://developers.squarespace.com/commerce-apis/products-overview
servers:
- url: https://api.squarespace.com/1.0
description: Production Server
tags:
- name: Products
description: Product catalog management including variants and images
security:
- bearerAuth: []
paths:
/commerce/products:
get:
operationId: listProducts
summary: Retrieve All Products
description: >-
Returns a paginated list of products in the merchant's catalog. By default
returns up to 50 products per page. Use the cursor parameter from the
previous response's pagination.nextPageCursor to retrieve subsequent pages.
Each product includes its basic metadata, variant information, and associated
images.
tags:
- Products
parameters:
- $ref: '#/components/parameters/cursor'
- name: type
in: query
description: Filter products by product type
required: false
schema:
type: string
enum:
- PHYSICAL
- DIGITAL
- SERVICE
- GIFT_CARD
responses:
'200':
description: Successful response with paginated list of products
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createProduct
summary: Create a Product
description: >-
Creates a new product in the merchant's catalog with appropriate subresources
based on product type. Supports creation of physical, service, gift card,
and digital download products. The request must include the product type,
name, and at least one variant. Images can be added after the product is
created using the product image endpoints.
tags:
- Products
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProductRequest'
responses:
'200':
description: Product created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/products/{productIds}:
get:
operationId: getProducts
summary: Retrieve Specific Products
description: >-
Retrieves detailed information for up to 50 specific products by their
product IDs. Product IDs should be provided as a comma-separated list
in the path. Returns full product data including all variants and images.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productIds'
responses:
'200':
description: Successful response with the requested products
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: updateProduct
summary: Update a Product
description: >-
Updates information for an existing product. The endpoint supports partial
updates so any optional or conditional field may be omitted from the request.
Only the fields provided in the request body will be updated. This endpoint
accepts a single product ID in the path when updating.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productIds'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProductRequest'
responses:
'200':
description: Product updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteProduct
summary: Delete a Product
description: >-
Deletes a physical product and all its associated variants and images from
the merchant's catalog. This action is permanent and cannot be undone.
Accepts a single product ID in the path.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productIds'
responses:
'204':
description: Product deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/products/{productId}/variants:
post:
operationId: createProductVariant
summary: Create a Product Variant
description: >-
Adds a new variant to an existing product. A variant represents a specific
configuration of a product, such as a particular size and color combination.
Each variant has its own SKU, price, and inventory tracking settings.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVariantRequest'
responses:
'200':
description: Product variant created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariant'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/products/{productId}/variants/{variantId}:
post:
operationId: updateProductVariant
summary: Update a Product Variant
description: >-
Updates attributes for an existing product variant such as price, SKU,
stock settings, and option values. Supports partial updates.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/variantId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateVariantRequest'
responses:
'200':
description: Product variant updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductVariant'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/products/{productId}/images:
post:
operationId: uploadProductImage
summary: Upload a Product Image
description: >-
Uploads a new image to a product using a publicly accessible image URL.
The image is fetched from the provided URL and stored by Squarespace.
An optional alt text can be provided for accessibility.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UploadImageRequest'
responses:
'200':
description: Product image uploaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductImage'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/products/{productId}/images/{imageId}:
post:
operationId: updateProductImage
summary: Update a Product Image
description: >-
Updates the alt text of an existing product image. The image itself
cannot be replaced; delete and re-upload to change the image file.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/imageId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateImageRequest'
responses:
'200':
description: Product image updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ProductImage'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteProductImage
summary: Delete a Product Image
description: >-
Permanently removes an image from a product. This action cannot be undone.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productId'
- $ref: '#/components/parameters/imageId'
responses:
'204':
description: Product image deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/products/{productId}/images/reorder:
post:
operationId: reorderProductImages
summary: Reorder Product Images
description: >-
Changes the display order of images for a product by providing an ordered
list of image IDs. The order of image IDs in the request determines the
display order, with the first image becoming the primary product image.
tags:
- Products
parameters:
- $ref: '#/components/parameters/productId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- imageIds
properties:
imageIds:
type: array
description: Ordered list of image IDs defining the new display order
items:
type: string
responses:
'200':
description: Product images reordered successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate using an API key or OAuth access token. Include the token
in the Authorization header as "Bearer YOUR_TOKEN".
responses:
BadRequest:
description: The request was malformed or contained invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication credentials are missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: The authenticated user does not have permission to access this resource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
cursor:
name: cursor
in: query
description: >-
Pagination cursor from a previous response's pagination.nextPageCursor field.
Omit or leave empty to retrieve the first page.
required: false
schema:
type: string
productIds:
name: productIds
in: path
description: >-
Comma-separated list of up to 50 product IDs. When used for single-product
operations, provide a single product ID.
required: true
schema:
type: string
productId:
name: productId
in: path
description: The unique identifier of the product
required: true
schema:
type: string
variantId:
name: variantId
in: path
description: The unique identifier of the product variant
required: true
schema:
type: string
imageId:
name: imageId
in: path
description: The unique identifier of the product image
required: true
schema:
type: string
schemas:
Product:
type: object
description: A product in the Squarespace merchant catalog
properties:
id:
type: string
description: Unique identifier for the product
type:
type: string
description: The product type determining available features and behaviors
enum:
- PHYSICAL
- DIGITAL
- SERVICE
- GIFT_CARD
storePageId:
type: string
description: Identifier of the store page where this product is listed
name:
type: string
description: Display name of the product shown to customers
description:
type: string
description: HTML description of the product
url:
type: string
format: uri
description: Relative URL path to the product page on the merchant site
urlSlug:
type: string
description: URL-friendly slug for the product page
tags:
type: array
description: List of tags associated with the product for organization
items:
type: string
isVisible:
type: boolean
description: Whether the product is visible to customers on the store
variants:
type: array
description: List of product variants with specific options, prices, and stock
items:
$ref: '#/components/schemas/ProductVariant'
images:
type: array
description: List of images associated with the product
items:
$ref: '#/components/schemas/ProductImage'
createdOn:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the product was created
modifiedOn:
type: string
format: date-time
description: ISO 8601 UTC timestamp when the product was last modified
CreateProductRequest:
type: object
description: Request body for creating a new product
required:
- type
- name
- variants
properties:
type:
type: string
description: The product type
enum:
- PHYSICAL
- DIGITAL
- SERVICE
- GIFT_CARD
name:
type: string
description: Display name for the product
description:
type: string
description: HTML description of the product
urlSlug:
type: string
description: URL-friendly slug for the product page
tags:
type: array
description: Tags to associate with the product
items:
type: string
isVisible:
type: boolean
description: Whether to make the product visible immediately
variants:
type: array
description: Initial variants for the product
items:
$ref: '#/components/schemas/CreateVariantRequest'
UpdateProductRequest:
type: object
description: Request body for updating an existing product (supports partial updates)
properties:
name:
type: string
description: Updated display name for the product
description:
type: string
description: Updated HTML description of the product
urlSlug:
type: string
description: Updated URL-friendly slug for the product page
tags:
type: array
description: Updated list of tags to associate with the product
items:
type: string
isVisible:
type: boolean
description: Updated visibility setting for the product
ProductVariant:
type: object
description: A specific variant of a product with its own price, SKU, and stock
properties:
id:
type: string
description: Unique identifier for the variant
sku:
type: string
description: Stock keeping unit identifier for the variant
pricing:
$ref: '#/components/schemas/VariantPricing'
stock:
$ref: '#/components/schemas/VariantStock'
attributes:
type: object
description: Key-value pairs of option names to selected values for this variant
additionalProperties:
type: string
CreateVariantRequest:
type: object
description: Request body for creating a product variant
required:
- sku
- pricing
properties:
sku:
type: string
description: Stock keeping unit identifier for the variant
pricing:
$ref: '#/components/schemas/VariantPricing'
stock:
$ref: '#/components/schemas/VariantStock'
attributes:
type: object
description: Option name to value mappings for this variant
additionalProperties:
type: string
UpdateVariantRequest:
type: object
description: Request body for updating a product variant (supports partial updates)
properties:
sku:
type: string
description: Updated stock keeping unit identifier
pricing:
$ref: '#/components/schemas/VariantPricing'
stock:
$ref: '#/components/schemas/VariantStock'
attributes:
type: object
description: Updated option name to value mappings
additionalProperties:
type: string
VariantPricing:
type: object
description: Pricing information for a product variant
properties:
basePrice:
$ref: '#/components/schemas/Money'
salePrice:
$ref: '#/components/schemas/Money'
onSale:
type: boolean
description: Whether the variant is currently on sale at the salePrice
VariantStock:
type: object
description: Stock tracking configuration for a product variant
properties:
quantity:
type: integer
description: Current stock quantity for the variant
minimum: 0
unlimited:
type: boolean
description: When true, the variant has unlimited stock
backordered:
type: boolean
description: Whether the variant is currently on backorder
ProductImage:
type: object
description: An image associated with a product
properties:
id:
type: string
description: Unique identifier for the product image
url:
type: string
format: uri
description: URL of the stored product image
altText:
type: string
description: Alternative text description for accessibility
width:
type: integer
description: Width of the image in pixels
height:
type: integer
description: Height of the image in pixels
UploadImageRequest:
type: object
description: Request body for uploading a product image from a URL
required:
- url
properties:
url:
type: string
format: uri
description: Publicly accessible URL of the image to upload
altText:
type: string
description: Alternative text for the image
UpdateImageRequest:
type: object
description: Request body for updating product image metadata
properties:
altText:
type: string
description: Updated alternative text for the image
Money:
type: object
description: A monetary value with currency
properties:
value:
type: string
description: Decimal string representation of the monetary amount
pattern: '^-?\d+(\.\d+)?$'
currency:
type: string
description: ISO 4217 three-letter currency code
pattern: '^[A-Z]{3}$'
Pagination:
type: object
description: Pagination metadata included with list responses
properties:
hasNextPage:
type: boolean
description: Indicates whether additional pages of results are available
nextPageCursor:
type: string
description: Cursor value to pass in the next request to retrieve the next page
nextPageUrl:
type: string
format: uri
description: Full URL for retrieving the next page of results
Error:
type: object
description: Standard error response returned by the Squarespace API
properties:
type:
type: string
description: Machine-readable error type identifier
subtype:
type: string
description: Optional more specific error subtype
message:
type: string
description: Human-readable description of the error
statusCode:
type: integer
description: HTTP status code associated with the error