Documentation — Contexa AI Search

Getting Started with AI Ecommerce Search

WooCommerce Product Search Plugin

Shopify Product Search App

Product Search REST API

JavaScript SDK for Site Search

Ecommerce Search Features

AI Product Recommendations

Search Analytics & Tracking

Search Pricing & Credits

Search Security & Privacy

Getting Started with AI Ecommerce Search

What is Contexa AI Search?

Contexa is an AI-powered ecommerce search and recommendation platform that delivers intelligent product search for online stores. It provides semantic search that understands customer intent, real-time autocomplete, 5 types of product recommendations, and built-in analytics. Contexa integrates with WooCommerce, Shopify, and any platform via REST API or JavaScript SDK.

How AI Product Search Works

Contexa uses three AI models working together:

1. Embedding Model (zylonai/multilingual-e5-large) — converts both products and search queries into semantic vectors for meaning-based matching.
2. Query Parser (llama3.2) — extracts structured filters from natural language queries (price ranges, categories, colors, brands) in multiple languages.
3. Validation Model (mistral) — scores search results for relevance after retrieval.

When a customer searches, their query is embedded into a vector, parsed for filters, matched against your product vectors using cosine similarity, and validated for relevance — all in ~245ms.

Supported Ecommerce Platforms

WooCommerce — WordPress plugin with automated onboarding wizard, product sync, 5 search templates, 5 recommendation shortcodes, and WPML multi-language support.

Shopify — Embedded app with real-time webhook-based product sync, Liquid theme block for the search widget, and GDPR compliance.

Custom Integration — JavaScript SDK for any website or REST API for server-to-server integration. Upload product data via CSV, JSON, or API.

Supported Languages

Contexa supports English, Hebrew, Arabic, Spanish, French, and German through its multilingual embedding model. The search works natively in all languages — no translation step required. For WooCommerce sites with WPML, the setup wizard lets you choose which languages to index.

Creating an Account

For WooCommerce: the plugin's onboarding wizard creates your account automatically — just enter your email.

For Shopify: the app handles authentication via OAuth when you install it.

For direct API access: register at contexa.co with your name, email, and password.

All new accounts start with a free plan — 10,000 API credits, no credit card required.

WooCommerce Product Search Plugin

System Requirements

WordPress 5.8+, WooCommerce 5.0+, PHP 7.4+. Your server must allow outbound HTTPS requests on port 443 to communicate with api.contexa.co.

Product Search Setup Wizard

When you activate the plugin, a full-screen onboarding wizard launches automatically:

Step 1 — Health Scan: Contexa runs a health score test, detecting your products, categories, post types, taxonomies, languages (WPML), and existing search plugins.

Step 2 — Dashboard: Shows your search health score, everything it detected, and any issues identified.

Step 3 — Language Selection (WPML only): Choose which languages to sync. Content counts update in real-time as you select/deselect.

Step 4 — Content Selection: Pick which content types to index — products, posts, pages, custom post types.

Step 5 — Account Creation: Enter your email. Contexa auto-creates your account and generates your API key.

Step 6 — Sync: Live progress bar shows connecting, indexing, analyzing, and enabling tracking.

Step 7 — Done: Shows before/after health scores and the [contexa_search] shortcode.

Product Search Shortcode

Place the search widget on any page using the shortcode. Contexa does not replace your default WooCommerce search — it provides its own search experience via shortcode.

[contexa_search]

<!-- With options -->
[contexa_search
  placeholder="Search products..."
  button_text="Search"
  layout="grid"
  columns="4"
  show_price="yes"
  show_description="yes"
  results_per_page="12"
  template="1"
]

Product Search Templates

Five visual templates are available via the template parameter:

Template	Name	Style
1	Classic Grid	Traditional cards with hover lift effect
2	Minimal Clean	Borderless with subtle hover
3	Card with Shadow	Rounded corners with elegant shadows
4	Modern Bordered	Bold borders with inverted hover
5	Colorful Gradient	Purple gradient backgrounds

Recommendation Shortcodes

Five recommendation types, each available as a shortcode with AJAX add-to-cart:

