← All docs

Getting Started

1. Install the app

Install XSearch on your BigCommerce store. The install asks for four permissions:

  • Products (read/write) — reads your catalog for indexing, and writes when you use the bulk catalog tools
  • Store information (read) — store name, domain and currency
  • Channel settings (read) — your channels and which products are assigned to each
  • Sites & routes (read) — each storefront channel's web address, used to allow your storefront to call search and to link Storefront Preview to the right site

After OAuth completes, the admin opens inside your BigCommerce control panel.

2. Build your search index

Open the Dashboard and follow the Storefront launch checklist. Its Sync catalog step points you to the Re-Index button on the same page. XSearch pulls your full catalog — products, variants, custom fields, categories, brands and channel assignments — and builds your search index. Progress is shown live; large catalogs index in batches. Once the first index is built, product changes keep it current automatically (see the FAQ for timing).

3. Configure your filters

The Search Schema page lists every field found in your catalog. Choose which fields are filters (facets), their widget type and their order. Variant options such as Color and Size are made filters for you automatically. Facet choices show in Storefront Preview straight away and reach your live storefront within about 15 minutes, because storefront configuration is cached briefly. Changing a field's type or delimiter needs a reindex, and the page tells you when. See Schema & Facets.

4. Preview

Storefront Preview renders your search experience through the same API your storefront uses, so what you see is what shoppers get. Clicking a product opens it on that channel's storefront in a new tab.

5. Connect a Stencil storefront

Storefront delivery is included from the Starter plan up; on the free plan the public search API stays off (see Plans).

  1. Open Settings → Storefront API and turn the public endpoint on. If your storefront also answers on a custom domain that isn't listed, add it.
  2. Open Settings → Storefront Script and click Refresh from BigCommerce so XSearch reads your channels and their web addresses.
  3. Switch on the Stencil channel you want to enhance. XSearch adds its script to that storefront for you — it appears in Storefront → Script Manager as XSearch storefront search — and allows the storefront's address to call search. Switching the channel off, or uninstalling the app, removes the script. XSearch does not edit theme files.

If the card shows a message and a snippet instead of Added to this storefront automatically, XSearch couldn't add the script. Follow the message (usually: reopen the app from BigCommerce and approve the updated permissions), or paste the snippet into Script Manager yourself on Store pages, in the Footer.

Visit a category or search-results page to verify the product grid. Add ?xsearch=off to any storefront URL to compare the native theme listing or troubleshoot delivery.

6. Connect a headless storefront

Catalyst and other headless storefronts call the public search API with the store hash and channel ID. Turn the endpoint on and add the storefront's origin under Settings → Storefront API, then see the Catalyst integration guide.

If something doesn't look right, start with Troubleshooting.