Maton

Squarespace

Access the Squarespace Commerce API with managed OAuth authentication. Manage products, inventory, orders, customer profiles, and transactions.

Reference

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

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

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

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

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

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

Response: 204 No Content on success

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.

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

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)

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)

Resources

PreviousSnapchatNextSquare

On this page

Reference
List All Inventory
Get Specific Inventory
Adjust Stock Quantities
List All Orders
Get Specific Order
Create Order
Fulfill Order
List Store Pages
List All Products
Get Specific Products
Create Product
Update Product
Delete Product
Create Variant
Update Variant
Delete Variant
Upload Image
Check Upload Status
Update Image (Alt Text)
Reorder Image
Assign Image to Variant
Delete Image
List All Profiles
Get Specific Profiles
List All Transactions
Get Specific Transactions
Resources