Squarespace

Squarespace

Squarespace Commerce API for managing orders, products, inventory, transactions, customer profiles, and webhook subscriptions on your online store.

Data Model

• Orders — capture, fulfillment state, and adjustments. Filter by date range, customer, or fulfillment status (PENDING/FULFILLED/CANCELED). Cursor pagination, up to 50 per page.
• Products & variants — catalog authoring with variant matrices (Color, Size), pricing, stock, SKU, and images. Products belong to exactly one store page. Filter by type (PHYSICAL/DIGITAL/SERVICE/GIFT_CARD).
• Inventory — stock tracked per-variant, not per-product. Supports INCREMENT, DECREMENT, SET_FINITE, and SET_UNLIMITED operations.
• Transactions — financial documents grouping payments, refunds, fees, taxes, discounts, and shipping. Linked via salesOrderId.
• Profiles — customer and member data. Available only on bundles connected with field-based credentials, not OAuth.
• Webhooks — subscribe to topics: order.create, order.update, extension.uninstall, inventory.update, product.create, product.update, product.delete.
• Store pages — top-level commerce containers that hold product collections. Required for creating products.

Relationships

• Products belong to a store page (need store_page_id to create).
• Variants belong to a product (tracked independently for inventory and pricing).
• Orders contain line items referencing variantId and productId.
• Transactions link to orders via salesOrderId.

Auth Considerations

• OAuth scopes: website.orders, website.transactions.read, website.inventory, website.products.
• Inventory scope required: Inventory reads and stock adjustments need website.inventory on the OAuth token. Missing scope surfaces as AUTHORIZATION_ERROR — OAuth tokens need that scope alongside orders, products, and transactions.
• Profiles unavailable on OAuth: Squarespace does not provide an OAuth scope for profiles; OAuth-connected bundles return AUTHORIZATION_ERROR on profile reads. Field-based auth reaches profiles when the upstream token allows it.

Gotchas

• store_page_id: Required when creating products — list store pages first.
• Variant attributes: Express as structured attribute maps (e.g. {"Size": "Medium"}).
• Cursor pagination: When using cursor, all other filter parameters are ignored by the API.
• Pricing values: Pass as strings (e.g. "9.99" for $9.99).
• Idempotency: Order creation and inventory adjustments use Idempotency-Key headers.