<!-- Similar Products (on product pages) -->
[contexa_similar product_id="123" title="You May Also Like" columns="4" limit="8"]

<!-- Trending Products (homepage, category pages) -->
[contexa_trending title="Trending Now" columns="4" limit="8"]

<!-- Personalized (based on visitor browsing history) -->
[contexa_personalized title="Recommended For You" columns="4" limit="8"]

<!-- Frequently Bought Together (cross-sell on product pages) -->
[contexa_frequently_together product_id="123" title="Often Bought Together" columns="4" limit="4"]

<!-- Cart-Based (cart and checkout pages) -->
[contexa_cart_based title="Complete Your Purchase" columns="4" limit="4"]

Product Search Index Sync

Initial sync happens during the onboarding wizard — products are sent in batches of 50.

After setup, auto-sync hooks into WooCommerce events:
- woocommerce_new_product — new products synced automatically
- woocommerce_update_product — updates synced automatically
- before_delete_post — deleted products removed from index

You can also manually sync individual products from the Preview & Sync admin page, which shows a searchable DataTables view of your entire catalog.

Content Sync

Beyond products, you can index blog posts, pages, and custom post types. Content sync is managed separately from product sync:

- Toggle auto-sync for content in Settings
- Choose which post types to index
- If WPML is active, filter by language
- Content syncs on save_post and is removed on before_delete_post

Admin Pages

After setup, the Contexa menu in WordPress provides:

Settings — API key, cache TTL (0-3600s), auto-sync toggles, content types, visitor tracking, error logging.

Preview & Sync — DataTables browser for your product catalog. See what Contexa has for each product, manually re-sync, or export as CSV.

Sync Status — Historical sync logs with success/failure tracking, error messages, and timestamps.

Content Sync — Manage WordPress content sync separately. Enable auto-sync, choose post types, filter by language.

Help — Shortcode reference and configuration guide.

WPML Integration

If WPML is detected, the setup wizard adds a language selection step. Select which languages to sync — only that content gets indexed.

Contexta temporarily disables WPML filters during sync to access all content, then filters by your selected languages. Each language is indexed separately for better relevance.

Content counts update in real-time as you select/deselect languages in the wizard.

Shopify Product Search App

Installation

Install the Contexa app from the Shopify App Store. The app uses standard Shopify OAuth 2.0 authentication. Once installed, product sync starts automatically via webhooks.

Product Sync

Contexa registers webhooks for real-time sync:

- products/create — new products indexed automatically
- products/update — changes synced in real-time
- products/delete — removed from index
- orders/create — tracked for analytics

You can also trigger a full catalog sync from the app admin. Pagination supports up to 250 items per page with batch processing.

Theme Integration

The app includes a Liquid theme block for the search widget. Add it to any section of your Shopify theme. Features:

- Real-time product search
- Inline autocomplete suggestions (150ms debounce, <5ms response)
- Add-to-cart integration
- Cart count updates
- Toast notifications

Product Search REST API

Search API Authentication

API requests accept either an API key or a JWT token in the Authorization header. Get your API key from the Contexa dashboard (Settings → API Keys) or from the WooCommerce/Shopify plugin settings.

// Option 1: API Key Authentication
fetch('https://api.contexa.co/api/data/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({ query: 'red running shoes' })
})

// Option 2: JWT Token Authentication
fetch('https://api.contexa.co/api/data/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  },
  body: JSON.stringify({ query: 'red running shoes' })
})

Product Search API

Search your product catalog with semantic understanding. Supports natural language filters, multi-language queries, and relevancy thresholds.

POST /api/data/search

// Request
{
  "query": "red running shoes",
  "limit": 12,              // Number or "max" for unlimited (default: 10)
  "relevancy": 8,           // Min relevancy threshold as percentage, e.g. 8 = 8% (default: 8)
  "language": "en",         // Optional: en, he, ar, es, fr, de
  "source": "https://...",  // Optional: your store URL
  "cart": [],               // Optional: current cart items
  "page_type": "search"     // Optional: search, category, homepage
}

