Smart Search Integration

WP Engine Smart Search AI provides AI-powered product search for Commerce Connect sites. It automatically indexes your BigCommerce products synced to WordPress® and enables advanced search features including semantic search, faceted filtering, and intelligent recommendations.

Overview

What Smart Search does:

• Indexes all BigCommerce products synced via Commerce Connect
• Provides semantic (meaning-based) search powered by AI
• Handles misspellings and typos automatically
• Supports faceted filtering (price ranges, attributes, categories)
• Delivers real-time search results as products update

Requirements:

• WP Engine Premium or Headless Platform plan
• Commerce Connect plugin installed and configured
• Products synced from BigCommerce
• Block Theme (for faceted search blocks)

---

Installation & Setup

Step 1: Enable Smart Search License

1. Log in to WP Engine User Portal
2. Navigate to Products → Smart Search
3. Select the environment(s) where Commerce Connect is installed
4. Wait for “Ready to Use” status (green checkmark)

The WP Engine AI Toolkit plugin will be automatically installed.

Step 2: Initial Product Sync

Critical: You must perform a one-time sync before configuring settings.

1. Go to WP Admin → WP Engine AI Toolkit → Smart Search
2. Click the Index tab
3. Click Index Now button
4. Wait for sync to complete (may take significant time for large product catalogs)

What gets indexed:

• All synced BigCommerce products
• Product titles and descriptions
• Product pricing
• Product attributes and variants
• Product categories and tags
• Custom fields (when configured)

Step 3: Configure Search Settings

After initial sync completes, configure search behavior:

1. Go to Configuration tab
2. Choose your search type (see Search Types below)
3. Click Save Configuration
4. Important: Re-run sync after any configuration changes

---

Search Types

Full Text Search (Default)

Traditional keyword matching with smart features:

Stemming:

• Reduces words to root forms
• Example: Search “running shoes” matches “run shoe”

Fuzzy Matching:

• Tolerates 1-2 letter typos per word
• Example: Search “tible” returns products with “table”

Best for: Simple product catalogs, exact match requirements

Semantic Search (AI-Powered)

Analyzes meaning and context, not just keywords:

How it works:

• Understands word relationships and intent
• Example: Search “kitchen” returns kitchen products even without the word “kitchen” in descriptions
• Example: Search “gift for mom” returns products categorized as gifts

Configuration:

1. Select Semantic card in Configuration
2. Add fields to analyze: post_content, post_title, post_excerpt
3. Field selection limited to ~500 words per instance
4. Click Save Configuration
5. Re-run sync

Best for: Large catalogs, descriptive product content, conversational search queries

Hybrid Search (Recommended)

Combines Full Text + Semantic search:

Advantages:

• Balances exact matches with contextual understanding
• Adjustable weighting slider between the two approaches
• More 50% Full Text = prioritizes exact matches
• More 50% Semantic = prioritizes contextual relevance

Best for: Most Commerce Connect sites

---

Product Indexing

What Gets Indexed Automatically

Commerce Connect products are treated as WooCommerce products by WordPress®. Smart Search automatically indexes:

• Product post type (product)
• Product fields:
  • Title (post_title)
  • Description (post_content)
  • Short description (post_excerpt)
  • SKU
  • Pricing
  • Attributes (size, color, material, etc.)
  • Categories
  • Tags

Custom Field Indexing

If you’ve added custom fields via ACF or other plugins:

1. Go to Configuration → Models
2. Toggle on your custom post meta fields
3. Assign field weights (higher = more important)
4. Save and re-sync

Example custom fields:

• Brand name
• Material composition
• Care instructions
• Sustainability certifications

Real-Time Updates

After initial sync, Smart Search automatically updates when:

• New products are synced from BigCommerce
• Existing products are updated
• Products are deleted
• Product attributes change

No manual re-sync required for content updates.

---

Adding Search to Your Site

Search Block (Basic)

