> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Squarespace

> Search your Squarespace store's products with Captain Product Search, kept in sync from the Squarespace Commerce APIs.

Connect a Squarespace store, and Captain imports its products into a new Captain catalog, keeps them in sync, and measures the revenue search brings in. A Captain search box goes on the store with one snippet.

> **Note**
>
> The Squarespace integration is in beta. It was tested end to end against a recorded copy of the platform's documented API, not yet against a live Squarespace site. Tell the Captain team on Slack before you connect a store you sell from.

## Quick start

#### [1. Make a key](#before-you-start)

Create a read-only Commerce API key in Squarespace.

#### [2. Connect](#connect-the-store)

Paste the key on the Squarespace card in the Captain console.

#### [3. Turn on search](#turn-on-storefront-search)

Create a storefront key and paste the search box into your site.

## How it works

* **The store connection** reads your products and orders through the Squarespace Commerce APIs with an API key you make. It only reads. It never changes your store.
* **The search box** is Captain's `<captain-search>` widget, pasted into your site. It searches the catalog the connection fills.

Orders feed the analytics: an order counts as assisted by search when the same shopper clicked that product in Captain's results first.

## Before you start

* A Squarespace site on the **Commerce Advanced** plan. Squarespace allows Commerce API keys only on that plan.
* Permission to manage the site's settings, to make the key.
* A Captain Product Search tenant with the Squarespace integration switched on. Captain switches it on per tenant.
* An owner of your Captain organization, to create the storefront key later.

### Make a read-only API key

### Open Developer API Keys

In Squarespace, open **Settings**, scroll down to **Advanced**, then select **Developer API Keys**.

### Generate the key

Select **Generate key**. Name it, for example `Captain`.

### Set the permissions

Under **Permissions**, give **Products** and **Orders** the **Read only** level. Captain needs nothing else.

### Copy the key

Squarespace shows the key once. Copy it now. It doesn't expire while the site is active.

## Connect the store

### Open the Squarespace card

In the Captain console, open **Developers**, then **Integrations**. On the **Squarespace** card, select **Connect**.

### Paste the key

Paste the key into **API key**. Captain tests it with read-only calls before it saves anything. A key without Products or Orders read is refused, and nothing is stored.

### Name the catalog

Keep the suggested catalog name or enter one no other catalog uses. The first import starts as soon as you connect.

Captain keeps the key in its secrets store only. It never shows it again, and it isn't in any log or reply.

## What syncs

Captain indexes a product only when a shopper can buy it:

* It is **visible**, and
* its **Store Page** is enabled.

Hidden products, products on a disabled Store Page, and gift cards stay out. Each variant is one record, and search groups variants by product. A download (digital) product has no variants, so it is one record.

| Squarespace field                                    | Captain field                                     |
| ---------------------------------------------------- | ------------------------------------------------- |
| Product `name`                                       | `title`                                           |
| Product `description` (HTML removed)                 | `body`                                            |
| Variant attributes, e.g. Size: Large                 | `variant_title`, `options`, `option_values`       |
| Product `type` (service, digital)                    | `product_type`                                    |
| Product `tags`                                       | `tags`                                            |
| The product's Store Page title                       | `collections`                                     |
| Product `urlSlug`                                    | `handle`                                          |
| Product `url`, joined to your site address           | `url`                                             |
| Product images, in their order                       | `images`, `image` (the variant's own image first) |
| Variant `sku`                                        | `sku`                                             |
| Variant `gtin`                                       | `barcode`                                         |
| Sale price while on sale, else base price            | `price`                                           |
| Base price while on sale                             | `compare_at_price`                                |
| Variant stock quantity (empty when unlimited)        | `inventory`, `available`                          |
| `mpn`, weight, dimensions, SEO title and description | `attributes`                                      |

### Orders

Captain reads orders that changed since the last sync. An order counts as revenue when its payment is **Paid** or **Partially paid**, it isn't a test-mode order, and it isn't canceled. For each one, Captain records one purchase event: the variants, their prices and quantities, the subtotal and currency, and an anonymous customer token. No names, emails or addresses.

## Live updates

Squarespace offers webhooks only to registered extensions, not to API keys. A key connection syncs on its schedule instead: every hour unless you change it, plus a full re-read at least once a day that removes products you deleted. **Sync now** runs one at any time.

## Turn on storefront search

### Create a storefront key

Open the Squarespace connection's **Manage** panel. Under **Storefront search**, select **Create storefront key**, and add any custom domains your site uses. The panel shows the snippet with the key filled in. Only an owner of the organization can create the key.

The snippet looks like this:

```html
<script type="module" src="https://cdn.jsdelivr.net/gh/runcaptain/captain-search@1.8.0/captain-search.js" integrity="sha384-..." crossorigin="anonymous"></script>

<captain-search
  endpoint="https://acme.captain.dev"
  index="squarespace-products"
  key="YOUR_SCOPED_KEY"
></captain-search>
```

### Add it to your site

### Load the script on every page

In Squarespace, open **Pages**, then **Website Tools**, then **Code Injection**. Paste the first line of the snippet (the `<script>` tag) into **Header**, and save.

### Place the search box

Edit the page where shoppers search, for example your shop page. Select **Add block**, choose **Code**, and paste the `<captain-search>` element.

### Check it

Save, then open the page in a private window and search.

Code Injection and Code blocks that run scripts need a Core, Plus or Advanced plan. Squarespace doesn't run custom code on checkout pages.

See [Search Widget](/guides/product-search/search-widget) for every option, such as placeholder text, dropdown or full results page, and colors.

## Sync now and Disconnect

* **Sync now** re-reads the whole catalog and the recent orders.
* **Disconnect** stops syncing and deletes the key from Captain. The catalog stays, so search keeps working until you delete it. To revoke the key in Squarespace too, delete it under **Developer API Keys**.

## Troubleshooting

* **"Squarespace refused the credentials".** The key was deleted, or it lacks Products or Orders read. Make a new key with both and reconnect.
* **A product is missing.** Check that it is visible and that its Store Page is enabled. Gift cards are never indexed.
* **A change hasn't shown up.** Changes arrive with the next hourly sync. Select **Sync now** to read them at once.
* **"rate limiting Captain".** Squarespace allows 300 requests a minute per site, shared with your other apps. Captain waits and continues on the next sync.
* **The search box doesn't appear.** Check that the script line is in Code Injection, Header, and that your plan allows custom code.