// Response
{
  "results": [
    {
      "product_id": "123",
      "name": "Crimson Athletic Sneakers",
      "price": 89.99,
      "image": "https://...",
      "permalink": "https://...",
      "categories": ["Shoes", "Running"],
      "sku": "SNKR-RED-001",
      "stock_status": "instock",
      "relevancy": 94,
      "matchPercentage": "94%",
      "compositeScore": 0.94
    }
  ],
  "filters": {
    "priceMin": 29.99,
    "priceMax": 199.99,
    "categories": ["Shoes", "Running"],
    "colors": ["red"],
    "brands": ["Nike"]
  },
  "originalQuery": "red running shoes",
  "cleanQuery": "red running shoes",
  "metadata": {
    "totalMatched": 47,
    "returned": 12,
    "responseTime": "245ms"
  }
}

Note: Costs 1 credit per request. Rate limit: 30 requests/min per user.

Autocomplete Suggestions

Get search suggestions based on real user behavior. Ranked by: frequency (40%), recency (25%), success rate (20%), click-through (15%).

POST /api/data/suggestions

// Request
{
  "query": "red",
  "limit": 5,              // Max 10 (default: 5)
  "includeMetrics": false   // Optional: include scoring details
}

// Response (default)
{
  "suggestions": [
    "red running shoes",
    "red dress",
    "red jacket mens"
  ],
  "cached": true,
  "responseTime": 3
}

// Response (includeMetrics: true)
{
  "suggestions": [
    {
      "query": "red running shoes",
      "score": 0.87,
      "count": 142,
      "successRate": 0.95,
      "clickRate": 0.72,
      "trending": true
    }
  ],
  "cached": true,
  "responseTime": 3
}

Note: FREE — no credits consumed. Response time: <5ms from cache.

Upload Products

Upload product data to your Contexa index. Accepts JSON files via multipart form-data. The JSON file must contain either a plain array of products or an object with a "products" key. WooCommerce and Shopify plugins handle uploads automatically.

POST /api/data/process
Content-Type: multipart/form-data
Authorization: Bearer YOUR_JWT_TOKEN

// Form fields:
// - file: JSON file (.json)
// - strategy: "fixedLength" | "overlapping" | "semantic" (default: "fixedLength")
// - chunkSize: number (default: 200)

// JSON format — Option 1: plain array
[
  {
    "id": "product_123",
    "name": "Red Running Shoes",
    "description": "Lightweight running shoes for daily training",
    "price": "89.99",
    "currency": "USD",
    "sku": "SNKR-RED-001",
    "permalink": "https://yourstore.com/red-shoes",
    "image_url": "https://yourstore.com/images/red-shoes.jpg",
    "stock_status": "instock",
    "categories": ["Shoes", "Running"],
    "tags": [],
    "attributes": {},
    "product_url": "https://yourstore.com/red-shoes",
    "language": "en"
  }
]

// JSON format — Option 2: object with products key
{
  "products": [
    { "id": "product_123", "name": "Red Running Shoes", ... }
  ]
}

// Response (201 Created)
{
  "message": "File uploaded and queued for processing.",
  "jobId": "64abc123def456",
  "totalItems": 150
}

// Check job status
GET /api/data/job-status/:jobId

// Response
{
  "status": "completed",    // queued | processing | completed | failed
  "progress": 100,
  "totalItems": 150,
  "processedItems": 150
}

Note: Costs 1 credit per 100 products. Requires JWT authentication (login to the dashboard first). WooCommerce/Shopify plugins use their own dedicated upload endpoints.

Image Search

Search for products by uploading an image. Uses visual embeddings for similarity matching. Minimum similarity threshold: 50%.

POST /api/image/search
Content-Type: multipart/form-data
Authorization: Bearer YOUR_JWT_TOKEN

// Form fields:
// - image: File (JPEG, PNG, WebP)
// - limit: Number (default: 10)

// Response
{
  "results": [
    {
      "id": "product_456",
      "name": "Blue Denim Jacket",
      "similarity": 0.91,
      "image": "https://...",
      "price": 129.99
    }
  ]
}

