Documentation

Set up and use Search with AI for WooCommerce.

A practical guide for installing the plugin, choosing a results flow, configuring AI providers, enabling image search, rebuilding the catalog index, and troubleshooting common setup problems.

Overview

What the plugin does

Search with AI for WooCommerce adds a shopper-facing product search experience to a WooCommerce store. Shoppers can type natural requests, optionally upload a product image, and reach either the theme's native WooCommerce search results or a dedicated shortcode results page.

Default behavior

The default shortcode uses the active theme's native WooCommerce product-search results.

Fallback matching

Text search can still work without an AI provider key through local catalog matching.

Optional AI

AI improves intent understanding, reranking, and image analysis when configured.

Requirements

Before you install

  • WordPress 6.4 or newer.
  • PHP 7.4 or newer.
  • WooCommerce active and the normal Shop/search pages working.
  • Rank Math is optional. Supported Rank Math fields are indexed when present.
  • An AI provider key is optional for text search and required for image search.
  • A vision-capable AI model is required when image search is enabled.

License

Activate the pro build

The free build can run without vendor license activation. The private/pro build requires an active license before storefront search features are available to shoppers.

  1. In WordPress admin, open Search with AI > Activation.
  2. Paste the license key exactly as provided after purchase.
  3. Click Activate License.
  4. Use Check License when you move the site, change the domain, or need to confirm status.
  5. Use Deactivate License before moving the license to another site.
License service: By default the plugin talks to https://plugin-licenses.onlineshopcatalogue.co.uk/api/licenses. Developers can override that endpoint with SWAI_LICENSE_API_BASE.

Quick Start

Recommended setup for a new store

  1. Install the plugin folder in /wp-content/plugins/ or upload the plugin zip from the WordPress plugins screen.
  2. Activate Search with AI for WooCommerce.
  3. Make sure WooCommerce is active.
  4. For the pro build, open Search with AI > Activation, enter the license key, and click Activate License.
  5. Open Search with AI > Settings.
  6. Leave AI off if you only want local text matching, or configure a provider if you want AI understanding or image search.
  7. Create or edit a page and add [swai_search].
  8. Click Rebuild Product Index after product imports or large catalog edits.
  9. Run a test search from the storefront.
Best first setup: Use [swai_search] first. It keeps your theme's product cards, sorting, filters, and pagination.

Results Flow

Choose native mode or shortcode mode

Mode Use it when What happens
Native Your theme already has good WooCommerce product result pages. The form redirects to native WooCommerce product search with post_type=product and swai_native=1.
Shortcode You want a dedicated AI search results page or your theme search template is not suitable. The plugin renders paginated product cards from the shortcode using swai_query, swai_page, and optional swai_token.

Shortcodes

Shortcode reference

[swai_search]Default search form. Uses native WooCommerce results.
[swai_search results_mode="native"]Explicit native mode.
[swai_search results_mode="shortcode" results_page_url="/ai-search-results/"]Put this on the search-entry page.
[swai_search results_mode="shortcode" per_page="9"]Put this on the dedicated results page.

Attributes

AttributeDefaultPurpose
results_modenativeUse native or shortcode.
results_page_urlCurrent/local pageTarget page for shortcode mode. Use a local URL or path such as /ai-search-results/.
per_page9Number of plugin-hosted results per page. It is clamped between 1 and 120.
placeholderExample prompt textCustom placeholder for the search input.
button_labelSearchCustom submit button text.

Dedicated results setup

  1. Create a page with slug ai-search-results.
  2. On that results page, add [swai_search results_mode="shortcode" per_page="9"].
  3. On the search-entry page, add [swai_search results_mode="shortcode" results_page_url="/ai-search-results/"].
  4. Run a test search and confirm the URL includes swai_query=....

Admin Settings

Settings reference

SettingDefaultHow to use it
Enable AI UnderstandingOffTurn on for provider-powered query understanding and reranking.
AI ProviderOpenAIChoose OpenAI, Anthropic Claude, Google Gemini, or OpenAI-compatible / Custom.
AI Provider API KeyEmptyEnter the key from the selected provider. Leave empty for fallback matching.
AI Provider Base URLEmptyOnly needed for OpenAI-compatible custom providers, usually ending in /v1.
AI Modelgpt-4o-miniUse any model ID supported by the selected provider.
Max Products Per Reply6Controls product count in widget/chat replies. Maximum is 120.
Enable Image SearchOnOnly works when the selected provider/model supports image input.
Primary Color#FCB800Main accent color for buttons, highlights, and active states.
Secondary Color#000000Support color for text, borders, and contrast elements.
AI System PromptEmptyOptional override for AI behavior. Keep the AI response JSON-only with reply and queries.

