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 Shop API Key generated from the dashboard (Production or Development).
SSH / SFTP access to the server (optional, for wp-cli / wp-config.php).

Citation: requirements verified in .

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-api.neuroon.ai before production. Add to wp-config.php:

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

Citation: neuroon_get_api_url() in .

Step 3. Configure credentials

Settings → Neuroon Search → Settings tab.
Shop API Key: paste the key (sk_…).
Shop ID (optional, auto-filled when verifying).
Click Save.

Credentials are stored in wp_options (neuroon_api_key, neuroon_shop_id). On shared environments, consider defining them as constants in wp-config.php with a custom filter.

Step 4. Verify the domain

Click Verify Domain. The plugin fires:

POST /api/plugin/shops/verify HTTP/1.1
X-Shop-API-Key: sk_xxx
Origin: https://your-shop.example
Content-Type: application/json

{"domain": "https://your-shop.example"}

The backend compares normalizeUrl(domain) against the registered shop.url. If they match, it returns shopId, verificationCode and shop data. The Products, Widget and Diagnostics tabs are enabled instantly.

Citation: flow described in wordpress-plugin/CLAUDE.md and handler admin_post_neuroon_verify.

Step 5. Initial catalog sync

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

What happens under the hood:

The plugin marks the selected items as PENDING in wp_neuroon_product_sync.
AJAX fires neuroon_start_sync, which calls neuroon_sync_batch in batches of 50 products by default (Neuroon_Constants::DEFAULT_BATCH_SIZE = 50, configurable up to 500 via the neuroon_batch_size option).
Each batch sends POST /api/plugin/shops/{shopId}/products/sync with syncType: "INCREMENTAL".
The UI polls neuroon_sync_status and updates the progress bar.

Citation: wp_neuroon_product_sync table, AJAX endpoints and batch size in wordpress-plugin/CLAUDE.md.

Latency: after the 200 OK, products are indexed in Neuroon in 2 to 5 seconds.

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

define('NEUROON_WIDGET_VERSION',  '0.9.10');
define('NEUROON_WIDGET_SRI_HASH', 'sha384-JTaG/IN0Jj/ImfUj2x5QVMG4HkbFHzui7fTpLtwl1hsP+kY9W8OODeSJRFWN1ZP5');

Citation: .

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 hooks jQuery onto WooCommerce events and dispatches neuroon:cart-update with a 200 ms debounce.

var wcCartEvents = 'added_to_cart removed_from_cart updated_wc_div ' +
                   'updated_cart_totals wc_fragments_refreshed ' +
                   'wc_fragments_loaded wc_cart_emptied';

Citation: .

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

Recommended: use the woocommerce_thankyou hook to call the endpoint server-side and avoid losing sales to adblockers:

add_action('woocommerce_thankyou', function ($order_id) {
    if (!$order_id) return;

    $order = wc_get_order($order_id);
    if (!$order) return;

    $payload = [
        'orderId'     => (string) $order->get_id(),
        'orderValue'  => (float) $order->get_total(),
        'currency'    => $order->get_currency(),
        'conversions' => array_map(function ($item) {
            return [
                'productId' => (string) $item->get_product_id(),
                'quantity'  => (int) $item->get_quantity(),
                'lineTotal' => (float) $item->get_total(),
            ];
        }, array_values($order->get_items())),
    ];

    $shop_id  = get_option('neuroon_shop_id');
    $api_key  = get_option('neuroon_api_key');
    $base_url = defined('NEUROON_API_BASE_URL') ? NEUROON_API_BASE_URL : 'https://api.neuroon.ai/api';

    wp_remote_post("$base_url/api/plugin/shops/$shop_id/track/conversion", [
        'headers' => [
            'X-Shop-API-Key' => $api_key,
            'Origin'         => get_site_url(),
            'Content-Type'   => 'application/json',
        ],
        'body'    => wp_json_encode($payload),
        'timeout' => 10,
    ]);
}, 20, 1);

If your shop uses a custom order builder, hook the handler where you mark the order as paid / completed, not on thankyou.

Step 9. Verify the integration

# 1) Check the shop info
curl -s "https://dev-api.neuroon.ai/api/plugin/shops/me" \
  -H "X-Shop-API-Key: $NEUROON_API_KEY" \
  -H "Origin: https://your-shop.example"

# 2) Retrieve 5 synced products
curl -s "https://dev-api.neuroon.ai/api/plugin/shops/$NEUROON_SHOP_ID/products?size=5" \
  -H "X-Shop-API-Key: $NEUROON_API_KEY" \
  -H "Origin: https://your-shop.example"

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

Common errors

Symptom	Cause	Fix
`Verify Domain` fails with 403	Current domain does not match the registered `shop.url`	Reconcile the canonical domain (apex vs `www.`).
`Sync` stuck at PROCESSING	PHP-FPM timeout (`max_execution_time`)	Raise to 60 s; the plugin already pauses 100 ms between batches.
`429` during a mass sync	Saturated `sync` rate limit (100/min)	The plugin honors `Retry-After`; wait and retry.
Widget does not load, `integrity` mismatch	SRI does not match the widget version	Recompute the SRI with `openssl dgst -sha384 -binary`.
Products do not appear in search	2-5 s indexing latency	Wait 5 s and retry.
Tracking does not hit the dashboard	Adblocker blocks the pixel	Use the `woocommerce_thankyou` hook server-side (Step 8).

Next steps

plugins/wordpress/admin-dashboard — tabs and AJAX.
plugins/wordpress/product-sync — FULL / INCREMENTAL modes.
Recipe · Conversion tracking — cross-stack patterns.
Authentication · Shop API Key.

Prerequisites​

Step 1. Install the plugin​

Step 2. (Optional) Point at Development​

Step 3. Configure credentials​

Step 4. Verify the domain​

Step 5. Initial catalog sync​

Step 6. Widget embed​

Step 7. Cart bridge​

Step 8. Conversion tracking​

Step 9. Verify the integration​

Common errors​

Next steps​