squarespace

What this skill does

# 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": "[email protected]",
      "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": "[email protected]",
  "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:
- `m