AI Providers

Provider setup

ProviderBase URLExample model
OpenAILeave emptygpt-4o-mini
Anthropic ClaudeLeave emptyclaude-sonnet-4-20250514
Google GeminiLeave emptygemini-2.5-flash
OpenAI-compatible / Customhttps://api.example.com/v1The provider's model ID
  1. Select the provider in Search with AI > Settings.
  2. Enter the API key and model ID from the same provider account.
  3. Only fill Base URL for OpenAI-compatible custom providers.
  4. Click Test Provider.
  5. If the test fails, verify provider, API key, model ID, and base URL are from the same account.

Catalog Index

What gets indexed and when to rebuild

The plugin builds a searchable product text blob for published products and keeps it in product meta.

  • Product title, short description, full description, and SKU.
  • Categories, tags, product attributes, and attribute values.
  • Variation SKU, variation attributes, and variation descriptions.
  • Featured/gallery image alt text, title, caption, and description.
  • Rank Math fields: rank_math_title, rank_math_description, and rank_math_focus_keyword.

Rebuild the index after bulk imports, CSV imports, major catalog edits, attribute changes, or SEO metadata changes.

Floating Widget

Where the AI search widget appears

The floating widget is designed for WooCommerce product-discovery pages. It does not render in the WordPress admin area and it waits until WooCommerce is available.

  • By default it appears on shop, product, product category, product tag, and product taxonomy pages.
  • In the pro build, the widget requires an active license for storefront use.
  • The public chat route is /wp-json/swai/v1/chat.
  • REST chat requests are rate-limited to 25 requests per 5 minutes per visitor fingerprint.
  • Developers can control visibility with the swai_should_render_widget filter.

Testing

Final setup checklist

  • Confirm WooCommerce is active and the shop page loads products normally.
  • Save the plugin settings once, even if you keep the default values.
  • If AI is enabled, click Test Provider before testing the storefront.
  • Run one short keyword search, one natural-language search, and one SKU search.
  • If image search is enabled, test JPEG, PNG, and WebP files under 5 MB.
  • Check the result URL in shortcode mode and confirm it includes swai_query.
  • After importing products, click Rebuild Product Index and test again.

Privacy

External services and data flow

The plugin only needs external AI calls when AI understanding or image search is enabled. Review your chosen provider's terms and privacy policy before using it on a live store.

ServiceWhen it is usedData involved
AI providerAI understanding, reranking, chat replies, and image search.Search query, selected catalog context, and uploaded image when image search is used.
License APIActivation, status checks, scheduled checks, and deactivation in the pro build.License key, site URL/domain metadata, plugin/version metadata, and license status proof data.
Keep API keys private. Do not place provider keys in public JavaScript, page content, or theme templates.

Troubleshooting

Common problems and fixes

ProblemFix
Shortcode shows WooCommerce missing message.Activate WooCommerce first.
Pro storefront search does not run.Activate the license from the Activation page and check status.
AI provider test fails.Check provider selection, API key, model ID, and custom base URL.
Image search fails or falls back.Use a vision-capable model and keep image search enabled only for that model.
Shortcode mode redirects but shows no results.Verify results_page_url, the results page shortcode, and that the URL includes swai_query.
New products do not appear.Rebuild Product Index after imports or large edits.

Developer Notes

Implementation reference

  • Provider settings are stored in swai_options.
  • Provider key: ai_provider. Supported values: openai, anthropic, gemini, openai_compatible.
  • API key and model option names remain openai_api_key and openai_model for backward compatibility.
  • Provider routing lives in includes/class-swai-ai-service.php.
  • Settings fields, shortcodes, REST route, AJAX actions, and license checks live in includes/class-swai-plugin.php.
  • Frontend widget JS lives in assets/js/swai-widget.js.
  • Admin provider/license JS lives in assets/js/swai-admin.js.
  • The public REST chat endpoint is /wp-json/swai/v1/chat.
  • The floating widget renders only on WooCommerce discovery views by default and can be controlled with the swai_should_render_widget filter.