sales-skills/sales-squarespace

Squarespace Platform Help

Squarespace is a design-first, all-in-one website builder with a built-in commerce layer — online store, memberships, digital downloads, gift cards, donations, subscriptions, and (via bundled Acuity Scheduling) bookings. You don't automate the site builder (pages/themes are UI-only); you automate the commerce layer with the Squarespace Commerce APIs (Orders, Inventory, Products, Transactions, Contacts) plus OAuth-gated webhooks. It's not a Merchant of Record (you own tax). This skill covers that integration surface and the pain points — the commerce-plan API gate, OAuth-only webhooks, HMAC verification, Squarespace Payments holds — that trip people up.

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

Ask only what you need (skip if the prompt already says):

1. What's the goal? (a) automate/integrate via the API or webhooks, (b) fix a store/payments/inventory problem, (c) pick a Squarespace plan or weigh fees, (d) compare Squarespace vs another platform.
2. Build context — automating your own site (an API key works, OAuth for webhooks) or a third-party app across other sites (OAuth)? Which objects — orders, products, inventory, transactions, contacts?
3. What plan is the site on? Commerce APIs require a paid commerce plan; a personal/Basic plan has no API.

Skip-ahead rule: if the user's prompt already contains enough context, go straight to Step 2.

Step 2 — Route or answer directly

Map the request to the right home. When routing, give the exact command.

| The user's real problem | Route to | |---|---| | Checkout-conversion strategy across tools (order bumps, AOV, cart abandonment tactics) | /sales-checkout {question} | | Migrating a store off (or onto) Squarespace — data export, redirects, SEO | /sales-checkout {question} (migration mechanics) | | Choosing a Merchant of Record for global tax / VAT instead | /sales-merchant-of-record {question} | | Memberships / paid gated-content strategy across tools | /sales-membership {question} | | Selling digital downloads strategy across tools | /sales-digital-products {question} | | Appointment booking strategy (Acuity is a separate product) | /sales-meeting-scheduler {question} | | General website / landing-page / funnel strategy | /sales-funnel {question} | | Post-purchase / abandoned-cart email sequences | /sales-email-marketing {question} | | Not sure which skill | /sales-do {question} |

Anything Squarespace-specific (Commerce APIs, webhooks, plan gates, payments holds) — answer here using Step 3.

Step 3 — Squarespace platform reference

Read references/platform-guide.md for the full platform reference — capabilities & automation surface, pricing/plan gates, the data model with JSON shapes, integration recipes (cURL + Python), and integration patterns.

For raw API detail (endpoints, request/response JSON, auth headers, webhook HMAC verification), read references/squarespace-api-reference.md.

Answer using only the relevant section — don't dump the whole reference.

Step 4 — Actionable guidance

You no longer need the guide loaded — focus on the user's situation:

• Integration: Own site → an API key (Bearer) for reads/writes; OAuth is required to register webhooks and for multi-site apps. Always send a custom User-Agent (a default one draws stricter rate limiting) and Content-Type: application/json on writes. Base URL https://api.squarespace.com/{version}/{path} — versions are per-endpoint (Orders 1.0, Products 2). HTTPS only.
• Real-time vs polling: For purchase-driven automation prefer the order.create/order.update webhook, but its payload is thin — verify the HMAC, then GET the full order. If you can't host a listener or you're API-key-only, poll GET /commerce/orders with paired modifiedAfter+modifiedBefore.
• Plan/fee math: Commerce APIs, abandoned-cart recovery, and subscriptions need a paid commerce plan (Core+ / Advanced). Transaction fees drop by tier (Basic 2% → Core/Plus/Advanced 0%; digital-product fee 7%→5%→1%→0%). Do the break-even before recommending a tier; flag pricing as best-effort.
• Don't promise page edits: the site builder is UI-only — there's no site-builder API. Automate commerce objects, not pages/themes.

If you discover a gotcha or tip not in references/learnings.md, append it there with today's date.

Gotchas

Best-effort from research (2026-06) — review these, especially plan-gated features and integration details that may be outdated.

• The Commerce API is plan-gated — the #1 trap. No API on a free trial or personal/Basic plan. Docs list Orders/Inventory on Core/Plus/Advanced/Commerce Advanced; some reviews say Advanced ($99/mo) only. Confirm the site's plan before promising an integration.
• Webhooks require OAuth, not an API key. An API key can read/write and poll orders, but only an OAuth app can create webhook subscriptions. This is the usual "why won't my webhook register" cause.
• Thin webhook payloads. data carries an orderId, not the order — make a follow-up GET /commerce/orders/{id}. Dedupe on order.id; retries duplicate.
• HMAC secret is hex — decode it to bytes. Verify Squarespace-Signature as HMAC-SHA256 over the raw body using hexToBytes(secret). Using the hex string directly, or hashing a re-serialized body, fails.
• Money is a {currency, value} decimal object, not integer cents (unlike Square/Sellfy). Don't divide by 100.
• modifiedAfter/modifiedBefore are paired and mutually exclusive with cursor — date window on the first page, cursor-only after.
• Donations bypass the Orders API — read them via the Transactions API.
• Squarespace Payments holds are a recurring complaint with slow support — don't rely on a single processor for a time-sensitive launch.
• No multi-currency and a limited gateway set (Squarespace Payments / Stripe / PayPal). Not a Merchant of Record — you own tax (US auto-calc via TaxJar).

