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

# Troubleshooting and good to know

> Fixes for common Captain Search problems on Shopify, and the limits of the beta.

Find your symptom below, then check the limits of the beta under [Good to know](#good-to-know).

**You'll need:** a private browser window for testing, and the browser's developer tools for a few checks.

## Troubleshooting

#### Search works in the theme editor but not on the live store

Theme editor changes apply only after **Save**, and only to the theme you made them in.

* Check that **Captain Search** is turned on in the live theme.
* Check that its settings are filled in and the theme is saved.
* Test in a private window.

#### Search shows the store's usual results instead of Captain's

The theme falls back to Shopify's results when Captain fails or is too slow.

To see which results are showing, open the browser's developer tools. Captain's results carry the attribute `data-captain-results` on the dropdown's product list (`#predictive-search-results-products-list`) and on the search page's grid (`#product-grid`). Then check the request to `/v1/indexes/{index}/search`:

* `403` means the key doesn't allow this storefront address or this catalog. Add every storefront address to the key's `allowed_origins`, including a custom domain, and check that the key's catalog matches **Product index**.
* `401` means the key is wrong, revoked or expired. Create a new scoped key and save it in the app embed.

#### Nothing changes on the storefront

The embed stays off when a setting is missing or invalid, and the theme keeps Shopify's own search. If the theme still shows Shopify's results, set **Product item selector (advanced)** (see [Which themes work](/guides/product-search/shopify/storefront-search#which-themes-work)).

* The endpoint must be an HTTPS address with no path.
* The catalog name may contain only letters, digits, `-` and `_`.
* The key must not be empty.

#### A product is missing from results

Check that the product is Active, published to the Online Store sales channel, and that its publish date has passed. Then run **Sync now** on the connection and search again after it finishes.

#### A deleted or unpublished product still appears

Run **Sync now**. The next successful scheduled resync also removes it. If the connection shows **Failing**, fix the error it names first.

#### Clicks or orders aren't attributed

Attribution needs the shopper's analytics consent. Check that the store's consent banner is on and that your test shopper accepted analytics. For express checkout orders, the credit can appear a little after the order, once the pixel's checkout report arrives.

## Good to know

* The app is in beta and not in the Shopify App Store. Captain installs it store by store.
* On the search page, sorting by best selling, metafield filters, and a price filter in a currency other than the store's show Shopify's own results.
* The search page reaches Captain's first 240 products for a search.
* Captain's product cards on the search page link to the product and leave out the theme's quick-add button.
* The result count and the no-results message the embed writes follow the storefront's language, in 31 languages. Only English has been shown on a live store so far.
* When the storefront shows a different currency from the catalog's, the embed hides Captain's prices rather than show the wrong currency.
* The first import reads the last 60 days of orders. Each Shopify connection shows how far back its orders go and why. Importing up to 365 days needs Shopify's approval for `read_all_orders`, which Captain hasn't received yet.
* A cancellation or refund of an order recorded before 20 October 2026 is subtracted only when that shopper didn't allow analytics. Otherwise the order keeps its original value.
* Captain answers Shopify customer data requests by hand.