Quick Search Spotlight

Quick Search Spotlight in Ecommerce Search is a curated list of up to 10 search phrases shown to users when they activate the search box, before they start typing. The purpose is to guide users who don't yet know what they're looking for toward trending or promoted content.

How it works

When a user focuses on the search box with an empty search phrase, the search API returns a list of popular search phrases instead of suggestions. Once the user starts typing, quick search spotlight are replaced by regular suggestions. Quick search spotlight and regular suggestions are mutually exclusive — only one is returned at a time.

Each phrase is validated before being included in the response. Only phrases that produce at least one result (product or content) are shown. This ensures users are never directed to empty search results.

Position groups

The quick search spotlight list is organized into 10 positions (1–10). Each position forms a position group that determines which phrase is shown at that spot in the list.

Each position can contain:

• Manual entries — admin-created phrases with time-based scheduling
• A default entry — automatically sourced from the most popular search phrases

Manual entries take precedence over the default. When no manual entry is active at a position, the default phrase is shown automatically.

Automatic population

By default, quick search spotlight is automatically populated from the most frequently searched phrases. This is based on real user search data — specifically, the click frequency on suggestion results over the last 30 days.

This means that without any admin configuration, the quick search spotlight list is fully functional and reflects actual user behavior. This is the recommended mode for businesses where each shop has different search patterns.

Deduplication

A phrase that exists as a manual entry — whether it is currently active, expired, or scheduled — will not appear as an automatically populated phrase. This prevents scenarios where an expired campaign phrase (e.g., "christmas gifts") reappears in the list because it was frequently searched.

Manual entries and scheduling

Administrators can create manual entries to promote specific phrases tied to campaigns, seasons, or sponsored content. Each manual entry has:

• A phrase — the search text shown to users
• A position (1–10) — where it appears in the list
• A start date — when it becomes active
• An optional end date — when it expires (omit for indefinite entries)

Entry types

Overlap rules

Only one manual entry can be active at a given position at any time. When creating or editing entries, the system validates that the time period does not overlap with existing entries at the same position.

Special case: If an existing entry at a position is indefinite (no end date), a new entry can still be added with a start date after the indefinite entry's start date. The new entry takes precedence when it becomes active, temporarily overriding the indefinite entry.

Exclude list

The exclude list allows administrators to block specific phrases from ever appearing in the quick search spotlight list. This applies to both manually created and automatically populated phrases.

Use cases include:

• Blocking competitor brand names
• Removing inappropriate or irrelevant phrases
• Seasonal cleanup (e.g., removing holiday terms after a campaign)

Scope configuration

Quick search spotlight are controlled per scope via the includePopularSearches setting. When enabled, quick search spotlight are returned for empty phrase searches in that scope. When disabled, the response does not include a quick search spotlight list.

Publication flow

Changes to quick search spotlight (adding, editing, or deleting entries, and modifying the exclude list) do not take effect immediately. They follow the standard publication flow:

1. Make changes on the Quick Search Spotlight page
2. Review pending changes on the Publication page
3. Publish to make the new configuration active

This ensures administrators have full control over when changes go live and can review all pending changes before publishing.

Search API response

Quick search spotlight suggestions are returned in the unified search response when the search phrase is empty and the scope has quick search spotlight enabled:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "products": [],
  "suggestions": [],
  "popularSearches": [
    {
      "phrase": "christmas gifts",
      "hits": ["Product"]
    },
    {
      "phrase": "winter jackets",
      "hits": ["Product"]
    },
    {
      "phrase": "gift cards",
      "hits": ["Product", "Content"]
    }
  ]
}

Each entry contains: