Squarespace

כל הזמנה חדשה בחנות Squarespace מפיקה מסמך אוטומטית.

התקנה (5 דקות)#

1. ב-Squarespace: Settings → Developer Tools → API keys → Generate key עם הרשאת Orders. הממשק דורש חבילת Commerce Advanced. הדביקו את המפתח במסך החיבור בשדה Commerce API key.

2. יצירת Webhook subscription אפשרית רק עם OAuth (מפתח API לא מספיק). עם אסימון OAuth בעל הרשאת website.orders.read שלחו:

   bashהעתקה

   curl -X POST "https://api.squarespace.com/1.0/webhook_subscriptions" \
     -H "Authorization: Bearer <OAUTH_ACCESS_TOKEN>" -H "User-Agent: my-setup" \
     -H "Content-Type: application/json" \
     -d '{ "endpointUrl": "https://invoice.slk.co.il/api/billing/ecommerce/squarespace/<hookId>",
           "topics": ["order.create", "order.update"] }'

3. התשובה מחזירה secret בפורמט hex ומציגה אותו פעם אחת. העתיקו והדביקו אותו בשדה הסוד. אם פספסתם, בצעו rotateSecret וקבלו חדש.

4. בחרו סוג מסמך ולחצו על שליחת הזמנת בדיקה. הזמנות במצב בדיקה (testmode) וביטולים לא מפיקים מסמך.

Developer reference#

Mode: hook, pull. Category: builder. Refunds: not supported.

Event.

{ "id": "5c2ba184b63ed3cb411ce2b1", "websiteId": "5f3c3d55ac435e1a051f77b3",
  "subscriptionId": "5f3c2155d947844beedda991", "topic": "order.create",
  "createdOn": "2026-09-20T10:00:00.000Z", "data": { "orderId": "5f9d1c2e3a4b5c6d7e8f9a0b" } }

Auth. Squarespace-Signature is the hex digest of HMAC-SHA256 over the raw body, keyed with the subscription secret decoded from hex to raw bytes. Squarespace's docs are explicit that using the hex string itself as the key produces a different signature. Because of the hex-decoded key this is { kind: "custom" } and not the plain hmac kind (which keys with the UTF-8 string). A secret that is not valid hex can never verify.

Classify. Topics order.create and order.update with a well-formed data.orderId; anything else answers 200 event ignored.

Pull. GET https://api.squarespace.com/1.0/commerce/orders/{orderId} with Authorization: Bearer <API key> and the mandatory User-Agent. 404 answers 200 skipped; network error, 5xx, 401/403 answer 502; missing credentials answer 502 חסרים פרטי חיבור.

Which orders issue. fulfillmentStatus in {PENDING, FULFILLED} (Squarespace orders are paid when created). CANCELED and testmode: true are acknowledged without a row.

Mapping.

VAT. The document is always tax-included. If subtotal + shipping - discount + tax is closer to grandTotal than subtotal + shipping - discount, the store shows prices without tax: prices are grossed up by taxTotal / base. Otherwise prices already include tax. vatBp is taxTotal over the net amount, snapped to 1800 within 80bp. A zero taxTotal gives a 0% document. The payment row is computed from the lines, so it can differ from grandTotal by an agora of rounding.

Refunds. The order.update notification carries no refund amount and Squarespace documents no refund topic. Issue a credit note manually.

Test with curl (sample order id sample-order-000000000001 is answered from a fixture, no API key needed):

SECRET='<hex secret>'
BODY='{"id":"5c2ba184b63ed3cb411ce2b1","websiteId":"5f3c3d55ac435e1a051f77b3","subscriptionId":"5f3c2155d947844beedda991","topic":"order.create","createdOn":"2026-09-20T10:00:00.000Z","data":{"orderId":"sample-order-000000000001"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$SECRET" | awk '{print $NF}')
curl -i -X POST "https://invoice.slk.co.il/api/billing/ecommerce/squarespace/<hookId>" \
  -H "content-type: application/json" -H "Squarespace-Signature: $SIG" -d "$BODY"

Sources: webhook overview, verifying notifications, subscriptions API, orders API.

Troubleshooting#

• 401 — הסוד שגוי או לא בפורמט hex. הדביקו את ה-secret שהוחזר בעת יצירת ה-subscription, בלי רווחים. אפשר להוציא חדש עם rotateSecret.
• 404 — ה-hookId בכתובת שגוי. העתיקו שוב ממסך החיבור.
• 502 "חסרים פרטי חיבור" — הדביקו Commerce API key במסך החיבור. Squarespace ינסה שוב.
• 502 "פרטי החיבור נדחו" — למפתח אין הרשאת Orders, או שהחבילה אינה Commerce Advanced.
• אין מסמך להזמנה — הזמנה שבוטלה (CANCELED) והזמנת בדיקה (testmode) לא מפיקות מסמך.
• "blocked" — מכסת המסמכים החודשית או חבילת המנוי. "dormant" — מודול החיוב כבוי.