WooCommerce Integration

Drop SearchX into your WooCommerce store in a few minutes using the official SearchX for WooCommerce plugin.

Overview

The SearchX for WooCommerce plugin is available on the official WordPress.org Plugin Directory and packages everything you need into a single WordPress plugin:

• Two shortcodes: [searchx_bar] for the search bar and [searchx_page] for the full results page. Drop them into pages, posts, headers, widgets, or page-builder templates.
• A dedicated settings tab at WooCommerce > Settings > SearchX with every widget option grouped logically, no code editing required.
• A built-in server-side proxy that keeps your private API key on the server. The browser only ever sees a placeholder, so the key never leaks into page source or browser dev tools.
• Automatic Add to Cart that uses WooCommerce's native cart URL, so the cart updates exactly as it would from any other product page.
• Automatic Wishlist support when YITH WooCommerce Wishlist is active.
• HPOS + Cart & Checkout Blocks compatibility declared, so WooCommerce won't flag the plugin as incompatible on modern stores.

Step 1: Install the plugin

The fastest path is straight from the WordPress.org directory:

1. In WordPress, go to Plugins > Add New.
2. Search for searchx.
3. Find SearchX for WooCommerce, click Install Now, then Activate.

That's it for installation. The plugin doesn't activate any storefront changes yet; it waits for you to fill in your credentials in step 2.

Alternative: upload the zip from your SearchX admin

You can also download the plugin zip directly from your SearchX dashboard: open your application, go to the Details tab, scroll to Integration Instructions, pick the WooCommerce tab, and click Download SearchX for WooCommerce plugin.

Then upload it in WordPress via Plugins > Add New > Upload Plugin, click Install Now, and Activate.

Step 2: Configure your credentials

Open WooCommerce > Settings > SearchX. The tab is organised into six sections that mirror the SearchX dashboard, so fill in only what you need.

Credentials

Paste the App ID and API key from your SearchX dashboard. The API URL defaults to production and rarely needs to change.

After saving you should see the standard WordPress confirmation:

Layout & behaviour

Search bar popup

Product cards

Filter sidebar

Labels & suggestions

Override the default button text. Leave blank to use the SearchX defaults.

Step 3: Replace your storefront search bar

Add the search bar shortcode where your current site search lives. Typical locations:

• Your theme's header (in a header builder, custom HTML widget, or a header template part).
• A WooCommerce-block-based header pattern.
• The site-wide widget area used by your theme for navigation.

[searchx_bar]

Reload the storefront and the SearchX bar takes the place of your search box:

Focusing the bar opens the popup with recent searches, top searches and featured products before the shopper even types:

You can use the shortcode up to 3 times on the same page out of the box (e.g. desktop header + mobile drawer + secondary location). Each instance gets its own root automatically.

Step 4: Create the search results page

Create or pick the page that will display the full SearchX results page, then drop the page shortcode in:

[searchx_page]

Option A: Use the default path. Create a page at /searchx. The search bar's default Search page path matches, so you're done.

Option B: Use a different path or an existing page. Add the shortcode to that page, copy its URL path, then open WooCommerce > Settings > SearchX, set the Search page path field to that path, and save. The search bar will now redirect there.

Step 5: Test on the storefront

Run through this quick checklist:

1. Open the storefront and type a product keyword into the SearchX bar; instant results should appear as you type.
2. Try a misspelled query (e.g. ipone) to confirm typo tolerance.
3. Open the full results page and test the category, brand, price, size and colour filters configured for your catalog.
4. Add a product to the cart straight from the results.
5. Test on mobile.

Open your browser's developer tools and look at the network panel. You'll see requests going to /wp-json/searchx/v1/proxy (your WordPress site), not directly to the SearchX API. This is the built-in proxy in action: your private API key stays on the server.

Your catalog and analytics

The plugin renders the search experience; your catalog and insights live in the SearchX admin:

• Catalog: products are imported from your product XML feed (Google Merchant Center, Facebook or Skroutz format) and re-synced automatically on your schedule (hourly or daily). The plugin never reads the WooCommerce database. See Product Import.

• Analytics: every search feeds the real-time dashboard: total searches, failed-search rate, click-through rate, search-to-cart conversion, top and zero-result terms. See Analytics.

Add to Cart and Wishlist behaviour

The plugin wires these for you out of the box, no event handlers required.

Add to Cart

