A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Squarespace API is how an app or AI agent works with an online store: editing products, adjusting stock, reading and fulfilling orders, and looking up customers. Access is granted through an API key or an OAuth token, each scoped per area like products, orders, or inventory, so a credential reaches only what it was granted, to read or to write. Squarespace can also push store events, like an order being created, to a subscribed endpoint.
How an app or AI agent connects to Squarespace determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the API key or OAuth token behind it and the permissions that credential carries.
The Commerce APIs are HTTPS REST endpoints under https://api.squarespace.com, returning JSON only. Most resources sit on the 1.0 path (orders, inventory, transactions, profiles, webhook subscriptions) while Products moved to v2. A call authenticates with a Bearer credential, an API key or an OAuth token, and every request must send a User-Agent header or it is rejected.
Squarespace POSTs a JSON payload to a subscribed HTTPS endpoint when a site event fires, like order.create or order.update. Each notification carries a Squarespace-Signature header that the receiver verifies against the subscription's secret to confirm the request came from Squarespace. Subscriptions are managed through the Webhook Subscriptions API and require OAuth.
A merchant generates an API key in their site settings and grants it Read Only or Read and Write per Commerce API. The key is sent as a Bearer credential and does not expire while the site stays active. API keys are available on Commerce Advanced plans and are meant for a custom app on a single site, not for distributed extensions.
OAuth 2.0 is required for Squarespace Extensions and commercial apps that connect many merchant sites. A merchant authorizes a set of scopes, like website.orders.read or website.inventory, and the app receives an access token valid for 30 minutes plus a refresh token valid for 7 days when offline access is requested. The Webhook Subscriptions API works with OAuth tokens only.
The Squarespace Commerce API is split into areas an agent can act on, like products, inventory, orders, transactions, and customer profiles. Each area has its own methods and its own permission, and a write in orders or inventory changes a live store.
Methods for managing physical, service, gift card, and download products, their images, and variants.
Methods for reading and adjusting stock levels for product variants.
Methods for reading order history, importing orders, and marking orders fulfilled.
Methods for reading the financial documents behind orders and donations.
Methods for reading customers, subscribers, and donors. In maintenance mode; the Contacts API is the replacement.
Methods for subscribing to site events, like an order being created.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ProductsMethods for managing physical, service, gift card, and download products, their images, and variants.9 | ||||||
| GET | /v2/commerce/products | Retrieve all products on a site, paginated with a cursor. | read | website.products.read | New | |
Products moved to v2 (GA 18 Dec 2025); v1.1 and v1.0 stay supported. Read-only. Acts onproduct Permission (capability) website.products.readVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/commerce/products/{productIdCsvs} | Retrieve one or more specific products by a comma-separated list of ids. | read | website.products.read | New | |
Read-only. Accepts up to a comma-separated set of product ids. Acts onproduct Permission (capability) website.products.readVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/commerce/products | Create a physical, service, gift card, or download product. | write | website.products | New | |
A core catalog write; needs the website.products scope or a key with Products Read and Write. Acts onproduct Permission (capability) website.productsVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/commerce/products/{productId} | Update an existing product's details. | write | website.products | New | |
A core catalog write. Acts onproduct Permission (capability) website.productsVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/commerce/products/{productId} | Permanently delete a product. | write | website.products | New | |
Irreversible; removes the product and its variants from the store. Acts onproduct Permission (capability) website.productsVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/commerce/products/{productId}/images | Upload an image to a product. | write | website.products | New | |
Image processing is asynchronous; a status endpoint reports when it is ready. Acts onproduct_image Permission (capability) website.productsVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/commerce/products/{productId}/variants | Create a variant on a product. | write | website.products | New | |
A variant is a sellable option of a product, like a size or color. Acts onproduct_variant Permission (capability) website.productsVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/commerce/products/{productId}/variants/{variantId} | Update a product variant. | write | website.products | New | |
A core catalog write. Acts onproduct_variant Permission (capability) website.productsVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/commerce/products/{productId}/variants/{variantId} | Delete a product variant. | write | website.products | New | |
Irreversible for that variant. Acts onproduct_variant Permission (capability) website.productsVersionIntroduced 2025-12-18 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InventoryMethods for reading and adjusting stock levels for product variants.3 | ||||||
| GET | /1.0/commerce/inventory | Retrieve stock information for all product variants, paginated with a cursor. | read | website.inventory.read | Current | |
Read-only. Returns up to 50 items per page. Acts oninventory Permission (capability) website.inventory.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1.0/commerce/inventory/{variantIdCsvs} | Retrieve stock for specific variants by a comma-separated list of ids. | read | website.inventory.read | Current | |
Read-only. Up to 50 variant ids per request. Acts oninventory Permission (capability) website.inventory.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1.0/commerce/inventory/adjustments | Adjust stock: increment, decrement, set a finite quantity, or mark a variant as unlimited. | write | website.inventory | Current | |
Requires an Idempotency-Key header so a retried adjustment is applied once. Acts oninventory_adjustment Permission (capability) website.inventoryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersMethods for reading order history, importing orders, and marking orders fulfilled.4 | ||||||
| GET | /1.0/commerce/orders | Retrieve order history, filterable by customer, fulfillment status, payment state, and modified date. | read | website.orders.read | Current | |
Read-only. cursor cannot be combined with the modifiedAfter or modifiedBefore date filters. Acts onorder Permission (capability) website.orders.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1.0/commerce/orders/{orderId} | Retrieve a single order by id. | read | website.orders.read | Current | |
Read-only. Acts onorder Permission (capability) website.orders.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1.0/commerce/orders | Import an order from a third-party sales channel into a Squarespace site. | write | website.orders | Current | |
With API-key auth this endpoint is capped at 100 requests per hour, per website. Acts onorder Permission (capability) website.ordersVersionAvailable since the API’s base version Webhook event order.createRate limit100 requests per hour, per website (API key auth) SourceOfficial documentation ↗ | ||||||
| POST | /1.0/commerce/orders/{orderId}/fulfillments | Mark an order fulfilled and optionally notify the customer with shipment details. | write | website.orders | Current | |
Moves the order's fulfillment status toward FULFILLED. Acts onorder_fulfillment Permission (capability) website.ordersVersionAvailable since the API’s base version Webhook event order.updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TransactionsMethods for reading the financial documents behind orders and donations.2 | ||||||
| GET | /1.0/commerce/transactions | Retrieve the financial documents behind orders and donations, filterable by modified date or order id. | read | website.transactions.read | Current | |
Read-only. A Document holds totals, payments, refunds, and gateway data for one order or donation. Acts ontransaction_document Permission (capability) website.transactions.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1.0/commerce/transactions/{documentIdCsvs} | Retrieve specific transaction documents by a comma-separated list of ids. | read | website.transactions.read | Current | |
Read-only. Acts ontransaction_document Permission (capability) website.transactions.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Profiles (Customers)Methods for reading customers, subscribers, and donors. In maintenance mode; the Contacts API is the replacement.2 | ||||||
| GET | /1.0/profiles | Retrieve all profiles (customers, subscribers, donors), filterable and sortable. | read | website.profiles | Deprecated | |
In maintenance mode since 9 Apr 2026; the Contacts API is the modern replacement. Returns up to 50 profiles per page. Acts onprofile Permission (capability) website.profilesVersionDeprecated 2026-04-09 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /1.0/profiles/{profileIdCsvs} | Retrieve specific profiles by a comma-separated list of ids. | read | website.profiles | Deprecated | |
Maintenance mode; up to 50 ids per request. Acts onprofile Permission (capability) website.profilesVersionDeprecated 2026-04-09 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webhook SubscriptionsMethods for subscribing to site events, like an order being created.5 | ||||||
| GET | /1.0/webhook_subscriptions | Retrieve all webhook subscriptions for the site. | read | website.orders.read | Current | |
Webhook Subscriptions require OAuth; a subscription's topics each need the matching read scope. Acts onwebhook_subscription Permission (capability) website.orders.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1.0/webhook_subscriptions | Create a webhook subscription for one or more event topics, returning a signing secret. | write | website.orders | Current | |
OAuth only. The token must hold the scope for each subscribed topic, like website.orders.read for order events. Acts onwebhook_subscription Permission (capability) website.ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1.0/webhook_subscriptions/{subscriptionId} | Update an existing webhook subscription's endpoint or topics. | write | website.orders | Current | |
OAuth only. Acts onwebhook_subscription Permission (capability) website.ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /1.0/webhook_subscriptions/{subscriptionId} | Delete a webhook subscription so its events stop being delivered. | write | website.orders | Current | |
OAuth only. Acts onwebhook_subscription Permission (capability) website.ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /1.0/webhook_subscriptions/{subscriptionId}/actions/sendTestNotification | Send a test notification to a subscription's endpoint to confirm delivery and signature checks. | write | website.orders | Current | |
OAuth only. Useful for verifying signature handling before going live. Acts onwebhook_subscription Permission (capability) website.ordersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Squarespace can notify an app or AI agent when something happens on a site, like an order being created or updated. It posts a signed JSON payload to a subscribed endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
order.create | An order was created on the site. Requires access to the Orders API for the subscription to receive it. | /1.0/commerce/orders |
order.update | An order changed, like a fulfillment, a refund, or a payment-state change. | /1.0/commerce/orders/{orderId}/fulfillments |
extension.uninstall | A merchant uninstalled the extension, so the app should stop calling and clean up stored tokens. | In-app only |
contact.create | A contact was created on the site (Contacts API). Released 15 Apr 2026. | In-app only |
contact.update | A contact's details changed. | In-app only |
contact.delete | A contact was deleted. | In-app only |
Squarespace limits how fast an app or AI agent can call, through a per-minute request ceiling shared across the Commerce APIs, with a separate hourly cap on creating orders with an API key.
Squarespace meters the Commerce APIs by request rate, not by a per-method cost. A site can make 300 requests per minute across the Commerce APIs, an average of five per second. Creating orders with an API key has a separate cap of 100 requests per hour, per website. Going over returns HTTP 429 Too Many Requests with a one-minute cooldown. Requests without a User-Agent header are rejected, and a generic client User-Agent may be subject to stricter rate limiting than a custom one.
List endpoints are cursor-based. A response returns up to 50 items and, when more remain, a pagination object with a cursor and a nextPageUrl to fetch the next page. A cursor cannot be combined with date filters like modifiedAfter or modifiedBefore on the same request. Cursors are dynamic, not snapshots, so results can shift if the underlying data changes between pages.
A list page returns at most 50 items. Endpoints that take a comma-separated set of ids, like specific products, inventory, transactions, or profiles, accept up to 50 ids per request. Commerce APIs return JSON only and reject any request sent over plain HTTP instead of HTTPS.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST_ERROR | The request had a bad query parameter, a malformed body, or referenced an unknown resource. A subtype such as MISSING_ARGUMENT narrows the cause. | Read the message field, fix the parameters or body, and resend. The request is not retryable as-is. |
| 401 | AUTHORIZATION_ERROR | Authorization failed: the API key or OAuth token was missing, invalid, or expired. An OAuth access token lasts only 30 minutes. | Send a valid credential, and refresh the OAuth access token with the refresh token when it expires. |
| 403 | PERMISSION_DENIED | The credential authenticated but lacks the permission the request needs, for example a read-only key calling a write endpoint. | Grant the matching scope or key permission. Existing key and token permissions cannot be edited; issue a new key or re-authorize OAuth with the wider scope. |
| 404 | NOT_FOUND | The requested resource does not exist or is not visible to this credential. | Verify the id and that the resource belongs to the authenticated site. |
| 429 | RATE_LIMITED | Too many requests: the site went over 300 requests per minute, or an API-key order import passed 100 per hour. | Wait out the one-minute cooldown, then retry with backoff and smooth the request rate. |
| 500 | INTERNAL_ERROR | An error on Squarespace's side. The response includes a contextId for reporting. | Retry with backoff, and include the contextId when contacting Squarespace support if it persists. |
Squarespace versions each Commerce API on its own path, most at 1.0 while Products moved to v2 in December 2025, and ships dated changes through its developer changelog without breaking older versions in place.
Most Commerce APIs sit on the 1.0 path and evolve in place through the dated developer changelog, with breaking changes reserved for a new version. The entries below are notable dated changes from that changelog.
The Products API moved to v2, reaching general availability on 18 December 2025 with support for Physical, Service, Gift Card, and Download product types. The earlier v1.1 and v1.0 versions remain fully supported.
The Contacts API reached general availability and became the recommended way to work with the people associated with a site, moving the older Profiles API into maintenance.
Pin a version per API and move up deliberately when a new one ships.
Squarespace Commerce API changelog ↗Bollard AI sits between a team's AI agents and Squarespace. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.