AI Search for Medusa

Install our Medusa plugin to put the AI Search Bar on your storefront

Overview

Shoppers know what they want but not what it is called, so they give up on the search box. The AI Search Bar answers what they mean: type "something warm for cold weather" and it finds your sweatpants, even though not one of those words is in the product name. Type "how long does delivery take" and it finds the page that says so.

The plugin reads your catalogue through your own Medusa, with the prices, discounts and stock your store is charging right now, and we read your storefront pages ourselves. There is no API key to create.

Medusa Is Headless, So Read This First

Every other shop platform we support renders its own pages, so our plugin can put the bar on them. Medusa is different: your backend serves the admin and the API, and your storefront is a separate application on a separate address. Two things follow.

The plugin needs two addresses. Your storefront address is where shoppers are, and it is what we index and what product links are built from. Your backend address is where this Medusa answers, and it is where the catalogue feed lives. Both are on the settings screen.
You paste one tag into your storefront, once. After that every setting reaches it from the plugin, so you never edit the storefront again.

Requirements

Medusa 2.x, on Node 20 or newer.
Your backend has to be able to make outgoing HTTPS requests, because the plugin talks to us directly.
Your backend has to be reachable from the internet, because we read your catalogue from it.

Installing the Plugin

From your Medusa folder:

npm install @asyntai/medusa-plugin-ai-search

Add it to medusa-config.ts:

module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: "@asyntai/medusa-plugin-ai-search",
      options: {},
    },
  ],
})

Then create the plugin's own table and restart:

npx medusa db:migrate

In the admin:

Open AI Search in the left menu.
Check the Storefront address. We guess it from your STORE_CORS setting, so it is usually right already.
Press Connect to Asyntai. A window opens where you sign in or create a free account.
Wait a few minutes while we read your store. The AI Search page tells you when the bar is live.

Putting the Tag on Your Storefront

The AI Search page shows you one line. Paste it into your storefront so it loads on every page:

<script async src="https://YOUR-MEDUSA/asyntai-search/loader"></script>

That address decides everything: your site id, where the bar goes, its colour, and whether it shows at all. Change a setting in the Medusa admin and your storefront follows within five minutes.

If You Use the Medusa Next.js Starter

The starter uses the Next.js App Router, which drops a plain script tag written into <head>. Use next/script in src/app/layout.tsx instead, inside <body>:

import Script from "next/script"

<Script
  src="https://YOUR-MEDUSA/asyntai-search/loader"
  strategy="afterInteractive"
/>

The starter also ships no search box of its own, so there is nothing for the bar to replace. Set Where the bar goes to Only where I put a placeholder and add <div data-asyntai-search /> wherever the bar should appear.

Set Product path to match your own default region, for example /us/products/{handle}. The starter puts a country code in front of every path, and that is how search results link to a product page.

Choosing Where the Bar Appears

There is one setting, Where the bar goes, with two answers.

Replace the storefront's own search box

The default. The bar finds the search box your storefront shows, hides it, and takes exactly the same place. If a shopper presses Enter without picking a result, your usual search page still opens, so nothing they already know stops working.

Only where I put a placeholder

Nothing in your header changes. Put <div data-asyntai-search></div> in your storefront wherever the bar should go, and the bar renders into it. This is the right answer for most Medusa storefronts, because a custom storefront often has no search box to replace.

The Other Settings

Product path. How your storefront addresses a product, with {handle} standing for the product. The default is /products/{handle}.
Search box to replace. Leave it empty and we find the box ourselves. Fill in a CSS selector only if we pick the wrong one, for example header form[role=search].
Placeholder text. Leave it empty and each shopper sees it in their own language.
Accent colour. Leave it empty to use the colour set in your Asyntai dashboard.
Let Asyntai read the catalogue. On by default. Switch it off and the bar searches your pages only.

Press Save after you change any of these.

Changing the Backend address after you have connected means we still read your catalogue from the old one. The screen says so when it happens, and pressing Connect again fixes it.

What the Bar Searches

Your storefront pages, as we read them from your site. And your products: name, description, categories, collection, price and availability come from your own Medusa through a read-only feed the plugin adds at /asyntai-search/feed. Every request to it carries a fresh timestamp and a signature made with a token only your store and Asyntai hold, and your store refuses one whose clock is more than five minutes out.

The price is Medusa's own calculated price for your default region, so a price list or a promotion a shopper sees, we see. Stock comes from your inventory levels, so a sold-out product says so. Only published products are searched, and one you unpublish disappears from the results at the next sync.

Trying It Before Your Shoppers Do

The AI Search page has a Try it button. It opens your real search bar, on your real catalogue, in a new tab. Searches you run there do not count against your monthly allowance.

Plans and Limits

A store connected through this plugin runs the bar on any plan, including the free one. Your monthly reply allowance still applies, and searches and chat replies share it. The AI Search page shows how much of the month is left.

When the allowance runs out, the bar removes itself and your storefront's own search box comes straight back. Your shoppers keep being able to search. They are never left typing into a box that answers nothing.

The plugin checks this as your storefront asks for the tag, so the bar comes back by itself when your allowance resets. You do not have to update or reinstall anything.

If Something Does Not Work

No AI Search entry in the admin menu. Restart your Medusa after installing, so the dashboard is built with the plugin in it.
No bar appears. Open the AI Search page and read the line under the status badge. It says exactly why the bar is off.
Still no bar, and the status says Live. Open your storefront and check the tag is really in the page. On the Next.js starter a plain script tag in <head> is silently dropped: use next/script.
A change you saved has not reached shoppers. The tag is cached for five minutes. Wait, or reload with the cache cleared.
Results link to pages that do not exist. Your Product path does not match your storefront. Fix it, and the links are rebuilt at the next sync.
Could not reach Asyntai. Your backend cannot make outgoing HTTPS requests. Ask your host to allow them.
Products are missing. Check that they are published. The feed sends what your store itself would show.
Your browser blocked the pop-up. Allow pop-ups for your admin and press Connect again.

Disconnecting

Press Disconnect on the AI Search page. The bar stops at once, the feed stops answering, and your usual storefront search takes over. Your own settings are kept, so connecting again does not mean choosing them all over. Removing the plugin and rolling back its migration removes everything it added, including its own database table.

Using the Chatbot as Well

This plugin adds the search bar only. To add the chat assistant too, install our separate Medusa chatbot plugin. The two work side by side on the same pages and share the same knowledge base.

Документация