How to build an AI shopping assistant on your product catalog

Before you start

An AI shopping assistant is a chat interface that answers shoppers in natural language and only recommends products that exist in your catalog. To build one on Medusa, you need:

• A Medusa v2.21.1+ application. Query's search method and the POST /store/search route require it.
• A Medusa Cloud project on the Scale or Enterprise plan for vector and hybrid search with Medusa Search. The self-hosted PostgreSQL search provider rejects vector queries.
• An LLM provider of your choice, called from your own code.
• A publishable API key, which scopes Store API requests to sales channels.

Medusa docs don't include a full customer-facing shopping assistant tutorial. The steps below combine documented building blocks.

1. Index your catalog for semantic search

This step lets the assistant find products by meaning, such as "something warm for a winter hike". Add a vector field to your product index definition in src/search. On the Enterprise plan, Medusa Search computes embeddings for you with the embed() modifier. On the Scale plan, you compute embeddings with your own model and pass them as search_options.vector.value.

Put the defining text first in what you embed, such as title, type, and description. Keep prices, stock, and region out of it. Those are exact constraints, so index them as filterable fields instead.

2. Map the assistant's tools to Store API routes

This step gives the LLM actions it can call. Each tool wraps a Medusa Store API route, so prices, stock, and promotions come from Medusa, not from the model.

3. Add a custom API route for the assistant

This step connects the LLM to retrieval. The Medusa Search AI search assistant example defines a POST /store/assistant route. Your own toSearchQuery function asks the LLM to turn the shopper's message into a search string, then query.search ranks products with it:

123456789101112131415
const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
const searchQuery = await toSearchQuery(req.body.message)

const { data } = await query.search({
  entity: "product",
  fields: ["id", "title", "handle", "thumbnail"],
  filters: { q: searchQuery, status: "published" },
  search_options: {
    vector: {
      field: "title_embedding",
      query: searchQuery,
      semantic_ratio: 0.7,
    },
  },
})

Passing text as vector.query requires a field with embed(), which is Enterprise-only. Keep semantic_ratio below 1 so brand names and model numbers the shopper typed still count.

4. Add guardrails so the assistant stays grounded

This step stops the assistant from inventing products or prices. A grounded answer is one where every product, price, and stock level comes from a tool result.

• Render product cards from the route's response, not from model text.
• Read totals from the cart that the Store API returns.
• Ask the shopper to confirm before the assistant completes the cart.
• Cap relation expansion with http.storeRelationsLimit, and add rate limiting middleware to the assistant route.

How a Medusa shopping assistant compares with Algolia Agent Studio and Shopify

Algolia Agent Studio connects an LLM, such as OpenAI or Gemini models, to Algolia indices for grounded answers. Its docs focus on search and retrieval, so cart and checkout stay in your commerce backend.

Shopify removed Storefront MCP's catalog and cart tools in favor of UCP servers, and points merchants who want no-code chat to the Inbox agent in Shopify Inbox. With Medusa, you write the conversational layer yourself and own every tool it calls.

When Medusa is not the right choice for a shopping assistant

Medusa is not the right choice if you want a chat assistant without writing code. A hosted option such as Shopify's Inbox agent is faster to set up. Medusa also needs the Scale plan or higher on Medusa Cloud for semantic search, or your own search provider when you self-host.