t1k:web:commerce:squarespace

Field	Value
Module	`commerce`
Version	`1.9.0`
Effort	`medium`
Tools	—

Keywords: api, commerce, ecommerce, inventory, orders, products, profiles, squarespace, transactions, webhooks

How to invoke

/t1k:web:commerce:squarespace
[api] [operation]

Squarespace Commerce APIs

Integrate a Squarespace store from your own backend: read/write the catalog, keep stock in sync, ingest orders from third-party sales channels, and reconcile payments. All facts here are grounded in the official docs at developers.squarespace.com (verified 2026-07-17) — see the per-API references for endpoint tables and examples.

When to use

Build a custom app/integration against a Squarespace Commerce Advanced store (API keys) or a multi-site Squarespace Extension (OAuth).
Sync products/inventory to or from another system (ERP, POS, marketplace).
Import orders created on an external channel (Instagram, a marketplace) into Squarespace.
Pull transactions for finance reconciliation.
Subscribe to store events via webhooks (OAuth only).

Decision tree

You need to…	Go to	Key endpoint(s)
Auth, headers, pagination, errors, rate limits, idempotency	`references/conventions.md`	(cross-cutting)
Read/write catalog products + variants + images	`references/products-inventory.md`	`GET/POST /v2/commerce/products`
Read stock, adjust quantities	`references/products-inventory.md`	`GET /1.0/commerce/inventory`, `POST /1.0/commerce/inventory/adjustments`
List/read/create orders, mark fulfilled	`references/orders-transactions.md`	`GET/POST /1.0/commerce/orders`, `POST …/fulfillments`
Reconcile payments / payouts / refunds	`references/orders-transactions.md`	`GET /1.0/commerce/transactions`
Read customer profiles	`references/profiles-webhooks.md`	`GET /1.0/profiles`
Subscribe to store events (OAuth only)	`references/profiles-webhooks.md`	Webhook Subscriptions API

The three facts that trip people up

Version is per-API, not uniform. Products is v2 (/v2/commerce/products); inventory, orders, transactions, profiles, webhooks are 1.0. Never hardcode one version across all calls. (Since 2025 Squarespace uses integer versioning — a bump means a breaking change.)
User-Agent is required on every request. Requests without a descriptive User-Agent are rejected, and default/library UA strings attract stricter rate limiting. Set a custom one.
API keys can’t do webhooks. The Webhook Subscriptions API is OAuth-only. API keys (Commerce Advanced plan, generated in the site UI) cover everything else. Order creation is also rate-limited to 100/hour on API-key auth (not on OAuth).

Quick start (API key)

curl https://api.squarespace.com/1.0/commerce/inventory \
  -H "Authorization: Bearer $SQUARESPACE_API_KEY" \
  -H "User-Agent: MyApp/1.0 (dev@example.com)"

Auth model, scopes, pagination, error shape, and idempotency: references/conventions.md.

Reference implementation

The1Studio ships a working MCP server that wraps these APIs (Python/FastMCP): The1Studio/squarespace-mcp — read its client.py/server.py for a concrete, tested httpx client (Bearer + User-Agent, cursor pagination, idempotency keys, lazy key check).

References

references/conventions.md — base URL, versioning table, auth (API key + OAuth), headers, pagination, errors, rate limits, idempotency.
references/products-inventory.md — Products API (v2) + Inventory API endpoint tables, response shapes, examples.
references/orders-transactions.md — Orders API + Transactions API endpoint tables, create/fulfill bodies, examples.
references/profiles-webhooks.md — Profiles API + Webhook Subscriptions API + brief note on Contacts/Discounts/Forms.