📘 User Guide

1. Overview

AI WooCommerce Search is an advanced natural-language product discovery plugin designed for WooCommerce stores.

Instead of traditional filters and keyword search, users can describe what they want in plain language, and the system intelligently returns matching products.

Example:

“Elegant pastel polo shirt for men, size L”

The plugin understands the intent and returns precise results using your store’s real product data.

2. Key Features

🧠 Natural Language Search
Users type queries like a human
No need for filters or exact keywords

⚡ Instant Results
Fast search powered by optimized pipeline
No page reload required

🌍 Multilingual Support
Works in any language supported by OpenAI

🎯 Accurate Matching
Converts user intent into structured attributes
Uses WooCommerce taxonomy for precise filtering

💡 Smart UX
Floating search button
Smooth animations
Mobile-first design

3. How It Works (Advanced Logic)

AI Woo Search does not behave like traditional keyword search.

It follows a structured pipeline:

🧠 Step 1 — User Query

User writes naturally:

✔ “Men’s grey short sleeve shirt”

✔ “Black leather shoes under $100”

✔ “Gaming laptop with RTX 4060”

✔ “Minimalist white sneakers”

✔ “Samsung phone with stylus”

✔ “Wooden dining table for 6 people”

🤖 Step 2 — AI Intent Extraction

The plugin uses OpenAI to convert text into structured intent:

{

  “category”: “shirt”,

  “gender”: “male”,

  “attributes”: {

    “color”: “gray”,

    “style”: “short sleeve”

  }

}

👉 AI only understands intent — it does NOT search products.

👉 Important: AI does not search your products directly.

      It only converts user language into structured filters.

      All product matching is done by WooCommerce data.

🏪 Step 3 — Store-Aware Mapping

The plugin maps intent to your store:

• Categories → WooCommerce categories
• Attributes → WooCommerce attributes
• Brands → brand taxonomy

👉 This ensures compatibility with ANY WooCommerce store.

🔍 Step 4 — Strict Filtering (Core Engine)

The plugin applies filters exactly like WooCommerce filters:

Category AND Gender AND Brand AND Attributes

Example:

Men + Shirt + Gray + Short Sleeve

👉 All conditions MUST match.

⚠️ Important Behavior

If no exact match exists:

👉 Result = 0 products

This is intentional.

The plugin DOES NOT:

❌ Show unrelated products
❌ Guess approximate matches
❌ Return misleading results

📦 Step 5 — Data Sources

The system uses:

1. WooCommerce taxonomies (main source)
2. Product attributes
3. Product title
4. Short description
5. Full description

👉 Even if attributes are missing, search can still work via text.

🧮 Step 6 — Ranking

Products are ranked by:

• exact matches
• attribute relevance
• text consistency

Only valid products are ranked.

⚡ Step 7 — Instant Response

Results are returned instantly:

• via REST API
• optimized queries
• cache (if enabled)

4. Installation

Upload plugin ZIP in WordPress
Activate plugin

Go to:

AI Woo Search

Enter your OpenAI API Key
Click Save Settings

5. License Activation

Enter your license key
Click Activate

✔ License binds to your domain
✔ No manual validation needed after activation

6. Using the Search

Frontend Experience

Click floating search button
Type your request
Results appear instantly

Example Queries

• “Black leather shoes under $100”
• “Gaming laptop with RTX 4060”
• “Minimalist white sneakers”
• “Men’s grey short sleeve shirt”

7. Supported Search Types

✔ Clothing
✔ Electronics
✔ General products
✔ Technical specs
✔ Price filters
✔ Style-based queries

8. Accuracy & Matching Philosophy

🎯 Precision Over Guessing

AI Woo Search is designed to be precise, not approximate.

✔ Shows only relevant products
❌ Does NOT show “close enough” results

Example

User searches:

“Women Adidas running shoes”

If store has:

• Adidas (men) ❌
• Nike (women) ❌

👉 Result:

0 products

Why this matters

Prevents:

• wrong purchases
• confusion
• poor UX

Traditional vs AI Search

🧠 How the system uses this data

The search engine:

• Matches user intent to WooCommerce categories and attributes
• Uses product titles and descriptions as additional signals
• Combines structured data + text to find the most accurate results

