# Squarespace Commerce MCP

> Squarespace Commerce connects your backend operations directly to your AI client. You can manipulate inventory stock levels, pull complete customer records, track pending orders, and mark shipments as fulfilled—all via natural language commands.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** inventory-tracking, order-fulfillment, product-catalog, headless-cms, shipping-logistics, data-sync

## Description

You can run your core Squarespace Commerce tasks right through your AI client, ditching the need to log into the visual dashboard just to check a stock count or mark an order shipped. This server gives your agent direct access to manipulate inventory, pull customer records, and track every pending order using natural language commands.

**Handling Orders and Fulfillment:**
To start, you'll use `list_orders` to pull a paginated list of all submitted commerce orders waiting for attention. Once your client finds the specific shipment it needs to deal with, it pulls comprehensive data for that single sale by calling `get_order_details`. If you need to know what products or variables are attached to an individual item, you can get granular metadata using `get_product_details` against a specific product ID. When it's time to ship, your agent marks the order as fulfilled—it uses `fulfill_order`, which requires the order’s ID, the tracking number, and the carrier name. You're always in control of that final status update.

**Managing Inventory and Product Stock:**
Don't guess what you've got; run `list_inventory` to get an audit of every single product variant's current stock count across the whole store. If a physical item comes back, or if you need to adjust for damaged goods, your client can change the stock level for any specific product variant ID using `adjust_inventory`. This function only needs two things: the ID and the delta (if it's coming in, that's a plus; if it's sold, that’s a minus).
For general catalog awareness, you can pull basic names and IDs for every product listed by running `list_products`.

**Pulling Customer and Financial Data:**
To get an overview of your client base, use `list_customer_profiles`. This returns a list of all registered customer accounts and their associated data. If you need to track the money coming in or going out, run `list_transactions`; it provides a full log of every financial transaction processed through the platform.

**System Oversight:**
If you're debugging the store setup, your agent can list current webhook subscriptions configured for the store using `list_webhooks`. This gives you visibility into how external systems are communicating with Squarespace Commerce. You’ve got everything here—from checking inventory levels across hundreds of variants to marking a shipment as done and updating the backend status.

## Tools

### adjust_inventory
Changes the stock count for a specific product variant ID, requiring a delta (+ or -) and ID.

### fulfill_order
Marks an order as shipped using its ID, tracking number, and carrier name.

### get_order_details
Retrieves all specific information for a single submitted order.

### get_product_details
Gets deep, granular metadata and variables for one specific product ID.

### list_customer_profiles
Returns a list of all customer profiles registered with Squarespace Commerce.

### list_inventory
Lists the current stock count for every tracked product variant in the store.

### list_orders
Retrieves a paginated list of all submitted commerce orders.

### list_products
Returns basic names and IDs for all products listed in the store catalog.

### list_transactions
Provides a log of all financial transactions processed through the platform.

### list_webhooks
Lists the current webhook subscriptions configured for the store.

## Prompt Examples

**Prompt:** 
```
Scan the current order list and figure out exactly which items are marked as pending fulfillment.
```

**Response:** 
```
Cycling via `list_orders` returning unresolved tickets:

1. 📦 **Order #62Bf (Pending/Open)** - Customer: Alice Lee - Value: $140.00
2. 📦 **Order #12Zx (Pending/Open)** - Customer: John M. - Value: $40.50

The rest of the transactions present in this pagination phase are cleanly fulfilled. Tell me the ID string if you want to apply a Courier track to any.
```

**Prompt:** 
```
Tell me the inner variant IDs attached to my product item tagged 'Winter Coat X5'. Our main store sells roughly 5 jackets.
```

**Response:** 
```
Invoked iterative search through `list_products` extracting 'Winter Coat X5' locating Primary ID object ~ `12abcd56`. Next requested Deep Metadata firing `get_product_details` to return your variables.

Here are the variants bound inside your Coat Parent Wrapper:
- **Variant A**: 'Black / Large' -> Variant ID: `vxA001` (Stock: 5)
- **Variant B**: 'Grey / Medium' -> Variant ID: `vxB004` (Stock: 2)

You can explicitly demand an inventory adjustment on these ID signatures via this interface freely.
```

**Prompt:** 
```
We just sold a 'Grey / Medium' offline to a friend. Adjust its variant inventory quantity ID vxB004 by -1 unit securely.
```

**Response:** 
```
Initializing an update request securely wrapping bounds connecting onto backend. Target Node `adjust_inventory` applied. 

**STATUS: ADJUSTMENT FINALIZED ✅**
Associated Variant: `vxB004`
Adjustment Processed: `-1 Unit Subtract`

The Squarespace backend accepted structural changes. Your active live stock now officially reflects 1 physical good available seamlessly avoiding overselling.
```

## Capabilities

### Process and track order fulfillment
Marks an order as shipped, records tracking numbers, and updates the status in the backend.

### Manage product stock levels
Adjusts the count of any specific product variant by a set quantity delta (+ or -).

### Retrieve detailed order records
Pulls comprehensive data for one specific order, including customer and item details.