Related skills

• /sales-checkout — Cross-tool checkout-conversion strategy, order bumps, AOV, and cart-abandonment tactics (Squarespace is one platform among Shopify/BigCommerce/Wix/Square Online/Medusa).
• /sales-square-online — Square Online, the other free-to-start website-builder-plus-store (and the closest API analog — shared-catalog commerce backend, HMAC webhooks).
• /sales-wix — Wix eCommerce, the other no-code website-builder-plus-store option.
• /sales-shopify — Shopify commerce backend (GraphQL Admin API), the scale-oriented alternative for product-heavy stores.
• /sales-merchant-of-record — Choosing a MoR (Paddle/Lemon Squeezy) for global VAT/GST vs owning tax yourself.
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code

Examples

Example 1: "Sync every new Squarespace order into my CRM"

A developer/automation question. Recommend the order.create webhook over polling, but note Squarespace webhooks need OAuth (an API key can't subscribe). Walk through: register the subscription (store the one-time hex secret), verify the HMAC-SHA256 signature in the Squarespace-Signature header over the raw body using hexToBytes(secret), then GET /1.0/commerce/orders/{orderId} (the payload is just a pointer), and upsert deduping on order.id. If they can't host a listener, show the modifiedAfter/modifiedBefore polling loop instead. Point to references/squarespace-api-reference.md for the JSON + verification code.

Example 2: "My Commerce API calls return nothing / 'not available on your plan'"

The top integration trap. Explain the Commerce APIs are plan-gated — no API on a free trial or personal/Basic plan; you need a paid commerce plan (Squarespace docs say Core/Plus/Advanced/Commerce Advanced, some reviews say Advanced-only). Have them confirm the site's plan and that the API key has the right permission scopes, and that they're hitting https://api.squarespace.com/1.0/commerce/orders over HTTPS with Authorization: Bearer + a custom User-Agent. Flag the plan ambiguity as best-effort and tell them to verify against current docs.

Example 3: "Basic vs Core vs Plus vs Advanced — which plan, and what are the fees?"

Pricing/plan-gate question (answer from the guide). Walk the tiers (best-effort 2026): Basic ~$16 has a 2% commerce fee + 7% digital fee and no Commerce API; Core ~$23 removes the commerce fee (5% digital); Plus ~$39 (1% digital, lower processing); Advanced ~$99 (0%/0%, plus abandoned-cart recovery, subscriptions, advanced shipping, Commerce APIs). Do the break-even on the fee deltas vs the monthly jump, and note no multi-currency and limited gateways. Flag all pricing as best-effort and tell them to confirm current rates.

Troubleshooting

"My webhook won't register / I get nothing on order events"

Two causes. (1) Auth: the Webhook Subscriptions API is OAuth-only — you can't create a subscription with an API key. Register an OAuth app, authorize scopes matching your topics (order.create/order.update), then POST /1.0/webhook_subscriptions. (2) Plan/verification: confirm the site is on an API-eligible commerce plan and that your listener returns 2xx fast over HTTPS. Use the "Send test notification" endpoint to validate. If you only need your own site and can't do OAuth, poll GET /commerce/orders?modifiedAfter=…&modifiedBefore=… instead.

"My webhook signature verification keeps failing"

Squarespace-Signature is HMAC-SHA256 over the raw request body, keyed by the subscription secret — which is hex-encoded and must be decoded to raw bytes first. Common mistakes: using the hex string directly as the key, hashing a parsed/re-serialized JSON object instead of the raw bytes, or comparing non-constant-time. Capture the raw body before any JSON parsing, do HMAC-SHA256(hexToBytes(secret), rawBody), hex-encode, and timingSafeEqual/compare_digest. If it still fails, rotate the secret (returns a new one once) and re-store it.

"Payments are stuck on a Squarespace Payments hold"

A documented, recurring complaint (Trustpilot/Reddit/BBB) with slow support resolution. Holds are a risk-review on the Squarespace Payments processor — there's no API to release them; you contact support and provide requested verification. Mitigations: don't run a time-sensitive launch on a brand-new Squarespace Payments account, keep a fallback gateway (Stripe/PayPal) connected, and reconcile payouts via the Transactions API so you can see what's actually settled vs held.