Turn on storefront search

Create a public storefront key, paste it into the Captain Search app embed, and save the theme.

You’ll need: a connected store (see Install and connect), the catalog name, and either an owner of your Captain organization or a server with a write key.

Search on the storefront changes only after the app embed is on and saved in the live theme.

Create a storefront key

The key in the theme is public. Anyone can read it from the page source, so it has to be a scoped key, limited to the store’s catalog and the storefront’s addresses. A scoped key can search and send events, including purchases, for its catalog. It can’t read analytics or change records.

From the console

Open the Shopify connection’s Manage panel. Under Storefront search, select Create storefront key, and add the store’s own domains if it has any.

The panel shows the endpoint, the catalog and the key once, ready to paste. Only an owner of the organization can create the key.

From the API

On a server, use a write key for every index ("indexes": ["*"]) or the admin key:

curl -X POST "https://acme.captain.dev/v1/keys" \
  -H "Authorization: Bearer $CAPTAIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "scoped",
  "indexes": ["shopify-products"],
  "allowed_origins": ["https://your-store.myshopify.com", "https://www.your-store.com"],
  "description": "Shopify storefront search"
}'

• indexes holds the catalog the store connection created.
• allowed_origins lists every address the storefront runs on: the myshopify.com domain and any custom domain.
• The response holds the key once. Copy it straight into the app embed below.

Turn on the app embed

What shoppers see

The embed adds no search box, popup or branding. Shoppers use the theme’s own search. Captain decides which products appear and in what order.

• Search dropdown. As the shopper types, the theme’s suggestions dropdown lists the products Captain ranks highest, in Captain’s order, in the theme’s own style. Query suggestions, collections and pages in the dropdown still come from Shopify.

• Search results page. Pressing Enter opens the theme’s /search page. Its product grid shows Captain’s results, in Captain’s order, as the theme’s own product cards. The result count on the page and in the browser tab is Captain’s.

• Filters, sorting and pages. On the search page, these use Captain’s results, count and order:

  • filters for price, availability, vendor, product type, tag and product options;
  • sorting by price, title and date;
  • page 2 and later.

  The page reaches Captain’s first 240 products for a search. A few choices keep the whole page on Shopify’s own results: sorting by best selling, metafield filters, and a price filter when the storefront shows a currency other than the store’s.

• Keyboard and mobile. Arrow keys, Enter, Escape and the mobile search panel work exactly as the theme defines them. Keys pressed before the dropdown appears are held and replayed once it shows, so Arrow Down then Enter opens the highlighted product.

• Prices in the dropdown follow the theme’s own setting. In Dawn it’s Theme settings, then Search behavior, then Show product price. When the theme hides prices in the dropdown, Captain’s rows hide them too. Product cards on the search page show prices as the theme does.

• When Captain is slow or down, the theme shows Shopify’s own results instead. In the dropdown, Captain has 400 ms from each keystroke’s request (the Wait for Captain up to setting). On the search page it has 1.5 seconds, or three times that setting if that’s longer. An error from Captain falls back the same way, so search keeps working when Captain is down.

The embed changes only the theme’s search. Shopify search everywhere else, such as the Storefront API, other apps and other sales channels, stays as it is.

Which themes work