squarespace
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).
安装 / 下载方式
TotalClaw CLI推荐
totalclaw install github:LeoYeAI~openclaw-master-skills~squarespacecURL直接下载，无需登录
curl -fsSL https://skills.taituai.com/api/skills/github%3ALeoYeAI~openclaw-master-skills~squarespace/file -o squarespace.md# 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://gateway.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://gateway.maton.ai/squarespace/{native-api-path}
```
Replace `{native-api-path}` with the actual Squarespace API endpoint path. The gateway 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://ctrl.maton.ai`.
### List Connections
```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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://ctrl.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://ctrl.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": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"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://ctrl.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://gateway.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', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```
If omitted, the gateway uses the default (oldest) active connection.
## 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": "customer@example.com",
"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": "customer@example.com",
"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:
- `mo