Skip to main content

Recipe: WooCommerce end-to-end

This guide builds a WooCommerce shop with semantic search, catalog sync, cart bridge and conversion tracking, all in under 30 minutes. We will use the official neuroon-search v0.8.4 plugin.

If you are looking for the AI agents plugin (UCP, Google Search AI Mode), that one is called neuroon-agentic-commerce v0.1.0 and is a separate product.

Estimated time: 20-30 min.

Prerequisites​

  • WordPress 5.8+ (tested up to 6.7) with WooCommerce 6.0+ (tested up to 9.4) on PHP 7.4+.
  • Administrator access (manage_options).
  • A API Key generated from the dashboard (Production or Development).
  • SSH / SFTP access to the server (optional, for wp-cli / wp-config.php).

Step 1. Install the plugin​

# Option A: WP-CLI
wp plugin install /path/to/neuroon-search-0.8.4.zip --activate

# Option B: via wp-admin
# Plugins → Add New → Upload Plugin → select the ZIP → Install Now → Activate

After activating, you will see the Settings → Neuroon Search menu. Only the Settings tab will be visible until you verify the domain (progressive disclosure).

Step 2. (Optional) Point at Development​

Only if you plan to test against dev.neuroon.ai before production. Add to wp-config.php:

define('NEUROON_API_BASE_URL', 'https://dev.neuroon.ai/api');

Step 3. Configure credentials​

  1. Settings → Neuroon Search → Settings tab.
  2. API Key: paste the key (Bearer token).
  3. Shop ID (optional, auto-filled when verifying).
  4. Click Save.

Step 4. Verify the domain​

Click Verify Domain. The plugin automatically checks that the current domain matches the shop.url already registered in Neuroon — it's not a call you have to build yourself. If they match, the Products, Widget and Diagnostics tabs are enabled instantly.

Step 5. Initial catalog sync​

  1. Settings → Neuroon Search → Products tab.
  2. Select all (or filter by category / status).
  3. Click Sync selected.

The plugin syncs the selected products in batches of 100 and updates a progress bar until it finishes.

Latency: synced products are indexed in Neuroon in 2 to 5 seconds.

Step 6. Widget embed​

The plugin automatically injects the widget script if you enable Auto-embed in the Widget tab.

For manual embed (e.g. in a custom theme), use the [neuroon_search] shortcode in any page or block.

Step 7. Cart bridge​

You do not have to do anything to enable it: the plugin keeps the widget's cart view in sync automatically and dispatches neuroon:cart-update whenever the cart changes.

Quick validation in the browser console:

window.addEventListener('neuroon:cart-update', e => console.log(e));
// Click "Add to cart" on a product page

Step 8. Conversion tracking​

If you use the official plugin, you do not have to write or configure anything: the plugin itself hooks into the WooCommerce checkout and reports every completed order to Neuroon automatically.

If you need manual conversion tracking — for example, a custom integration that does not go through the plugin — see the Conversion tracking recipe.

Step 9. Verify the integration​

# 1) Check the shop info
curl -s "https://api.neuroon.ai/api/integrations/v1/shop" \
-H "Authorization: Bearer $NEUROON_API_KEY" \
-H "Origin: https://your-shop.example"

# 2) Retrieve 5 synced products
curl -s "https://api.neuroon.ai/api/integrations/v1/products?size=5" \
-H "Authorization: Bearer $NEUROON_API_KEY" \
-H "Origin: https://your-shop.example"

# 3) Run a search using the widget token (printed in data-token)
curl -s "https://api.neuroon.ai/api/widget/search?q=t-shirt&limit=3" \
-H "X-Widget-Token: $WIDGET_TOKEN"

Common errors​

SymptomCauseFix
Verify Domain fails with 403Current domain does not match the registered shop.urlReconcile the canonical domain (apex vs www.).
Sync stuck at PROCESSINGPHP-FPM timeout (max_execution_time)Raise it to 60 s.
429 during a mass syncSaturated sync rate limit (100/min)The plugin honors Retry-After; wait and retry.
Widget does not load, integrity mismatchSRI does not match the widget versionRecompute the SRI with openssl dgst -sha384 -binary.
Products do not appear in search2-5 s indexing latencyWait 5 s and retry.
Tracking does not hit the dashboardAdblocker blocks a client-side pixelThe plugin's tracking is already server-side by default; verify the API Key and the verified domain are correct.

Next steps​

Last updated on