Shopify Integration

Add SearchX to a Shopify store — search bar in the header, a full results page at /search, and Add to Cart — using Custom Liquid sections. No app install required.

Overview

SearchX on Shopify has two independent halves, and you need both:

• Catalog (data). Your Shopify products have to be imported into your SearchX index. SearchX imports a product feed in Google Merchant (XML) format, so you generate that feed with a feed app and point SearchX at its URL.
• Storefront (UI). SearchX is a JavaScript widget that mounts into <div> containers inside your theme. You add it through Custom Liquid sections — one in the header for the search bar, one on the search template for the results page.

The UI without an index shows empty results; the index without the UI is invisible. Set up the catalog first, then the storefront.

Requirements

• A SearchX application with an App ID and a public API / search key (the key that ships to the browser — never a private/admin key).
• A Shopify store with an Online Store 2.0 theme and Customize theme (or Edit code) access.
• A feed app that produces a Google Merchant XML feed (see Step 1).

At a glance

The whole integration is five steps:

1. Build a product feed and import it into SearchX (Steps 1.1–1.3).
2. Connect the feed and set your store's Origin URL in the SearchX dashboard (Steps 1.4–1.5).
3. Paste the header snippet into a Custom Liquid section in your theme's Header group (Step 2).
4. Add a results container on the Search template and hide the native search (Step 3).
5. Test search and Add to Cart (Step 4 and the Checklist).

The only values that are truly unique to you are your App ID, your public API key, and your store's Origin URL. Everything else in the snippet works as-is — styling and language are optional. The exact placeholders to change are listed under What to replace in Step 2.

Step 1: Get your catalog into SearchX

Shopify does not expose a downloadable XML feed at a stable URL on its own, so you use a feed app to generate one.

1.1 Install a feed app

Any Google Merchant feed app works — for example Pify Google Shopping Feed, Omega, AdNabu, Simprosys, or Channable. They all follow the same idea: they build an XML file at a URL you can hand to SearchX.

1.2 Configure the feed (important)

These settings make the feed compatible with SearchX and with Add to Cart. In Pify they live under Global Settings and Create Feed → Base Settings; other apps have equivalents.

1.3 Generate and check the feed

1. Build the feed, then Regenerate for an instant build (otherwise it builds on the app's next scheduled cycle).
2. Wait until the item count is greater than 0 and a feed link appears (a .xml URL).
3. Open the URL and confirm: <g:id> is a plain number (the variant id), each variant is its own <item> sharing one <g:item_group_id>, and <g:price> looks like 120.00 USD.

1.4 Connect the feed to SearchX

In the SearchX dashboard, on your application, set the XML feed type to Google and the feed URL to the .xml link from your feed app, then run the import. SearchX downloads the feed, parses it, and builds your search index.

1.5 Filterable attributes

In your SearchX application settings, make sure sizes, color, brand, and price are listed as filterable attributes, or the Brands / Sizes / Price-range facets won't filter.

Step 2: Add the search bar to the header

The widget loads once, site-wide, from a Custom Liquid section inside the Header group (the header renders on every page, so the widget is available everywhere).

1. Online Store → Themes → Customize.
2. In the Header group, choose Add section → Custom Liquid.
3. Paste the snippet below into the Liquid code field and Save. Replace YOUR_APP_ID, YOUR_PUBLIC_API_KEY, and customCSSUrl with your own values.

<style>
  /* Desktop: breathing room under the bar */
  @media (min-width: 750px) {
    #searchx-search-bar {
      margin-bottom: 28px;
      margin-top: 28px;
    }
  }
</style>

<!-- Hide the theme's native search icon so SearchX is the only search entry -->
<script>
  (function () {
    function hide() {
      document.querySelectorAll('.header-actions__action').forEach(function (b) {
        var a = (b.getAttribute('aria-label') || '').toLowerCase();
        if (a.indexOf('search') > -1) b.style.display = 'none';
      });
    }
    hide();
    document.addEventListener('DOMContentLoaded', hide);
    window.addEventListener('load', hide);
  })();
</script>

<!-- Where the search bar mounts -->
<div id="searchx-search-bar"></div>

<!-- Your credentials and options -->
<script>
  window.__SearchXDemo = {
    app_id: 'YOUR_APP_ID',
    api_key: 'YOUR_PUBLIC_API_KEY',
    apiPageURL: 'https://admin.searchxengine.ai/api/v1',
    customCSSUrl: 'https://your-cdn.example.com/searchx-theme.css',
    defaultLanguage: 'en',
    searchPageURL: '/search',
    cartAddUrl: '/cart/add.js',
  };
</script>

<!-- React + ReactDOM + SearchX SDK (CDN, deferred) -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js" defer></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js" defer></script>
<script src="https://sdk.searchxengine.ai/searchx-sdk.umd.js" defer></script>