⚠️ Important note (in simple terms)

If a product does not contain relevant information:

👉 It may not appear in search results

Example:

If a product has no color assigned and no description mentioning it,
a query like:

“red shirt”

may not find that product.

✅ Good news

You do NOT need any custom setup.

Everything works with:

✔ Standard WooCommerce categories
✔ Default product attributes
✔ Regular product descriptions

💡 Best practice

Think of AI Search as a smart layer on top of your catalog.

👉 The better your product data → the better your search results

🚀 Quick tip

Even small improvements help a lot:

• Add missing attributes (color, size)
• Use clear product titles
• Write short but descriptive product descriptions

9. Performance

✔ Optimized queries
✔ Smart caching
✔ Minimal API calls

Search Result Limit

To keep the interface fast, clean, and easy to use, AI Woo Search displays only the top matching products instead of overwhelming shoppers with very large result lists.

In normal AI search mode, only the highest-ranked matching products are shown.

This improves usability, performance, and conversion.

10. Cost (Important)

Uses your own OpenAI API key.

Typical cost:

• ~$1–2 per 1000 users
• ~$10–40/month average

Depends on usage.

11. Troubleshooting

🔴 No results

✔ Try simpler query
✔ Check product categories
✔ Check attributes

🔴 Wrong results

✔ Verify product data
✔ Ensure attributes are assigned

👉 AI cannot fix incorrect product data.

🔴 Too strict results

✔ This is expected

The system requires full match.

🔴 API errors

✔ Check API key
✔ Check OpenAI balance

🔴 License issues

✔ Verify domain
✔ Re-activate license

🔴 “Quota exceeded”

✔ Add payment method in OpenAI

✔ Check usage limits

🔴 Why a specific product does not appear

This usually happens when the product does not fully match the search criteria.

Check:

✔ Correct category assigned 

✔ Required attributes exist (color, size, etc.) 

✔ Product description contains relevant keywords 

👉 AI Woo Search requires all important conditions to match.

If one condition is missing, the product may be excluded.

🔴 Results not updating

If you recently changed products:

✔ Clear plugin cache 

✔ Or wait for cache TTL to expire 

👉 Cached results may temporarily show outdated data.

🔑How to Get Your OpenAI API Key

(Step-by-step guide for AI Woo Search Plugin users)

📌 What is this and why you need it?

AI Woo Search uses the OpenAI API to understand user queries.

👉 To make the plugin work, you need your own OpenAI API Key.

🚀 Step-by-Step Instructions

1️⃣ Go to OpenAI Platform

👉 Open this link in your browser:

👉 https://platform.openai.com/

2️⃣ Sign In or Create Account

• If you already have an account → Sign in
• If not → click Sign up

3️⃣ Open API Keys Page

Once logged in:

👉 Click this direct link:

👉 https://platform.openai.com/api-keys

4️⃣ Create New API Key

1. Click “Create new secret key”
2. Give it a name (optional), for example:
3. WooCommerce AI Search
4. Click Create

⚠️ IMPORTANT

👉 You will see the key only once!

Example:

sk-abc123xyz456…

📌 Copy it immediately and store it safely.

5️⃣ Add API Key to Plugin

Go to your WordPress admin:

AI Search → Settings

Paste your key into:

OpenAI API Key

Click:

👉 Save Settings

💳 Do I need to pay OpenAI?

Yes, OpenAI API is usage-based.

Typical cost:

• ~$10–40/month for medium traffic sites
• Depends on how often users search

👉 You can monitor usage here:
https://platform.openai.com/usage

🛡️ Security Tips

• ❌ Never share your API key publicly
• ❌ Do not expose it in frontend code
• ✅ Use it only in plugin settings

🧪 Test Your Setup

After adding the key:

1. Open your website
2. Click AI Search
3. Type something like:
4. black sneakers under $100
5. You should see results instantly

⚙️ AI Woo Search — Plugin Settings Guide

This section explains every setting available in the plugin and how it affects performance, cost, and user experience.

🔑 OpenAI API Key

👉 This is your personal API key from OpenAI.

What it does:

• Enables AI-powered search
• Connects your website to OpenAI

Required:

