Skip to navigation
Product Search

Squarespace

Beta

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.

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

Create a read-only Commerce API key in Squarespace.

2. Connect

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

3. Turn on 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

1

Open Developer API Keys

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

2

Generate the key

Select Generate key. Name it, for example Captain.

3

Set the permissions

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

4

Copy the key

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

Connect the store

1

Open the Squarespace card

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

2

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.

3

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 fieldCaptain field
Product nametitle
Product description (HTML removed)body
Variant attributes, e.g. Size: Largevariant_title, options, option_values
Product type (service, digital)product_type
Product tagstags
The product’s Store Page titlecollections
Product urlSlughandle
Product url, joined to your site addressurl
Product images, in their orderimages, image (the variant’s own image first)
Variant skusku
Variant gtinbarcode
Sale price while on sale, else base priceprice
Base price while on salecompare_at_price
Variant stock quantity (empty when unlimited)inventory, available
mpn, weight, dimensions, SEO title and descriptionattributes

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.

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:

<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

1

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.

3

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 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.