🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Squarespace
πŸ¦€ ClawHub

Squarespace

by @byungkyu

Squarespace Commerce API integration with managed OAuth. Manage products, inventory, orders, customer profiles, and transactions. Use this skill when users w...

Versionv1.0.1
Downloads684
#crypto-defi#security#ecommerce#legal#productivity
TERMINAL
clawhub install squarespace

πŸ“– About This Skill

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

# 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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai 2. Go to maton.ai/settings 3. Copy your API key

Connection Management

Manage your Squarespace OAuth connections at https://api.maton.ai.

List Connections

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

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

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: 

{
  "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

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:

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

    GET /squarespace/1.0/commerce/inventory

    Query parameters:

  • cursor (optional): Pagination cursor from previous response

    • Response: 

    {
  "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

    GET /squarespace/1.0/commerce/inventory/{variantIds}

  • {variantIds}: Comma-separated variant IDs (max 50)

    • #### Adjust Stock Quantities

    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

    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: 

    {
  "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

    GET /squarespace/1.0/commerce/orders/{orderId}

    #### Create Order

    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

    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

    GET /squarespace/1.0/commerce/store_pages

    Query parameters:

  • cursor (optional): Pagination cursor

    • Response: 

    {
  "storePages": [
    {
      "id": "store-page-id",
      "title": "Main Store",
      "isEnabled": true,
      "urlSlug": "store"
    }
  ],
  "pagination": {...}
}

    #### List All Products

    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: 

    {
  "products": [
    {
      "id": "product-id",
      "type": "PHYSICAL",
      "storePageId": "store-page-id",
      "name": "Product Name",
      "description": "
    HTML description
    ",
      "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

    GET /squarespace/v2/commerce/products/{productIds}

  • {productIds}: Comma-separated product IDs (max 50)

    • #### Create Product

    POST /squarespace/v2/commerce/products
Content-Type: application/json
    {
  "type": "PHYSICAL",
  "storePageId": "store-page-id",
  "name": "New Product",
  "description": "
    Product description
    ",
  "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

    POST /squarespace/v2/commerce/products/{productId}
Content-Type: application/json
    {
  "name": "Updated Product Name",
  "description": "
    Updated description
    ",
  "isVisible": true,
  "tags": ["updated", "sale"]
}

    Response: 200 OK with Product object

    #### Delete Product

    DELETE /squarespace/v2/commerce/products/{productId}

    Response: 204 No Content on success

    Product Variants

    #### Create Variant

    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

    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

    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

    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 

    {
  "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

    GET /squarespace/v2/commerce/products/{productId}/images/{imageId}/status

    Response: 

    {
  "status": "PROCESSING"
}

    Status values: PROCESSING, READY, ERROR

    #### Update Image (Alt Text)

    POST /squarespace/v2/commerce/products/{productId}/images/{imageId}
Content-Type: application/json
    {
  "altText": "Product image description"
}

    Response: 200 OK with ProductImage object

    #### Reorder Image

    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

    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

    DELETE /squarespace/v2/commerce/products/{productId}/images/{imageId}

    Response: 204 No Content

    Profiles (Customers)

    #### List All Profiles

    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,customer@example.com

    • Response: 

    {
  "profiles": [
    {
      "id": "profile-id",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "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

    GET /squarespace/1.0/profiles/{profileIds}

  • {profileIds}: Comma-separated profile IDs (max 50)

    • Transactions

    #### List All Transactions

    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: 

    {
  "documents": [
    {
      "id": "document-id",
      "createdOn": "2024-01-15T10:30:00Z",
      "modifiedOn": "2024-01-15T12:00:00Z",
      "customerEmail": "customer@example.com",
      "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

    GET /squarespace/1.0/commerce/transactions/{documentIds}

  • {documentIds}: Comma-separated document IDs (max 50)

    • Pagination

    Squarespace uses cursor-based pagination. Response includes:

    {
  "pagination": {
    "hasNextPage": true,
    "nextPageCursor": "cursor-value",
    "nextPageUrl": "https://api.squarespace.com/..."
  }
}

    To get the next page, use the cursor parameter:

    GET /squarespace/v2/commerce/products?cursor=cursor-value

    Code Examples

    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

    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., /squarespace/v2/commerce/products)
  • 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:

    echo $MATON_API_KEY

    2. Verify the API key is valid by listing connections:

    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
  • Inventory API
  • Orders API
  • Products API
  • Profiles API
  • Transactions API
  • Maton Community
  • Maton Support

    • πŸ’‘ Examples

    # 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

    πŸ“‹ Tips & Best Practices

  • Products API uses version v2 (e.g., /squarespace/v2/commerce/products)
  • 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