Note: Costs 1 credit per request.

Recommendations

Five recommendation endpoints:

// All recommendation endpoints require authentication (JWT or API key)

// Similar Products
GET /api/recommendations/similar/:productId

// Trending Products
GET /api/recommendations/trending

// Personalized (requires visitor tracking)
GET /api/recommendations/personalized

// Frequently Bought Together
GET /api/recommendations/frequently-together/:productId

// Cart-Based
POST /api/recommendations/cart-based
{
  "cartItems": [
    { "productId": "product_123", "quantity": 1 },
    { "productId": "product_456", "quantity": 2 }
  ]
}

// All return:
{
  "recommendations": [
    {
      "id": "product_789",
      "title": "Product Name",
      "price": 49.99,
      "image": "https://...",
      "score": 0.87
    }
  ]
}

Note: Each request costs 1 credit. Returns up to 10 results.

Event Tracking

Send tracking events to power analytics, recommendations, and autocomplete suggestions. Two options: standard endpoint or high-throughput ingestion endpoint.

// Option 1: Standard tracking
POST /api/tracking/event

// Single event
{
  "type": "product_view",
  "visitorId": "anonymous_visitor_id",
  "timestamp": 1707000000000,
  "properties": {
    "productId": "product_123",
    "price": 89.99
  }
}

// Batch events (same endpoint)
{
  "events": [
    { "type": "page_view", "visitorId": "...", "timestamp": 1707000000000 },
    { "type": "add_to_cart", "visitorId": "...", "properties": { "productId": "123" } }
  ]
}
// Returns 202 Accepted

// Option 2: High-throughput ingestion (up to 1,000 events/batch)
POST /api/ingest/batch
{
  "events": [
    { "type": "page_view", "timestamp": 1707000000000, "sessionId": "..." },
    { "type": "product_view", "properties": { "productId": "123" } }
  ]
}
// Returns 202 Accepted with { eventsQueued, queueLength }

Note: FREE — no credits consumed. No rate limit (batch max 1,000 events per request). Supported types: page_view, product_view, add_to_cart, remove_from_cart, cart_state, search, recommendations_shown, purchase, identify.

Rate Limits

Rate limits vary by authentication level:

- General (unauthenticated): 100 requests per 15 minutes per IP
- Authenticated: 30 requests per minute per user
- Monthly plan limits: Free = 10,000/month, Pro = 50,000/month, Enterprise = 100,000+/month
- Tracking events: No rate limit (batch max 1,000 events per request)

Endpoint	Rate Limit	Credit Cost
Search	30 req/min per user	1 credit/request
Suggestions	30 req/min per user	Free
Trending	30 req/min per user	Free
Recommendations	30 req/min per user	1 credit/request
Data Upload	30 req/min per user	1 credit/100 products
Image Search	30 req/min per user	1 credit/request
Tracking Events	No limit	Free

JavaScript SDK for Site Search

Installation

Add the Contexa SDK to your website. It handles event batching, persistent visitor tracking, and session analytics automatically.

<script src="https://api.contexa.co/sdk/contexa-sdk.js"></script>
<script>
  const contexa = new ContextaSDK();
  contexa.init({ apiKey: 'YOUR_API_KEY', ingestionUrl: 'https://api.contexa.co' });
</script>

Initialization

The SDK requires manual initialization via contexa.init(). Both apiKey and ingestionUrl are required:

const contexa = new ContextaSDK();
contexa.init({
  apiKey: 'YOUR_API_KEY',
  ingestionUrl: 'https://api.contexa.co',  // Required — defaults to localhost without this
  batchSize: 50,           // Events per batch (default: 50)
  flushInterval: 5000      // Flush interval in ms (default: 5000)
});

Tracking Events

The SDK provides convenience methods for common events. All events are batched (50 per batch) and flushed every 5 seconds.

// Page view (automatic URL detection)
contexa.pageView();

// Product view
contexa.track('product_view', {
  productId: 'product_123',
  price: 89.99,
  title: 'Red Running Shoes'
});

// Add to cart
contexa.addToCart('product_123', 'Red Running Shoes', 1, { price: 89.99 });