Use the default WordPress® search block with Smart Search enabled:

1. Edit any page or template in Block Editor
2. Add Search block
3. Configure display options (button text, placeholder, etc.)
4. Publish

Smart Search automatically powers all search queries.

Faceted Search Blocks (Advanced)

Requirements: Block Theme only (not supported in classic themes)

Range Facet (Price Filtering)

1. Add Range Facet block to search results template
2. Configure:
   • Field: Product price (_price meta key)
   • Min/Max: Set price range boundaries
   • Step: Price increment (e.g., $10)
3. Customize labels and styling

Example: “$0 - $500” slider

Filter Facet (Category/Attribute Filtering)

1. Add Filter Facet block to search results template
2. Configure:
   • Taxonomy: Product categories or tags
   • Display: Checkboxes or dropdown
   • Limit: Number of options to show
3. Customize appearance

Example: Filter by “Color”, “Size”, “Material”

Active Filters Facet (Display Selected Filters)

1. Add Active Filters Facet block
2. Shows currently applied filters
3. Users can click to remove individual filters

Example: “Color: Blue × Size: Large ד

---

Search Promotions & Custom Results

Promote Specific Products

Feature products at the top of search results:

1. Go to Search Promotions tab
2. Click Add Promotion
3. Select products to promote
4. Drag to reorder (top = highest priority)
5. Save

Use cases:

• Promote seasonal products
• Feature new arrivals
• Highlight sale items
• Boost slow-moving inventory

Custom Search Results

Define exact results for specific search phrases:

1. Go to Custom Search Results tab
2. Enter search phrase (e.g., “shipping policy”)
3. Select specific products or pages to return
4. Save

Use cases:

• Map common questions to help pages
• Direct brand searches to brand pages
• Override default results for ambiguous queries

---

Synonyms

Create synonym groups so search understands product terminology:

1. Go to Synonyms tab
2. Add synonym group (2-32 words)
3. Save and re-sync

Examples:

• “laptop, notebook, computer”
• “couch, sofa, loveseat”
• “dress, gown, frock”
• “sneakers, trainers, running shoes”

Benefits:

• Makes search intuitive for customers
• Accounts for regional terminology differences
• Captures brand-specific terms

---

Configuration Best Practices

For Small Product Catalogs (<100 products)

Recommended:

• Use Full Text Search with Fuzzy matching
• Enable Stemming
• Set Fuzzy distance: 1
• Skip Semantic Search (unnecessary overhead)

For Medium Product Catalogs (100-1,000 products)

Recommended:

• Use Hybrid Search
• Weight: 60% Full Text / 40% Semantic
• Enable Prioritize Recent Content (30-day window)
• Add synonyms for common product terms

For Large Product Catalogs (1,000+ products)

Recommended:

• Use Hybrid Search
• Weight: 40% Full Text / 60% Semantic
• Add comprehensive synonym groups
• Use faceted search blocks extensively
• Configure Search Promotions for key products

For Descriptive/Editorial Product Content

Recommended:

• Use Semantic Search (70%+)
• Index post_content field with full weight
• Add custom fields to index (brand, materials, etc.)
• Skip Fuzzy matching (semantic handles variations)

---

Performance Optimization

Reduce Initial Sync Time

Large catalogs may take significant time to index. To optimize:

1. Start with essential fields only in Configuration
2. Run initial sync
3. Add custom fields incrementally
4. Re-sync after each addition

Prioritize Recent Products

Enable Prioritize Recent Content to surface new products:

1. Go to Configuration → Prioritize Recent Content
2. Select prioritization window (7-365 days)
3. Available for Full Text and Hybrid only

Use case: Boost recently added products in search results

---

Troubleshooting

Products Not Appearing in Search Results

Check:

1. Initial sync completed successfully
2. Products are published in WordPress® (not draft)
3. Product post type enabled in Configuration → Models
4. Search index not corrupted

