WooCommerce Integration

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

Overview

The SearchX SDK Integration plugin 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 — Download and install the plugin

1. From the SearchX dashboard, open the application you want to integrate and go to its Install JS snippet page. Pick the WooCommerce tab and click Download SearchX SDK Integration plugin to grab searchx-plugin.zip.
2. In WordPress, go to Plugins > Add New > Upload Plugin.
3. Upload searchx-plugin.zip and 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.

Step 2 — Configure your credentials

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

Credentials

Paste the App ID and API key from your SearchX dashboard. The other fields default to production values and rarely need to change.

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]

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

Visit your store and type a query in the search bar. You should see the popup with live results. Submit the query and the page should redirect to your results page with the full grid, filter sidebar, sort, and pagination rendered.

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.

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 — anything else returns 403, so 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');
define('SEARCHX_CUSTOM_CSS_URL', 'https://example.com/client-theme.css');
define('SEARCHX_CUSTOM_LOCALE_URL', 'https://example.com/locales/{{lng}}.json');

The plugin resolves each setting 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.

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

• 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.