When a shopper clicks Add to Cart from either the popup's quick-add icon or a product card, the plugin navigates the browser to WooCommerce's native add-to-cart URL:

?add-to-cart=PRODUCT_ID&quantity=1

WooCommerce handles the cart mutation through its normal request lifecycle, so the cart count, mini-cart, and any cart hooks fire exactly as if the shopper had clicked Add to Cart on a regular product page.

This requires that the unique_id field on each indexed SearchX product matches the WooCommerce product ID. If you import products from a feed, make sure the feed's product ID matches the WooCommerce ID.

Wishlist

When YITH WooCommerce Wishlist is active, Add to Wishlist clicks are posted to the plugin's REST endpoint (/wp-json/searchx/v1/wishlist/add) which adds the product to the shopper's wishlist using YITH's API. No further setup needed.

If YITH is not active, the click instead dispatches a SearchX:woocommerceAddToWishlist browser event you can listen to for custom wishlist handling. See Event Handling.

Security: the server-side proxy

The plugin uses a short server-side proxy to keep your private API key out of the browser. Here's what happens:

1. The browser sees a placeholder API key (searchx-wordpress-proxy) and the proxy URL (/wp-json/searchx/v1/proxy), never your real key.
2. Every search request the widget makes goes to the proxy first.
3. The proxy attaches your real API key on the server side and forwards the request to the SearchX API.
4. The response comes back the same way.

This means:

• Your API key is never visible in browser dev tools, page source, or browser extensions.
• The proxy only forwards a small allowlist of SearchX endpoints, so anything else returns 403 and a leaked placeholder key can't be used as a general-purpose relay.
• Built-in per-IP and global rate limiting protect your API quota against bursts and distributed traffic spikes.
• The proxy refuses to forward to anything other than the official SearchX hosts.

You don't need to configure any of this. It's enabled the moment you fill in your credentials.

Customising via wp-config.php (optional)

If you prefer to keep credentials in code instead of the database, define these constants in wp-config.php:

define('SEARCHX_APP_ID', 'your-app-id');
define('SEARCHX_API_KEY', 'your-private-api-key');
// Optional:
define('SEARCHX_API_PAGE_URL', 'https://admin.searchxengine.ai/api/v1');
define('SEARCHX_DEFAULT_LANGUAGE', 'en');

The plugin resolves credentials and supported defaults in this order: saved settings > wp-config.php constants > built-in defaults. So you can mix and match: store credentials in wp-config.php and let merchants tweak the visual toggles from the WooCommerce settings tab. The SDK bundle loads from the SearchX CDN, and custom widget CSS and translations are managed from the SearchX admin SDK settings.

Troubleshooting

Nothing appears on the storefront

• Check that the SearchX App ID and API key are saved.
• Check that the [searchx_bar] shortcode is present on the page, template or widget.
• Check that your theme renders shortcodes in that location.
• Check that your SearchX catalog has products imported.

The popup works, but the full results page does not

• Check that the results page contains [searchx_page].
• Check that the published page path matches Search page path in the settings.
• If the page is not at /searchx, update the path in WooCommerce > Settings > SearchX.

Add to cart does not work

• Check that the SearchX product unique_id values match your WooCommerce product IDs (set this in your XML feed).
• Check that WooCommerce cart/session behaviour works with the active theme.

Wishlist does not add products

• Check that YITH WooCommerce Wishlist is installed and active if automatic wishlist support is expected.
• Without YITH, listen for the SearchX:woocommerceAddToWishlist fallback event in your theme. See Event Handling.

No analytics or search results

• Check that the API key belongs to the same SearchX application as the App ID.
• Check that the product catalog has been imported successfully.
• Check that the API URL is still https://admin.searchxengine.ai/api/v1, unless SearchX support told you to use another endpoint.

Uninstalling

Deactivating and deleting the plugin from Plugins > Installed Plugins cleans up every option the plugin writes. No custom tables, no orphan rows in wp_options.

Related

• Product Import: Connect and schedule your product XML feed.
• Analytics: Searches, CTR, zero-result queries and conversion insights.
• Widget Styling: Override the default look and feel with CSS.
• Localization: Add translations or override existing strings.
• Event Handling: Custom Add to Cart / Wishlist handlers when you need them.
• Suggested Links: Promotional chips that appear in the search bar popup.
• URL Filters: Deep-link to filtered results for email campaigns and landing pages.