Squarespace Inventory API
The Squarespace Inventory API enables developers to retrieve and update inventory quantities for product variants on a Squarespace merchant site. It supports bulk inventory queries and individual variant stock management.
OpenAPI Specification
openapi: 3.1.0
info:
title: Squarespace Commerce Inventory API
description: The Squarespace Commerce API provides programmatic access to the commerce features of a Squarespace merchant site. It enables developers to build integrations and applications that manage products, process orders, track inventory, access customer profiles, retrieve financial transactions, and configure webhook subscriptions. All endpoints use HTTPS and follow REST principles with standard verbs and response status codes. Authentication is handled via API keys or OAuth tokens.
version: '1.0'
contact:
name: Squarespace Developer Support
url: https://developers.squarespace.com/commerce-apis/overview
termsOfService: https://www.squarespace.com/terms-of-service
servers:
- url: https://api.squarespace.com/1.0
description: Production Server
security:
- bearerAuth: []
tags:
- name: Inventory
description: Stock level retrieval and adjustment for product variants
paths:
/commerce/inventory:
get:
operationId: listInventory
summary: Retrieve All Inventory
description: Returns real-time stock information for all product variants on the merchant site. The response contains up to 50 InventoryItem objects per page, with dynamic cursor-based pagination for iterating through all records. Each InventoryItem corresponds to a single product variant and includes its current stock quantity and tracking settings.
tags:
- Inventory
parameters:
- $ref: '#/components/parameters/cursor'
responses:
'200':
description: Successful response with paginated list of inventory items
content:
application/json:
schema:
type: object
properties:
inventory:
type: array
description: List of inventory items for product variants
items:
$ref: '#/components/schemas/InventoryItem'
pagination:
$ref: '#/components/schemas/Pagination'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/commerce/inventory/{variantIds}:
get:
operationId: getInventoryByVariants
summary: Retrieve Specific Inventory
description: Retrieves real-time stock information for up to 50 specific product variants by their variant IDs. Variant IDs should be provided as a comma-separated list in the path. This endpoint is useful for checking stock levels on specific items without paginating through the full inventory.
tags:
- Inventory
parameters:
- $ref: '#/components/parameters/variantIds'
responses:
'200':
description: Successful response with inventory items for the specified variants
content:
application/json:
schema:
type: object
properties:
inventory:
type: array
description: Inventory items for the requested product variants
items:
$ref: '#/components/schemas/InventoryItem'
'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/inventory/adjustments:
post:
operationId: adjustInventory
summary: Adjust Stock Quantities
description: Applies incremental stock quantity adjustments to one or more product variants. Adjustments are relative changes, not absolute values. Positive values increase stock and negative values decrease it. Bulk adjustments across multiple variants can be submitted in a single request. Each adjustment can optionally include a reason for audit tracking.
tags:
- Inventory
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdjustInventoryRequest'
responses:
'200':
description: Inventory adjustments applied successfully
content:
application/json:
schema:
type: object
properties:
inventory:
type: array
description: Updated inventory items after adjustments were applied
items:
$ref: '#/components/schemas/InventoryItem'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
AdjustInventoryRequest:
type: object
description: Request body for applying inventory adjustments
required:
- increments
properties:
increments:
type: array
description: List of inventory adjustments to apply
items:
$ref: '#/components/schemas/InventoryAdjustment'
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
InventoryAdjustment:
type: object
description: A single stock quantity adjustment for a product variant
required:
- variantId
- quantity
properties:
variantId:
type: string
description: Unique identifier of the product variant to adjust
quantity:
type: integer
description: Relative quantity change to apply. Positive values increase stock, negative values decrease it.
InventoryItem:
type: object
description: Stock information for a single product variant
properties:
variantId:
type: string
description: Unique identifier of the product variant
sku:
type: string
description: Stock keeping unit identifier for the variant
descriptor:
type: string
description: Human-readable description of the variant including option values
isUnlimited:
type: boolean
description: When true, the variant has unlimited stock and quantity values are not meaningful
isTracked:
type: boolean
description: Whether stock tracking is enabled for this variant
quantity:
type: integer
description: Current stock quantity available for the variant
minimum: 0
infiniteStock:
type: boolean
description: Alias for isUnlimited indicating the variant never goes out of stock
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
responses:
Unauthorized:
description: Authentication credentials are missing or invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: The request was malformed or contained invalid parameters
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'
Forbidden:
description: The authenticated user does not have permission to access this resource
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
variantIds:
name: variantIds
in: path
description: Comma-separated list of up to 50 product variant IDs for which to retrieve inventory information
required: true
schema:
type: string
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
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".
externalDocs:
description: Squarespace Commerce API Documentation
url: https://developers.squarespace.com/commerce-apis/overview