Skill: byungkyu/squarespace (version 1.0.1)

--- name: squarespace description: | Squarespace Commerce API integration with managed OAuth. Manage products, inventory, orders, customer profiles, and transactions. Use this skill when users want to manage e-commerce operations on Squarespace stores. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: homepage: "https://maton.ai" requires: env: - MATON_API_KEY --- # Squarespace Access the Squarespace Commerce API with managed OAuth authentication. Manage products, inventory, orders, customer profiles, and transactions. ## Quick Start ```bash # List all products (v2 API) python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/squarespace/v2/commerce/products') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('User-Agent', 'MyClaude/1.0') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://api.maton.ai/squarespace/{native-api-path} ``` Maton proxies requests to `api.squarespace.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Squarespace OAuth connections at `https://api.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections?app=squarespace&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'squarespace'}).encode() req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "{connection_id}", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "squarespace", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Squarespace connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/squarespace/v2/commerce/products') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('User-Agent', 'MyClaude/1.0') req.add_header('Maton-Connection', '{connection_id}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If you have multiple connections, always include this header to ensure requests go to the intended account. ## Security & Permissions - Access is scoped to products, inventory, orders, customer profiles, and transactions within the connected Squarespace account. - **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user. ## API Reference ### Inventory #### List All Inventory ```bash GET /squarespace/1.0/commerce/inventory ``` Query parameters: - `cursor` (optional): Pagination cursor from previous response **Response:** ```json { "inventory": [ { "variantId": "5ba1418df4204bb2d21eac3f", "sku": "SQ0001", "descriptor": "Product Name - Size: Medium", "isUnlimited": false, "quantity": 25 } ], "pagination": { "hasNextPage": true, "nextPageCursor": "abc123", "nextPageUrl": "https://api.squarespace.com/1.0/commerce/inventory?cursor=abc123" } } ``` #### Get Specific Inventory ```bash GET /squarespace/1.0/commerce/inventory/{variantIds} ``` - `{variantIds}`: Comma-separated variant IDs (max 50) #### Adjust Stock Quantities ```bash POST /squarespace/1.0/commerce/inventory/adjustments Content-Type: application/json Idempotency-Key: unique-key-here { "incrementOperations": [{"variantId": "variant-id-1", "quantity": 5}], "decrementOperations": [{"variantId": "variant-id-2", "quantity": 2}], "setFiniteOperations": [{"variantId": "variant-id-3", "quantity": 100}], "setUnlimitedOperations": ["variant-id-4"] } ``` **Response:** 204 No Content on success --- ### Orders #### List All Orders ```bash GET /squarespace/1.0/commerce/orders ``` Query parameters: - `customerId` (optional): Filter by customer ID - `modifiedAfter` (conditional): ISO 8601 datetime (e.g., `2024-01-01T00:00:00Z`) - required with `modifiedBefore` - `modifiedBefore` (conditional): ISO 8601 datetime - required with `modifiedAfter` - `cursor` (optional): Pagination cursor - `fulfillmentStatus` (optional): `PENDING`, `FULFILLED`, or `CANCELED` Note: Cannot combine cursor with date range parameters. Date filters must be used together. **Response:** ```json { "result": [ { "id": "order-id", "orderNumber": "1001", "createdOn": "2024-01-15T10:30:00Z", "modifiedOn": "2024-01-15T12:00:00Z", "channel": "web", "testmode": false, "customerEmail": "[REDACTED_SECRET]", "fulfillmentStatus": "PENDING", "lineItems": [...], "subtotal": {"value": "99.99", "currency": "USD"}, "shippingTotal": {"value": "9.99", "currency": "USD"}, "taxTotal": {"value": "8.50", "currency": "USD"}, "grandTotal": {"value": "118.48", "currency": "USD"} } ], "pagination": { "hasNextPage": true, "nextPageCursor": "abc123", "nextPageUrl": "..." } } ``` #### Get Specific Order ```bash GET /squarespace/1.0/commerce/orders/{orderId} ``` #### Create Order ```bash POST /squarespace/1.0/commerce/orders Content-Type: application/json Idempotency-Key: unique-key-here { "channelName": "External Store", "externalOrderReference": "ORDER-12345", "customerEmail": "[REDACTED_SECRET]", "lineItems": [ { "lineItemType": "PHYSICAL_PRODUCT", "variantId": "variant-id", "quantity": 2, "unitPricePaid": {"currency": "USD", "value": "29.99"} } ], "subtotal": {"currency": "USD", "value": "59.98"}, "priceTaxInterpretation": "EXCLUSIVE", "grandTotal": {"currency": "USD", "value": "59.98"}, "createdOn": "2024-01-15T10:30:00Z" } ``` **Response:** 201 Created with Order object Note: `subtotal` must equal the sum of `lineItems.unitPricePaid.value * quantity`. #### Fulfill Order ```bash POST /squarespace/1.0/commerce/orders/{orderId}/fulfillments Content-Type: application/json { "shouldSendNotification": true, "shipments": [ { "shipDate": "2024-01-16T08:00:00Z", "carrierName": "USPS", "service": "Priority Mail", "trackingNumber": "9400111899223456789012", "trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012" } ] } ``` **Response:** 204 No Content on success --- ### Products #### List Store Pages ```bash GET /squarespace/1.0/commerce/store_pages ``` Query parameters: - `cursor` (optional): Pagination cursor **Response:** ```json { "storePages": [ { "id": "store-page-id", "title": "Main Store", "isEnabled": true, "urlSlug": "store" } ], "pagination": {...} } ``` #### List All Products ```bash GET /squarespace/v2/commerce/products ``` Query parameters: - `modifiedAfter` (optional): ISO 8601 datetime - `modifiedBefore` (optional): ISO 8601 datetime - `type` (optional): Comma-separated types: `PHYSICAL`, `SERVICE`, `GIFT_CARD`, `DIGITAL` - `cursor` (optional): Pagination cursor Note: Cannot combine cursor with date/type filters. **Response:** ```json { "products": [ { "id": "product-id", "type": "PHYSICAL", "storePageId": "store-page-id", "name": "Product Name", "description": "<p>HTML description</p>", "url": "https://example.squarespace.com/store/product-slug", "urlSlug": "product-slug", "tags": ["tag1", "tag2"], "isVisible": true, "variants": [...], "images": [...], "createdOn": "2024-01-01T00:00:00Z", "modifiedOn": "2024-01-15T12:00:00Z" } ], "pagination": {...} } ``` #### Get Specific Products ```bash GET /squarespace/v2/commerce/products/{productIds} ``` - `{productIds}`: Comma-separated product IDs (max 50) #### Create Product ```bash POST /squarespace/v2/commerce/products Content-Type: application/json { "type": "PHYSICAL", "storePageId": "store-page-id", "name": "New Product", "description": "<p>Product description</p>", "urlSlug": "new-product", "tags": ["new", "featured"], "isVisible": true, "variants": [ { "sku": "SKU-001", "pricing": { "basePrice": {"currency": "USD", "value": "49.99"} }, "stock": {"quantity": 100, "unlimited": false} } ] } ``` **Response:** 201 Created with Product object #### Update Product ```bash POST /squarespace/v2/commerce/products/{productId} Content-Type: application/json { "name": "Updated Product Name", "description": "<p>Updated description</p>", "isVisible": true, "tags": ["updated", "sale"] } ``` **Response:** 200 OK with Product object #### Delete Product ```bash DELETE /squarespace/v2/commerce/products/{productId} ``` **Response:** 204 No Content on success --- ### Product Variants #### Create Variant ```bash POST /squarespace/v2/commerce/products/{productId}/variants Content-Type: application/json { "sku": "SKU-002", "pricing": { "basePrice": {"currency": "USD", "value": "59.99"}, "salePrice": {"currency": "USD", "value": "49.99"}, "onSale": true }, "stock": {"quantity": 50, "unlimited": false}, "attributes": {"Size": "Large"}, "shippingMeasurements": { "weight": {"unit": "POUND", "value": 1.5}, "dimensions": {"unit": "INCH", "length": 10, "width": 8, "height": 4} } } ``` **Response:** 201 Created with ProductVariant object Note: To use `attributes`, the product must first have matching `variantAttributes` set via Update Product (e.g., `"variantAttributes": ["Size"]`). #### Update Variant ```bash POST /squarespace/v2/commerce/products/{productId}/variants/{variantId} Content-Type: application/json { "sku": "SKU-002-UPDATED", "pricing": { "basePrice": {"currency": "USD", "value": "64.99"}, "onSale": false } } ``` **Response:** 200 OK with ProductVariant object Note: Stock and images cannot be updated via this endpoint. #### Delete Variant ```bash DELETE /squarespace/v2/commerce/products/{productId}/variants/{variantId} ``` **Response:** 204 No Content on success Note: Cannot delete the only variant of a product. --- ### Product Images #### Upload Image ```bash POST /squarespace/v2/commerce/products/{productId}/images Content-Type: multipart/form-data curl "https://api.maton.ai/squarespace/v2/commerce/products/{productId}/images" \ -H "Authorization: Bearer $MATON_API_KEY" \ -H "User-Agent: MyClaude/1.0" \ -X POST \ -F file=@image.png ``` **Response:** 202 Accepted ```json { "imageId": "image-id" } ``` Requirements: - Dimensions: less than 60MP - File types: JPEG, JPG, PNG, GIF - Max file size: 20MB (under 500KB recommended) - Max 100 images per product #### Check Upload Status ```bash GET /squarespace/v2/commerce/products/{productId}/images/{imageId}/status ``` **Response:** ```json { "status": "PROCESSING" } ``` Status values: `PROCESSING`, `READY`, `ERROR` #### Update Image (Alt Text) ```bash POST /squarespace/v2/commerce/products/{productId}/images/{imageId} Content-Type: application/json { "altText": "Product image description" } ``` **Response:** 200 OK with ProductImage object #### Reorder Image ```bash POST /squarespace/v2/commerce/products/{productId}/images/{imageId}/order Content-Type: application/json { "afterImageId": "other-image-id" } ``` Use `null` for `afterImageId` to move image to the top. **Response:** 204 No Content #### Assign Image to Variant ```bash POST /squarespace/v2/commerce/products/{productId}/variants/{variantId}/image Content-Type: application/json { "imageId": "image-id" } ``` Use `null` for `imageId` to remove the image from the variant. **Response:** 204 No Content #### Delete Image ```bash DELETE /squarespace/v2/commerce/products/{productId}/images/{imageId} ``` **Response:** 204 No Content --- ### Profiles (Customers) #### List All Profiles ```bash GET /squarespace/1.0/profiles ``` Query parameters: - `cursor` (optional): Pagination cursor - `filter` (optional): Semicolon-separated filters (e.g., `isCustomer,true;hasAccount,true`) - `sortDirection` (optional): `asc` or `dsc` (default: `dsc`) - `sortField` (optional): `createdOn`, `id`, `email`, or `lastName` (default: `id`) Filter options: - `isCustomer,true` or `isCustomer,false` - `hasAccount,true` or `hasAccount,false` - `email,[REDACTED_SECRET]` **Response:** ```json { "profiles": [ { "id": "profile-id", "firstName": "John", "lastName": "Doe", "email": "[REDACTED_SECRET]", "hasAccount": true, "isCustomer": true, "createdOn": "2024-01-01T00:00:00Z", "address": { "address1": "123 Main St", "city": "New York", "state": "NY", "countryCode": "US", "postalCode": "10001" }, "acceptsMarketing": true, "transactionsSummary": { "orderCount": 5, "totalOrderAmount": {"value": "499.95", "currency": "USD"} } } ], "pagination": {...} } ``` #### Get Specific Profiles ```bash GET /squarespace/1.0/profiles/{profileIds} ``` - `{profileIds}`: Comma-separated profile IDs (max 50) --- ### Transactions #### List All Transactions ```bash GET /squarespace/1.0/commerce/transactions ``` Query parameters: - `modifiedAfter` (conditional): ISO 8601 datetime - required with `modifiedBefore` - `modifiedBefore` (conditional): ISO 8601 datetime - required with `modifiedAfter` - `cursor` (optional): Pagination cursor Note: Date filters must be used together (both `modifiedAfter` and `modifiedBefore` are required when filtering by date). **Response:** ```json { "documents": [ { "id": "document-id", "createdOn": "2024-01-15T10:30:00Z", "modifiedOn": "2024-01-15T12:00:00Z", "customerEmail": "[REDACTED_SECRET]", "salesOrderId": "order-id", "voided": false, "totalSales": {"value": "99.99", "currency": "USD"}, "totalNetSales": {"value": "99.99", "currency": "USD"}, "totalTaxes": {"value": "8.50", "currency": "USD"}, "total": {"value": "108.49", "currency": "USD"}, "payments": [ { "id": "payment-id", "amount": {"value": "108.49", "currency": "USD"}, "creditCardType": "VISA", "provider": "STRIPE", "paidOn": "2024-01-15T10:35:00Z" } ] } ], "pagination": {...} } ``` #### Get Specific Transactions ```bash GET /squarespace/1.0/commerce/transactions/{documentIds} ``` - `{documentIds}`: Comma-separated document IDs (max 50) --- ## Pagination Squarespace uses cursor-based pagination. Response includes: ```json { "pagination": { "hasNextPage": true, "nextPageCursor": "cursor-value", "nextPageUrl": "https://api.squarespace.com/..." } } ``` To get the next page, use the `cursor` parameter: ```bash GET /squarespace/v2/commerce/products?cursor=cursor-value ``` ## Code Examples ### JavaScript ```javascript const response = await fetch( 'https://api.maton.ai/squarespace/v2/commerce/products', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}`, 'User-Agent': 'MyClaude/1.0' } } ); const data = await response.json(); console.log(data.products); ``` ### Python ```python import os import requests response = requests.get( 'https://api.maton.ai/squarespace/v2/commerce/products', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'User-Agent': 'MyClaude/1.0' } ) products = response.json()['products'] ``` ## Notes - **Products API uses version `v2`** (e.g., [REDACTED_SECRET]) - Store Pages endpoint uses version `1.0` (e.g., `/squarespace/1.0/commerce/store_pages`) - Inventory, Orders, Profiles, and Transactions APIs use version `1.0` - All requests require a `User-Agent` header describing your application - Requests without a custom User-Agent are subject to stricter rate limits - Maximum 50 items per batch request (inventory, products, profiles, transactions) - Create Order has a stricter rate limit: 100 requests per hour per website - Idempotency-Key header is required for stock adjustments and order creation - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments ## Rate Limits - General: 300 requests per minute (5 per second) - Create Order: 100 requests per hour per website (with API key auth) - Exceeding limits returns 429 Too Many Requests with a one-minute cooldown ## Error Handling | Status | Meaning | |--------|---------| | 400 | Invalid request parameters or missing Squarespace connection | | 401 | Invalid or missing Maton API key | | 404 | Resource not found | | 405 | Method not allowed for product type | | 409 | Conflict (duplicate SKU, concurrent modification, etc.) | | 429 | Rate limited | | 4xx/5xx | Passthrough error from Squarespace API | ### Troubleshooting: API Key Issues 1. Check that the `MATON_API_KEY` environment variable is set: ```bash echo $MATON_API_KEY ``` 2. Verify the API key is valid by listing connections: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Troubleshooting: Invalid App Name Ensure your URL path starts with `squarespace`. For example: - Correct: `https://api.maton.ai/squarespace/1.0/commerce/products` - Incorrect: `https://api.maton.ai/1.0/commerce/products` ## Resources - [Squarespace Commerce APIs Overview](https://developers.squarespace.com/commerce-apis/overview) - [Inventory API](https://developers.squarespace.com/commerce-apis/inventory-overview) - [Orders API](https://developers.squarespace.com/commerce-apis/orders-overview) - [Products API](https://developers.squarespace.com/commerce-apis/products-overview) - [Profiles API](https://developers.squarespace.com/commerce-apis/profiles-overview) - [Transactions API](https://developers.squarespace.com/commerce-apis/transactions-overview) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[REDACTED_SECRET])


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)