biggora Squarespace Commerce Customization and API Integration
Overview
Squarespace is a managed website building platform with integrated commerce capabilities. Unlike platforms with rich extension ecosystems (Shopify, WooCommerce), Squarespace offers a deliberately constrained customization model. There is no plugin marketplace, no server-side extension points, and no SDK for building installable apps. Squarespace Commerce development centers on two approaches: the Commerce APIs for external integrations, and code injection for frontend customization.
The Squarespace Commerce APIs follow a REST architecture with OAuth 2.0 authentication. They expose read and write access to orders, transactions, products, inventory, and customer profiles. External applications -- ERP systems, fulfillment providers, analytics platforms, custom dashboards -- use these APIs to synchronize data with Squarespace stores.
Frontend customization uses Squarespace's code injection system to add custom CSS, JavaScript, and HTML to specific pages or site-wide. The Fluid Engine layout system provides drag-and-drop block-based design, while code blocks allow embedding arbitrary HTML and scripts. Developer mode (legacy, available on Squarespace 7.0 sites only) exposed the JSON-T template engine for deep structural customization.
Customization Options
Code Injection
Squarespace provides code injection points for adding custom code without modifying templates:
- Site-wide header injection -- Code injected into the
<head>of every page. Use for analytics scripts, custom fonts, global CSS, and meta tags. - Site-wide footer injection -- Code injected before
</body>on every page. Use for tracking pixels, chat widgets, and JavaScript that depends on DOM readiness. - Per-page header injection -- Code injected into the
<head>of a specific page. Use for page-specific styles, structured data, or conditional scripts. - Code blocks -- Inline HTML/CSS/JS blocks placed within the page content via the Fluid Engine editor. Use for embedded widgets, custom forms, and interactive elements.
Code injection is available on all paid Squarespace plans. Custom code executes in the browser context alongside Squarespace's own scripts.
Custom CSS and JavaScript
Add custom CSS through the Design > Custom CSS panel. CSS changes apply site-wide and override template defaults. Squarespace assigns semantic class names to commerce elements (sqs-product-quick-view-content, product-price, cart-row) that serve as styling hooks.
Custom JavaScript added via code injection can interact with commerce pages: modify product displays, add custom validation to checkout-adjacent pages, implement dynamic pricing displays, and integrate third-party services. Access Squarespace's frontend data through the Static global object and JSON page data endpoints (/<page-slug>?format=json).
Developer Mode (Legacy)
Developer mode is available only on Squarespace 7.0 sites and provides access to the JSON-T template engine. In developer mode, the site's templates are exposed as .region and .block files that use the JSON-T syntax (a Squarespace-proprietary template language based on JSON data binding). Developer mode enables deep structural changes to page layouts, collection displays, and navigation.
Developer mode is not available on Squarespace 7.1 sites (the current version). Squarespace has not indicated plans to bring it to 7.1. For 7.1 sites, customization is limited to code injection, custom CSS, and the Fluid Engine block editor.
Fluid Engine
The Fluid Engine is Squarespace's current layout system (7.1). It provides a CSS Grid-based drag-and-drop editor for arranging content blocks. From a development perspective, Fluid Engine pages render as CSS Grid containers with positioned child blocks. Custom CSS can target Fluid Engine layouts using the .fluid-engine class and grid-area positioning.
Commerce APIs
Squarespace exposes REST APIs for commerce data. All API endpoints use the base URL https://api.squarespace.com/1.0/commerce/.
Orders API
Retrieve and manage orders placed through the Squarespace store:
GET /orders-- List orders with filtering by fulfillment status, date range, and modification date.GET /orders/{id}-- Retrieve a single order with line items, customer info, shipping, and payment details.POST /orders/{id}/fulfillments-- Create a fulfillment with tracking number and carrier.
Transactions API
Access payment transaction data:
GET /transactions-- List transactions with date filtering and pagination.GET /transactions/{id}-- Retrieve a single transaction with payment details.
Products API
Read product catalog data:
GET /products-- List all products with variants, pricing, images, and inventory.GET /products/{id}-- Retrieve a single product.
The Products API is read-only through the REST API. Product creation and modification require the Squarespace dashboard or third-party tools using the Squarespace Inventory API.
Inventory API
Manage inventory levels:
POST /inventory-- Update stock quantities for product variants. Supports absolute set and relative adjustment operations.
Profiles API
Access customer profile data:
GET /profiles-- List customer profiles with order history summary.GET /profiles/{id}-- Retrieve a single customer profile.
For complete API endpoint documentation, authentication details, and code examples, see references/commerce-api.md.
OAuth and API Authentication
Squarespace supports two authentication methods for API access:
API Keys
Generate API keys in the Squarespace dashboard under Settings > Developer API Keys. API keys provide full read/write access scoped to a single site. Include the key in the Authorization: Bearer <api-key> header.
API keys are suitable for first-party integrations where the developer controls both the Squarespace site and the consuming application. Do not distribute API keys to third parties.
OAuth 2.0
OAuth 2.0 is required for third-party applications that access multiple Squarespace sites. Register the application in the Squarespace Developer Portal to obtain a client ID and client secret.
The OAuth flow follows the authorization code grant:
- Redirect the site owner to
https://login.squarespace.com/api/1/login/oauth/provider/authorizewith the client ID, redirect URI, scopes, and state parameter. - The site owner authorizes the application and Squarespace redirects to the callback URL with an authorization code.
- Exchange the authorization code for an access token and refresh token at
https://login.squarespace.com/api/1/login/oauth/provider/tokens. - Use the access token in API requests. Refresh tokens when the access token expires (30 minutes).
Webhooks
Squarespace supports webhook subscriptions for real-time event notifications. Configure webhooks in the Squarespace dashboard under Settings > Developer API Keys > Webhooks, or manage them programmatically through the Webhook Subscriptions API.
Supported Events
| Topic | Trigger |
|---|---|
order.create |
New order placed |
order.update |
Order modified (status change, fulfillment added) |
extension.uninstall |
OAuth extension uninstalled by site owner |
inventory.update |
Inventory quantity changed (planned/beta) |
Webhook Payload
Webhook payloads include the event type, the site's websiteId, a createdOn timestamp, and a data object containing the relevant entity (order ID, product ID). Fetch the full entity data via the corresponding API endpoint after receiving the webhook notification.
Signature Verification
Squarespace does not provide HMAC signature verification for webhooks at the API key level. For OAuth-based integrations, verify the X-Squarespace-Signature header using the webhook signing secret. Always validate the websiteId in the payload matches the expected site.
Limitations
Squarespace's managed platform imposes significant constraints compared to open-source and app-marketplace platforms:
- No plugin marketplace. There is no mechanism to build, distribute, or sell extensions within the Squarespace ecosystem. All integrations are external.
- No server-side extension points. Developers cannot inject server-side logic into the Squarespace request lifecycle. No middleware, no hooks, no server-side event handlers.
- Read-only Products API. Products cannot be created or modified through the REST API. Product management requires the Squarespace dashboard.
- Limited webhook events. Only order and extension events are supported. No webhooks for product changes, page updates, or member actions.
- No custom checkout modification. The checkout flow is entirely managed by Squarespace. Custom fields, validation steps, and payment methods cannot be added to checkout.
- Template access restricted to 7.0. Developer mode and JSON-T template editing are not available on Squarespace 7.1.
- API rate limits. Requests are throttled at approximately 40 requests per second with a daily cap. Bulk data operations must implement paging and throttling.
For detailed customization techniques and integration patterns, see references/customization.md.
Anti-Patterns
- Scraping pages instead of using APIs -- Squarespace pages expose JSON data at
?format=json, but this endpoint is undocumented and subject to change without notice. Use the official Commerce APIs for reliable data access. - Storing API keys in client-side code -- Custom JavaScript injected via code blocks runs in the browser. Never embed API keys or secrets in client-side code. Proxy API calls through a backend server.
- Ignoring pagination -- All list endpoints return paginated results. Always handle the
pagination.nextPageCursorfield and iterate until no more pages are available. - Polling for order updates -- Use webhooks for order events instead of polling the Orders API. Polling wastes rate limit budget and introduces unnecessary latency.
- Relying on developer mode for new sites -- Developer mode is only available on Squarespace 7.0 sites. New sites default to 7.1. Do not build solutions that depend on JSON-T template access.
- Modifying checkout behavior via JavaScript -- Squarespace's checkout page restricts custom script execution. JavaScript injected via code injection does not run on checkout pages for security and PCI compliance reasons.
Reference Files
- Commerce API -- REST API endpoints, authentication, pagination, filtering, webhooks, rate limiting, error handling
- Customization -- Code injection, custom CSS, JavaScript APIs, member areas, JSON-T syntax, Fluid Engine, third-party integrations