// Search
contexa.track('search', { query: 'red running shoes' });

// Purchase
contexa.track('purchase', {
  orderId: 'order_456',
  revenue: 179.98,
  currency: 'USD',
  items: [
    { id: 'product_123', price: 89.99, quantity: 2 }
  ]
});

// Custom event
contexa.track('custom_event', {
  key: 'value'
});

Visitor Tracking

The SDK generates an anonymous visitor ID stored in localStorage. This ID persists across sessions and is used to:

- Link user actions for personalized recommendations
- Track conversion funnels
- Power session-based analytics

No personally identifiable information is collected. The visitor ID is a random string with no connection to real identity.

Ecommerce Search Features

Semantic Product Search

Unlike keyword matching, Contexa understands the meaning behind queries. "Red running shoes" matches "Crimson Athletic Sneakers" because the AI understands these are semantically similar.

The process:
1. Query text is normalized (Unicode normalization, punctuation removal)
2. Converted to a semantic vector using the embedding model
3. Matched against product vectors using cosine similarity
4. Results scored and ranked by combined semantic + filter scores
5. Top results validated for relevance by the validation model

Typo-Tolerant Product Search

Contexa uses Levenshtein distance with adaptive thresholds:

Word Length	Characters Allowed Wrong	Example
4-5 chars	1	"sheos" → "shoes"
6-8 chars	2	"runinng" → "running"
9+ chars	3	"sneakerss" → "sneakers"

Note: Combined with semantic matching, even heavily misspelled queries often return correct results.

Natural Language Filters

Customers can search with natural language and Contexa extracts structured filters automatically:

- "red shoes under $50" → color: red, category: shoes, price: <$50
- "Nike running shoes size 10" → brand: Nike, category: running shoes, size: 10
- "winter jacket blue large" → season: winter, category: jacket, color: blue, size: large

Filter extraction works in all supported languages. If the AI parser fails, Contexa falls back to regex-based extraction.

Site Search Autocomplete

Real-time inline suggestions as customers type. Powered by aggregated search behavior on your store:

Ranking Algorithm:
- Frequency: 40% — how often this query is searched
- Recency: 25% — how recently it was searched
- Success Rate: 20% — how often it returns results
- Click-Through: 15% — how often results are clicked

Performance: <5ms from Redis cache, 5-minute TTL.

Note: Suggestions appear based on recent search history from the last 30 days. This is a free feature — no credits consumed.

AI Product Recommendations

Similar Products

Finds products with the closest semantic match using vector cosine similarity. Best for product detail pages — "You May Also Like" sections.

Requires a productId. Returns up to 10 similar products ranked by similarity score.

Personalized

Uses a visitor's search history to recommend relevant products. Computes an average embedding from the visitor's past interactions and finds the closest matches. Excludes products the visitor has already seen.

Requires visitor tracking to be enabled. Best for homepages and logged-in dashboards.

Frequently Bought Together

Analyzes co-occurrence patterns in search sessions across all users. If customers who viewed Product A also viewed Product B, they're considered "frequently together".

Falls back to vector similarity if no co-occurrence data exists yet. Best for product pages — cross-sell sections.

Cart-Based

Recommends products that complement the current cart contents. Analyzes purchase patterns across all users to find items commonly bought alongside the cart items.

Requires cart items in the request body. Best for cart and checkout pages.

Search Analytics & Tracking

Search Performance Metrics

The Contexa dashboard provides:

- Total Queries — count of search queries over time
- Results Returned — total results across all searches
- Average Relevancy — composite relevancy score (0-1 scale)
- API Usage — current usage vs monthly credit limit
- Query/Result Trends — area charts over customizable date ranges
- Recent Searches — expandable list with per-result relevancy scores
- CSV Export — export search logs for analysis

Search Query Analytics

Deep dive into search performance:

- Top Queries — most searched terms with counts, relevancy, CTR, and conversion rate
- Zero-Result Rate — percentage of searches returning nothing
- Success Rate — percentage of searches with good results
- Query Quality Breakdown — distribution of query quality scores
- Similar Query Detection — identifies near-duplicate queries using Levenshtein similarity