<!-- Boot the SDK + bridge Add to Cart to Shopify -->
<script defer>
  (function () {
    var cfg = window.__SearchXDemo;
    function ready() {
      return (
        window.SearchXSDK &&
        typeof window.SearchXSDK.init === 'function' &&
        window.React &&
        window.ReactDOM
      );
    }
    function present(id) {
      return document.getElementById(id);
    }
    var booted = false;
    function boot() {
      if (booted) return;
      var components = {};
      if (present('searchx-search-bar')) components.SearchBar = { root: 'searchx-search-bar' };
      if (present('searchx-search-page')) components.SearchPage = { root: 'searchx-search-page' };
      if (!Object.keys(components).length) return;
      window.SearchXSDK.init({
        app_id: cfg.app_id,
        api_key: cfg.api_key,
        apiPageURL: cfg.apiPageURL,
        defaultLanguage: cfg.defaultLanguage,
        components: components,
        settings: {
          platform: 'custom',
          searchPageURL: cfg.searchPageURL,
          aiSearchEnabled: true,
          showAddToCartButton: true,
          showPopupAddToCart: true,
          showBrand: true,
          showColorFilter: true,
          showSizeFilter: true,
          showPriceRangeFilter: true,
          mobileViewPort: '750px',
        },
        customCSSUrl: cfg.customCSSUrl,
      });
      booted = true;
    }
    var tries = 0;
    function wait() {
      if (ready()) {
        boot();
        return;
      }
      if (tries++ > 150) return;
      setTimeout(wait, 100);
    }

    // Add to Cart bridge — see Step 4
    window.addEventListener('SearchX:addToCart', function (e) {
      var product = (e && e.detail && e.detail.product) || {};
      var id = product.unique_id || product.variant_id || product.id;
      if (!id) return;
      var drawer =
        document.querySelector('cart-drawer') || document.querySelector('cart-notification');
      var body = { items: [{ id: id, quantity: 1 }] };
      if (drawer && typeof drawer.getSectionsToRender === 'function') {
        try {
          var ids = drawer
            .getSectionsToRender()
            .map(function (s) {
              return s.section || s.id;
            })
            .filter(Boolean);
          if (ids.length) {
            body.sections = ids;
            body.sections_url = window.location.pathname;
          }
        } catch (_) {}
      }
      fetch(cfg.cartAddUrl, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
        body: JSON.stringify(body),
      })
        .then(function (r) {
          return r.json().then(function (data) {
            return { ok: r.ok, data: data };
          });
        })
        .then(function (res) {
          if (!res.ok) {
            // Add failed (invalid variant, out of stock, ...): leave the cart UI untouched
            window.dispatchEvent(new CustomEvent('SearchX:addToCartError', { detail: res.data }));
            return;
          }
          var data = res.data;
          if (drawer && typeof drawer.renderContents === 'function') {
            drawer.renderContents(data);
            if (typeof drawer.open === 'function') {
              try {
                drawer.open();
              } catch (_) {}
            }
            return;
          }
          document.dispatchEvent(new CustomEvent('cart:refresh', { bubbles: true }));
          window.dispatchEvent(new CustomEvent('SearchX:cartUpdated', { detail: data }));
          var toggle = document.querySelector(
            '.js-drawer-open-cart,[data-cart-toggle],a[href="#cart"]',
          );
          if (toggle) {
            toggle.click();
            return;
          }
          window.location.reload();
        })
        .catch(function () {
          window.location.reload();
        });
    });

    if (document.readyState === 'loading') {
      document.addEventListener('DOMContentLoaded', wait);
    } else {
      wait();
    }
  })();
</script>

What the key options do:

• platform: 'custom' — the widget does not write to the cart itself; it fires a SearchX:addToCart event that the snippet handles (Step 4).
• searchPageURL: '/search' — pressing Enter sends the shopper to the results page (Step 3).
• mobileViewPort: '750px' — below this width the widget collapses to a compact magnifier (Step 5). The key is mobileViewPort (camelCase); any other spelling is ignored and falls back to the default.
• customCSSUrl — an external stylesheet that themes the widget itself (colours, cards, buttons), separate from the layout CSS in the <style> block.

What to replace (and where to find it)

Leave these unchanged: apiPageURL, the three CDN <script> URLs, cartAddUrl (/cart/add.js is Shopify-standard), and the boot + Add to Cart logic.

Step 3: Results page at /search

You want /search to show only SearchX, not the theme's native search.

1. In Customize, switch the template selector (top centre) to Search.

2. In the Template group, Add section → Custom Liquid and set its Liquid code to just:

   <div id="searchx-search-page"></div>
   

   Copy

   The SDK is already loaded by the header, so it mounts the results page here automatically.

3. Save.

Then hide the theme's native search on this template: in the Template group there are usually two native sections — Search (title + input) and Search results (the grid). Select each, open the ⋯ menu, and choose Hide. After that, /search shows only the SearchX results page with its facets, sorting, and pagination.