✅ Yes (plugin will not work without it)

Example:

sk-xxxxxxxxxxxxxxxx

Tips:

• Keep it private
• Do not share it publicly
• Use a separate key for this plugin

🤖 OpenAI Model

Default:

gpt-4.1-mini

What it does:

Determines which AI model is used to interpret user queries.

Recommended:

• gpt-4.1-mini → ✅ best balance (cost + performance)

Alternatives:

• Faster/cheaper → lighter models
• More accurate → heavier models (higher cost)

Impact:

⏱️ Request Timeout (seconds)

Default:

20

What it does:

Maximum time the plugin waits for AI response.

Example:

• If set to 20 → waits up to 20 seconds

Recommended:

• 15–25 seconds

If too low:

❌ requests may fail

If too high:

❌ slow fallback behavior

✍️ Max Query Length

Default:

150

What it does:

Limits how long a user query can be.

Why important:

• Controls API cost
• Prevents abuse/spam
• Keeps responses fast

Example:

User cannot type more than 150 characters

Recommended:

• 100–250

💾 Enable Cache

✔ Enabled

What it does:

Stores:

• parsed AI intents
• search results

Benefits:

• ⚡ Faster responses
• 💰 Lower OpenAI cost
• 🔁 Reuses previous searches

Recommended:

✅ Always ON

⏳ Cache TTL (minutes)

Default:

1440 (24 hours)

What it does:

How long cached data is stored.

Example:

• 1440 = 24 hours
• 60 = 1 hour

Recommended:

🎨 Enable Animations

✔ Enabled

What it does:

Enables UI effects:

• floating search button
• panel transitions
• staggered results animation

Recommended:

✅ ON for best UX

♿ Respect Reduced Motion

✔ Enabled

What it does:

Detects user system preference:

• disables heavy animations if needed

Why important:

• Accessibility compliance
• Better UX for sensitive users

Recommended:

✅ Always ON

🐞 Debug Mode

❌ Disabled (default)

What it does:

Logs detailed internal activity to WordPress logs.

Includes:

• API responses
• errors
• pipeline steps

Use when:

• troubleshooting issues
• development/testing

Important:

⚠️ Do NOT enable on production long-term

Widget Position

Defines where the floating AI Search button appears on the frontend. This helps prevent overlap with important store elements such as sticky add-to-cart buttons, bottom navigation, chat widgets, or mobile action bars.

Horizontal Offset (px)

Controls the horizontal spacing of the widget from its selected anchor position.

Vertical Offset (px)

Controls the vertical spacing of the widget from its selected anchor position.

Mobile Vertical Offset (px)

Lets the administrator increase the bottom spacing on mobile devices to avoid conflicts with sticky purchase buttons, cookie banners, or bottom navigation.

default values:

Widget Position → Bottom Right

Horizontal Offset → 24

Vertical Offset → 24

Mobile Vertical Offset → 24

Cache Maintenance

Cache Maintenance lets store administrators manually clear the plugin’s locally stored AI cache at any time.

When caching is enabled, the plugin stores parsed search intents and cached product search results in the local database to improve speed and reduce repeated API usage. Over time, this cache may contain outdated or less relevant data, especially after catalog updates, attribute changes, product removals, or major pricing/content edits.

The Clear Cache action removes all stored AI intent cache and cached search results from the local database. This is useful when:

• product data has changed significantly,
• categories, attributes, or brand mappings were updated,
• search results need to be refreshed immediately,
• the administrator wants to force the plugin to rebuild search data from scratch.

This action does not affect products, orders, licenses, or plugin settings. It only clears cached AI search data.

📊 Recommended Default Configuration

🧠 Performance & Cost Tips

• Enable cache → reduces API cost by up to 70%
• Limit query length → prevents unnecessary tokens
• Use gpt-4.1-mini → best cost/performance ratio

⚠️ Common Mistakes

❌ Missing API key
❌ Cache disabled (high cost)
❌ Too long queries
❌ Debug mode left ON

🚀 Summary

These settings control:

• ⚡ Speed
• 💰 Cost
• 🎯 Accuracy
• 🎨 User Experience

Proper configuration ensures your AI search is fast, affordable, and reliable.