Insights

Search Quality: Average relevancy score with trend, zero-result rate, success rate.

User Behavior: Total users, sessions, average session duration, conversion rate.

Product Performance: Top products by clicks/revenue, bottom performing by relevancy.

Conversion Funnel: Visual funnel from searches → clicks → purchases with stage-to-stage rates.

Event Types

All supported tracking event types:

Event Type	Description	When to Use
page_view	Page navigation	Every page load
product_view	Product detail view	Product page visits
add_to_cart	Item added to cart	Add-to-cart clicks
remove_from_cart	Item removed from cart	Cart removals
cart_state	Current cart snapshot	Cart page loads
search	Search query performed	Search submissions
recommendations_shown	Recommendations displayed	Rec widget loads
purchase	Order completed	Thank you page
identify	User identification	Login/signup events

Data Retention

Tracking events are automatically deleted after 90 days via TTL indexes. Search logs are retained indefinitely for powering suggestions and trending. User accounts and product data persist until deletion is requested.

All tracking uses anonymous visitor IDs — no PII is collected.

Search Pricing & Credits

Plans

Available plans:

Plan	Credits/Month	Best For
Free	10,000	Small stores, testing, evaluation
Pro	50,000	Growing stores with higher traffic
Enterprise	100,000+	Large catalogs, custom requirements

Note: Credits are included with your plan. Usage is tracked monthly and resets on the first of each month. Upgrade your plan for higher limits. Enterprise plans are custom — contact sales.

Credit Costs

What uses credits and what's free:

Action	Cost
Search query	1 credit
Recommendation request	1 credit
Data upload (per 100 products)	1 credit
Image search	1 credit
Autocomplete suggestions	Free
Trending searches	Free
Event tracking	Free
Analytics & dashboard	Free

Search Security & Privacy

Authentication Methods

JWT Tokens — stateless authentication for the dashboard. Access token + refresh token.

API Keys — fingerprint-scoped for integrations. Can be rotated/revoked from the dashboard.

Two-Factor Authentication — Optional TOTP-based 2FA with any authenticator app. 10 backup codes provided. 2-minute verification window.

Data Security

- All traffic encrypted with HTTPS/TLS
- Sensitive data encrypted at rest
- Passwords hashed with bcrypt
- Security headers enforced via Helmet.js (CSP, HSTS, X-Frame-Options)
- Data isolation: all data scoped to your API key fingerprint — no cross-store access
- Per-client isolated workers for processing

Privacy

- Anonymous visitor IDs only — no PII collected from customers
- Tracking can be disabled entirely with one toggle
- 90-day automatic cleanup for tracking events
- Data export available via API
- Right to deletion supported
- GDPR compliant (Shopify app handles all required webhooks)

Contexa AI Search Documentation

Getting Started with AI Ecommerce Search

What is Contexa AI Search?

How AI Product Search Works

Supported Ecommerce Platforms

Supported Languages

Creating an Account

WooCommerce Product Search Plugin

System Requirements

Product Search Setup Wizard

Product Search Shortcode

Product Search Templates

Recommendation Shortcodes

Product Search Index Sync

Content Sync

Admin Pages

WPML Integration

Shopify Product Search App

Installation

Product Sync

Theme Integration

GDPR Compliance

Product Search REST API

Search API Authentication

Product Search API

Autocomplete Suggestions

Trending Searches

Upload Products

Image Search

Recommendations

Event Tracking

Rate Limits

JavaScript SDK for Site Search

Installation

Initialization

Tracking Events

Visitor Tracking

Ecommerce Search Features

Semantic Product Search

Typo-Tolerant Product Search

Natural Language Filters

Site Search Autocomplete

AI Product Recommendations

Similar Products

Trending Products

Personalized

Frequently Bought Together

Cart-Based

Search Analytics & Tracking

Search Performance Metrics

Search Query Analytics

Insights

Event Types

Data Retention

Search Pricing & Credits

Plans

Credit Costs

Search Security & Privacy

Authentication Methods

Data Security

Privacy