Step 4: Add to Cart

When a shopper clicks Add to Cart on a result, the widget fires:

window.dispatchEvent(new CustomEvent('SearchX:addToCart', { detail: { product: item } }));

The snippet listens for that event and always adds the item with a POST to Shopify's /cart/add.js. It then tries to refresh the cart UI, in this order:

1. Live drawer update (best-effort). If the theme exposes a compatible cart drawer (<cart-drawer> or <cart-notification> with Shopify's Section Rendering hooks, as in some Dawn-family themes), the snippet requests the re-rendered drawer HTML and tries to update and open the drawer without a reload.
2. Otherwise it broadcasts common cart events and tries to open a cart toggle.
3. If neither applies, it reloads the page so the cart updates.

Shopify has no native wishlist, so the heart action is forwarded as a SearchX:wishlistRequested event you can hook into a wishlist app.

Step 5: Layout and mobile

All layout CSS lives in the <style> block at the top of the header Custom Liquid. Because the header renders everywhere, this CSS applies site-wide.

Desktop spacing

@media (min-width: 750px) {
  #searchx-search-bar {
    margin-bottom: 28px;
    margin-top: 28px;
  }
}

Mobile: stick the magnifier to the header

Below mobileViewPort (750px), the widget shows a compact magnifier instead of a full bar. You want it in the header row next to the burger, and staying with the header as the shopper scrolls.

The catch: in Horizon (and most Online Store 2.0 themes) only the <header> element is position: sticky — your Custom Liquid section is a sibling below it, not a child. So position: absolute or fixed won't stick: absolute is anchored to the page and scrolls away, and fixed pulls the section out of flow so its full-width background covers your content.

The fix is to make your section sticky too, pull it up into the header row, and cancel that pull so the rest of the page doesn't shift:

@media (max-width: 749px) {
  #shopify-section-sections--XXXX__custom_liquid_YYYY {
    position: sticky;
    top: -1px; /* match Horizon's sticky header offset */
    z-index: 9; /* above the header (its z-index is 8) */
    height: 0; /* no extra row */
    margin-top: -52px; /* pull the icon up into the header row */
    margin-bottom: 52px; /* cancel the pull so page content doesn't shift */
    overflow: visible;
  }
  #shopify-section-sections--XXXX__custom_liquid_YYYY .searchx__container {
    width: auto !important;
    justify-content: flex-start;
    margin-left: 21px; /* sit to the right of the burger */
    margin-top: 8px; /* fine vertical nudge, before the header is stuck */
  }
  /* When the header pins, Horizon shifts it a few px — nudge the icon to match */
  #shopify-section-sections--XXXX__custom_liquid_YYYY.sx-stuck .searchx__container {
    margin-top: 14px;
  }
  #searchx-search-bar {
    width: auto !important;
  }
}

Track the stuck state

CSS can't tell whether a sticky element is currently pinned, and Horizon's header shifts by a few pixels once it sticks — so the icon needs a slightly different margin-top at rest vs stuck. A tiny script adds an sx-stuck class to your own section while it's pinned (it only toggles a class on your element — it never touches the theme's header DOM). Add it once inside the header Custom Liquid:

<script>
  (function () {
    var sec = document.getElementById('shopify-section-sections--XXXX__custom_liquid_YYYY');
    if (!sec) return;
    function update() {
      sec.classList.toggle('sx-stuck', sec.getBoundingClientRect().top <= 0);
    }
    window.addEventListener('scroll', update, { passive: true });
    window.addEventListener('resize', update);
    update();
  })();
</script>

How to tune it:

• Vertical (coarse): change the section's margin-top and margin-bottom together to the same magnitude — a larger negative margin-top (with an equal positive margin-bottom) lifts the icon higher without shifting page content.
• Vertical (fine): the container's margin-top — set the rest value, and the .sx-stuck value for when the header is pinned.
• Horizontal: the container's margin-left.
• Still hidden behind the header? raise z-index (the header is 8).

The section id is unique to your store — find it from the Customize URL (?section=...) when the section is selected, or in the storefront with:

document.getElementById('searchx-search-bar').closest('.shopify-section').id;

Settings reference

The most common settings you'll tune in the snippet:

For the full list of options, see the SDK Reference and Search Settings.

Troubleshooting

Checklist

1. Feed app installed, configured per Step 1.2, Regenerated, .xml URL obtained.
2. Feed verified: g:id is the variant id.
3. SearchX application: feed type Google, feed URL set, import run.
4. Filterable attributes: sizes, color, brand, price.
5. Header group → Custom Liquid → header snippet pasted with your credentials.
6. Search template → Custom Liquid with #searchx-search-page.
7. Native Search + Search results sections hidden.
8. Test: search → results → Add to Cart updates the cart.
9. Desktop spacing and mobile magnifier positioned.