### Audit full catalog inventory
Lists current stock levels across all product variants in the system.

### Pull customer purchase history
Retrieves a list of all registered Squarespace customer profiles and their associated data.

## Use Cases

### Identifying stuck shipments
An Ops Manager needs to find all orders pending shipment that haven't been touched in two days. They prompt their agent: 'Scan the current order list and flag everything open for 48+ hours.' The agent calls `list_orders`, filters the results, and lists only the unresolved tickets, saving manual database queries.

### Quickly adjusting stock after an offline sale
A Store Owner sells a jacket 'offline' to a friend. Instead of manually logging into inventory management, they ask their agent: 'Decrement the Grey/Medium variant (ID vxB004) by 1.' The agent runs `adjust_inventory` and confirms the new stock count.

### Creating a low-stock report
A developer needs to build an inventory report. They tell the agent: 'List all products, then check their current stock.' The agent calls `list_products` and immediately follows up with `list_inventory`, returning a merged list of items that need reordering.

### Investigating a complex order failure
A customer reports an issue with Order #123. The agent first calls `get_order_details` to confirm the contents and shipping address, then runs `list_transactions` against that order ID to see if payment cleared correctly.

## Benefits

- Automate dispatch approvals: Instead of manually checking dashboards, the agent processes `fulfill_order` based on simple logic parameters over a chat prompt. This handles repetitive shipping tasks instantly.
- Immediate inventory visibility: Run `list_inventory` to get a real-time audit of every physical stock item without navigating product pages. You know exactly what you have.
- Deep customer insight: Calling `list_customer_profiles` pulls shopper history, letting your agent analyze past behavior before recommending restocking or sales promotions.
- Full order lifecycle tracking: Use `list_orders` to pinpoint all pending commercial shipments, then use `get_order_details` to gather the necessary information for fulfillment.
- Financial oversight: Cross-reference operational status with money flow. The `list_transactions` tool provides a pure data stream of bank activity alongside order records.

## How It Works

The bottom line is: you tell your AI client what needs doing—like 'fulfill order #123'—and it runs the necessary APIs to make it happen.

1. Enable the MCP bridge on your environment and provide your primary Squarespace Developer API Key.
2. Your AI client calls specific tools (e.g., `list_orders`) to gather data by reading the live backend state.
3. The agent executes the task based on the gathered data, returning the final result or confirmation of changes.

## Frequently Asked Questions

**How do I adjust inventory using the adjust_inventory tool?**
You must provide three things: the specific variant ID, a quantity delta (the number to change), and confirmation of the action. Example: 'Increase stock for `vxB004` by 10' runs `adjust_inventory`.

**What is the difference between list_products and get_product_details?**
`list_products` gives you a basic roster of product names and IDs. Use it to see what exists in your catalog. Use `get_product_details` when you need deep variables, like specific variant dimensions or complex metadata for one item.

**Does list_orders show me the payment status?**
Yes, `list_orders` gives you the basic order summary. For full financial details, use `get_order_details`. If you need a pure log of all bank movements over time, run `list_transactions`.

**Can I track shipments using fulfill_order?**
Yes, the `fulfill_order` tool requires an order ID, tracking number, and carrier name. Running this marks the order as shipped and attaches that crucial tracking data to the record.

**How do I use the cursor when calling `list_orders` to fetch all pending orders?**
You pass the cursor from the previous response into your next call. This mechanism ensures you retrieve every order record, regardless of how many pages Vinkius returns. It’s crucial for running comprehensive reports on old or high-volume inventory.

**What specific financial records are returned by `list_transactions`?**
The tool lists general financial transactions recorded against the store. This data stream provides visibility into overall bank flow and sale amounts, but it doesn't provide full credit card numbers or highly sensitive payment details.

**If an SKU fails validation during `adjust_inventory`, what error message do I receive?**
The system returns a specific failure code indicating the exact reason for the rejection. This usually means the provided variant ID is invalid or the quantity delta violates existing store rules. You'll need to correct one of those two inputs.

**What credentials are needed to enable access when using `get_product_details`?**
You must provide your overarching Squarespace Developer API Key. This key authorizes your AI client to query the product data and read deep catalog hierarchies on your behalf.

**Can the AI add inventory if a new shipment of stock arrives?**
Yes. Once you know the `variant_id` representing your SKU item (extracted from `get_product_details`), simply instruct the AI: "Add +10 to the stock of this variant". The AI securely triggers `adjust_inventory` scaling up the quantities actively across your storefront.

**Am I able to finalize orders automatically feeding a Tracking ID string?**
Yes! Use the `fulfill_order` command naturally. Pass the order ID, the postal tracking number, and specify the dispatch carrier (FedEx, UPS, etc). The workflow marks the backend as satisfied natively informing Squarespace.

**How detailed is the product variant readout locally?**
By executing `get_product_details`, the agent drops deep metadata directly inline. You get descriptions, arrays mapping every single variant SKU attached, full pricing metrics (sale versus original tags), images context arrays, visibility flags, and physical weight calculations.