Fix:

1. Go to Index tab
2. Click Delete search data
3. Re-run sync with Index Now

Search Returns Irrelevant Results

Causes:

• Semantic Search weight too high
• Insufficient synonym configuration
• Poorly written product descriptions

Fix:

1. Adjust Hybrid Search weighting (increase Full Text %)
2. Add synonym groups for product terminology
3. Improve product descriptions in BigCommerce

Faceted Blocks Not Working

Causes:

• Classic theme in use (facets require Block Theme)
• Facet field not indexed
• Taxonomies not assigned to products

Fix:

1. Switch to Block Theme
2. Ensure facet field is indexed in Configuration
3. Verify products have categories/tags assigned in BigCommerce

Real-Time Updates Not Syncing

Causes:

• WP Engine AI Toolkit plugin deactivated
• Webhook failures between BigCommerce and WordPress®

Check:

1. Plugin is active in Plugins page
2. Commerce Connect webhooks are working (see Troubleshooting → Webhook Failures)
3. Re-enable Smart Search license if needed

Sync Takes Too Long

For very large catalogs (10,000+ products):

1. Contact WP Engine support to increase sync timeout
2. Consider indexing in stages:
   • Index product titles/descriptions first
   • Add attributes/custom fields later
3. Run sync during low-traffic periods

---

Integration with Commerce Connect Blocks

Search Box in Header

Add Smart Search-powered search to your site header:

1. Edit header template in Site Editor
2. Add Search block
3. Configure:
   • Show/hide search button
   • Placeholder text: “Search products…”
   • Button text: “Search”
4. Style to match theme

Product Grid with Search

Combine search with product display:

1. Create search results template
2. Add Search block at top
3. Add Products Grid block below
4. Products Grid automatically filters based on search query

Search Results Page Customization

1. Edit Search Results template in Site Editor
2. Add Faceted Search blocks (Range, Filter, Active Filters)
3. Add Products Grid block for results
4. Add Products Counter block to show result count
5. Customize layout and styling

---

Advanced: Custom Search Implementation

Using REST API

Smart Search provides a REST API endpoint for custom implementations:

// Example: Custom AJAX product search
fetch('/wp-json/wpe-ai-toolkit/v1/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'blue dress',
    post_type: 'product',
    limit: 20,
  }),
})
  .then((response) => response.json())
  .then((data) => {
    // Handle search results
    console.log(data.results);
  });

Filtering by Product Attributes

Add custom filters to search queries:

<?php
// Filter products by price range in search
add_filter('wpe_smart_search_query_args', function($args, $query) {
  if (isset($_GET['max_price'])) {
    $args['meta_query'][] = [
      'key' => '_price',
      'value' => $_GET['max_price'],
      'compare' => '<=',
      'type' => 'NUMERIC',
    ];
  }

  return $args;
}, 10, 2);

---

Limitations & Considerations

Block Theme Requirement:

• Faceted search blocks only work with Block Themes
• Classic themes must use shortcodes or custom implementations

Semantic Search Field Limit:

• ~500 words analyzed per field
• Long product descriptions may be truncated
• Choose most relevant fields for indexing

Initial Sync Required:

• Must sync data before configuration changes take effect
• Re-sync required after any Configuration changes
• Can’t skip initial sync step

License Per Environment:

• Separate license needed for dev/staging/production
• Contact Account Manager for multi-environment setup

Plugin Must Stay Active:

• Deactivating WP Engine AI Toolkit stops real-time updates
• Products won’t appear in search if plugin is disabled

---

Related Documentation

• Product Sync - How BigCommerce products sync to WordPress®
• Products Grid Block - Display search results
• Products Filters Block - Add filtering to product grids
• SEO Plugins - Optimize product pages for search engines

---

Sources

• WP Engine Smart Search Support
• Smart Search AI Product Page
• Headless E-Commerce Search Tutorial