How to Build an AI Shopping Assistant for Shopify

To build a Shopify AI shopping assistant, connect a server-side AI application to Shopify's Storefront MCP and UCP catalog tools, render the results as usable product and cart interfaces, and add strict rules for price, availability, customer data, and unsupported claims.

The model should handle conversation. Shopify should remain the source of truth for products, variants, policies, carts, checkout, and authenticated customer information.

This guide focuses on the production decisions that sit between Shopify's reference project and a reliable customer experience.

What Are You Actually Building?

A shopping assistant is not one model call attached to a chat bubble.

It is a small commerce application with six parts:

A customer-facing interface
A server-side conversation endpoint
An AI model that supports tool use
An MCP client connected to Shopify
Session and conversation storage
Evaluation, analytics, and human escalation

The model receives a shopper's message and decides whether it needs a commerce tool. The application calls that tool, returns the result to the model, and renders the final answer with interactive product or cart data.

The backend performs the privileged work. The browser should never contain model provider secrets or unrestricted customer tokens.

Start With One Valuable Job

Do not launch with a promise to "answer anything."

Choose a narrow first job that can be tested:

Find products from a large catalog
Compare products by structured attributes
Select a compatible part or accessory
Build a routine or bundle
Answer shipping and return questions
Help a shopper choose a valid variant
Add the selected variant to a cart

For a skincare store, the first job might be:

Recommend products by skin concern, ingredient preference, and routine step, then build a cart after the shopper confirms each item.

For an industrial supplier:

Find parts by application and specification, explain the evidence for compatibility, and escalate when a required specification is missing.

A precise job produces a better data audit, system prompt, interface, and test suite.

Decide Whether a Custom Assistant Is Justified

A custom build is usually justified when the experience depends on:

Merchant-specific product logic
Complex filters or compatibility rules
Custom bundles or guided selling
A branded interface
Existing account, loyalty, or support systems
Multiple languages or markets
Detailed analytics and controlled experiments
Human handoff with conversation context

An off-the-shelf app may be sufficient for a small catalog, common support questions, and a standard chat interface.

Do not choose custom development merely to change the assistant's tone. Choose it when the buying logic or system integration is meaningfully specific to the business.

The Recommended Architecture

Shopify's reference architecture uses a theme app extension for the chat interface and an app backend that acts as the MCP client.

A production request typically follows this path:

The shopper sends a message from the storefront.
The browser sends it to the app's server-side chat endpoint.
The server loads the permitted conversation history.
The app retrieves the live Shopify tools available to this store and agent.
The model decides whether to call a catalog, policy, cart, or account tool.
The server validates and executes the tool call.
The tool result is returned to the model.
The server streams text and structured UI events to the browser.
The storefront renders product cards, options, cart changes, or an escalation action.
The application records a privacy-safe outcome event.

The same backend pattern can support a Liquid theme, a Hydrogen storefront, or another headless frontend. The presentation layer changes; the commerce authority does not.

Use Shopify's Live Catalog Before Adding a Vector Database

Many older AI commerce tutorials begin by copying the entire product catalog into a vector database.

That is no longer the default starting point for a Shopify shopping assistant.

Storefront Catalog MCP already provides natural-language product discovery and current product retrieval. Its UCP-conforming tools include:

search_catalog
lookup_catalog
get_product

Using Shopify's live catalog reduces the risk of recommending stale prices, unavailable variants, or deleted products from a separately synchronized index.

A vector database can still be useful for content that Shopify's tools do not cover well, such as:

Long buying guides
Technical manuals
Installation documentation
Original editorial content
Support transcripts approved for retrieval
Proprietary compatibility knowledge

If you add retrieval, keep the responsibilities separate:

Use the knowledge index for explanatory content.
Use Shopify tools for products, variants, prices, availability, carts, and checkout.

Never let an embedding result override current commerce data.

Connect to the Correct Shopify Capabilities

Shopify's agentic commerce interfaces are moving toward the Universal Commerce Protocol. Current documentation separates some capabilities across endpoints and access levels.

For store-scoped catalog discovery, Shopify documents:

https://{storeDomain}/api/ucp/mcp

Catalog requests require an agent profile that declares the agent's identity and capabilities.

Shopify also documents standard Storefront MCP capabilities for policy questions and cart operations. Broader UCP documentation covers carts, checkout, and orders.

Do not freeze a copied list of tool names into the application. At startup or per compatible session:

Connect to the relevant MCP server.
Call tools/list.
Validate the returned schemas.
Expose only the allowed tools to the model.
log schema changes and unsupported capabilities.

This matters because Shopify's MCP and UCP surface is actively evolving.

Treat MCP Results as Typed Data

The model should not be responsible for converting arbitrary prose into cart operations.

A safer tool loop looks like this:

async function runShoppingTurn(input: ShoppingTurnInput) {
  const history = await loadSafeHistory(input.sessionId);
  const tools = await discoverAllowedTools(input.storeDomain);
 
  const decision = await model.respond({
    system: shoppingRules,
    messages: [...history, input.message],
    tools,
  });
 
  if (!decision.toolCall) {
    return streamText(decision.text);
  }
 
  const validatedCall = validateToolCall(decision.toolCall, tools);
  const toolResult = await shopifyMcp.call(validatedCall);
 
  return model.respond({
    system: shoppingRules,
    messages: [...history, input.message, decision, toolResult],
    tools,
  });
}

This is an architectural example, not code tied to a specific model SDK. In production, include bounded tool loops, timeouts, cancellation, structured errors, and observability.

The application must validate tool arguments against the live schema before execution. Model-generated arguments are untrusted input.

Separate Conversation State From Commerce State

Conversation state includes:

The shopper's stated goal
Preferences mentioned in the current session
Products already discussed
Clarifying questions and answers

Commerce state includes:

Product and variant identifiers
Current price
Availability
Cart ID and cart lines
Market and currency
Checkout URL
Authenticated customer state

Conversation state can help the agent remember that a shopper prefers blue. It must not be trusted to remember that the blue medium variant is still available or costs the same amount.

Refresh commerce state through Shopify before presenting a final recommendation or changing the cart.

Design the System Rules Around Evidence

A good system instruction is not mainly a brand voice document.

It should define operational rules such as:

Search before making product recommendations.
Base product claims only on returned product or approved knowledge data.
State when a requested attribute is missing.
Retrieve current product details before confirming a variant.
Never invent availability, delivery dates, discounts, or policy exceptions.
Ask before adding an item to the cart.
Summarize every cart change.
Do not access customer information without authentication.
Escalate medical, legal, safety-critical, or unsupported compatibility questions.
Keep answers concise enough to shop from.

Tone comes after factual boundaries.

Ask Clarifying Questions Selectively

An assistant should not turn every request into an interview.

Ask when the answer materially changes the recommendation:

Budget
Size
Destination market
Compatibility requirement
Material or ingredient restriction
Intended use
Delivery deadline

Do not ask for information the tool can already infer safely from storefront context, current market, or the selected product.

A useful rule is to ask the smallest question that removes the largest purchasing uncertainty.

Render Commerce UI, Not Just Chat Text

Product recommendations should not appear only as paragraphs.

Render structured product cards with:

Product image
Exact title
Current localized price
Relevant evidence for the recommendation
Available options
Link to the product page
Clear select or add-to-cart action

Cart changes should show:

Added or removed item
Selected variant
Quantity
Updated subtotal
Checkout action

This lets the shopper verify what the agent is doing. It also improves accessibility and reduces the chance that a product identifier gets lost in conversational text.

Use the model for explanation. Use deterministic components for commerce actions.

Keep Cart Mutations Confirmable and Idempotent

Cart operations are write actions. Treat them differently from product search.

Before execution:

Resolve a specific purchasable variant.
Confirm quantity.
Confirm the target cart.
Validate the live tool input.

After execution:

Render the returned cart state.
Tell the shopper exactly what changed.
Provide undo or quantity controls where supported.
Avoid repeating the mutation if the response stream reconnects.

Use idempotency mechanisms required by the current capability. A retry must not add a second item accidentally.

Checkout totals remain authoritative. The assistant should not promise a final total before shipping, duties, taxes, discounts, and market rules have been applied.

Add Customer Accounts Only When the Use Case Needs Them

Public catalog search does not justify access to personal customer data.

Use Shopify's Customer Accounts MCP server when the assistant needs authenticated features such as:

Order lookup
Order details
Account information
Reordering
Supported return workflows

Shopify documents OAuth 2.0 with PKCE for customer authentication and requires appropriate protected customer data access.

Implement authentication as an explicit transition:

The shopper asks for an account-specific action.
The app explains that sign-in is required.
Shopify handles customer authentication.
The app securely receives the authorized token.
The original request is retried with the permitted account tools.

Do not ask the shopper to paste an order access token, password, or full payment information into chat.

Stream Responses Without Hiding Tool State

Streaming makes the assistant feel responsive, but a typing effect is not enough.

The interface should expose meaningful states:

Understanding request
Searching products
Checking options
Updating cart
Waiting for sign-in
Could not retrieve current data

Shopify's reference project uses server-sent events for its chat stream. WebSockets or another transport can also work if the hosting architecture requires it.

Whichever transport you choose:

Abort work when the shopper cancels.
Set timeouts around model and tool calls.
Distinguish retryable failures from invalid requests.
Do not display raw provider or MCP errors.
Preserve enough trace data to diagnose failures.

Build for Model Portability

Shopify's reference project uses Claude but notes that the model can be replaced.

Keep provider-specific code behind an adapter:

interface ShoppingModel {
  respond(input: {
    system: string;
    messages: ConversationMessage[];
    tools: CommerceTool[];
  }): Promise<ModelTurn>;
}

Your business rules, Shopify MCP client, validation, evaluation cases, and UI event format should not depend on one provider's message shape.

Portability gives the team room to compare:

Tool-calling accuracy
Response latency
Cost per resolved conversation
Multilingual performance
Safety behavior
Product recommendation quality

Do not switch models based on a general benchmark alone. Run the same store-specific evaluation set against each candidate.

Security Requirements

At minimum:

Keep model keys and app secrets server-side.
Validate every tool call.
Allowlist store domains instead of accepting arbitrary MCP URLs.
Restrict tools by session and authentication state.
Encrypt customer tokens at rest.
Use short-lived customer access where supported.
Verify app and webhook requests.
Apply rate limits by store, session, and network risk.
Set maximum message and history sizes.
Sanitize rendered model output.
Redact sensitive fields from logs.
Define retention and deletion rules for conversations.
Record cart and account mutations in an audit trail.

The model is not a security boundary.

Prompt injection can appear in a shopper message, product description, knowledge document, or fetched page. Tool permissions and server-side validation must remain effective even when the model follows a malicious instruction.

Decide what the application truly needs to retain.

For many pre-purchase assistants, a random session ID and short conversation window are enough. Avoid attaching an identified customer profile before it provides clear value and the shopper has authenticated.

Tell shoppers:

That they are interacting with AI
What conversation data is stored
Whether messages may be reviewed for quality
How long data is retained
How to request deletion
How to reach a person

Do not send personal or payment data to a model unless the use case, provider terms, permissions, and privacy disclosures explicitly support it.

Test With an Evaluation Set, Not a Demo Script

A polished happy-path demo proves very little.

Build a repeatable evaluation set from real customer questions. Include:

Product discovery

Broad intent with several valid products
Specific attribute present in product data
Requested attribute missing from product data
No matching product
Product unavailable in the shopper's market

Variant selection

Valid option combination
Unavailable combination
Combination that does not exist
Ambiguous size language
Price-changing variant

Policies

Direct policy answer
Product-specific exception
Question the policy does not answer
Request for an exception the merchant has not promised

Cart

Add one confirmed variant
Change quantity
Remove an item
Retry after a network interruption
Product becomes unavailable before mutation

Safety and security

Prompt injection in a customer message
Instruction to reveal the system prompt
Request for another customer's order
Unsupported medical or compatibility claim
Malicious URL presented as a store domain

Score each case for:

Correct tool choice
Correct tool arguments
Grounded final answer
Correct product and variant
Appropriate uncertainty
Safe mutation behavior
Useful interface output
Latency

Run the suite whenever prompts, models, tools, product data, or application code change.

Measure Commercial Outcomes

Do not optimize for the number of messages sent.

Track:

Search success rate
No-result and low-confidence queries
Product-card click-through
Variant selection completion
Assisted add-to-cart rate
Checkout handoff rate
Assisted conversion rate
Revenue per assisted session
Human escalation rate
Resolution rate by intent
Incorrect recommendation reports
Return reasons after assisted purchases
Model and tool cost per resolved session

Segment results by device, market, catalog area, and assistant job. A high overall conversion rate can hide a product category where recommendations consistently fail.

Whether its current tool assumptions match Shopify's live UCP schemas
How sessions and conversations are isolated
How errors and reconnects affect tool calls
Whether its UI meets your accessibility requirements
How it stores customer tokens and conversation data
Whether the model adapter supports your evaluation needs
How the app will be monitored and rolled back

Reference code is a starting point, not a substitute for system design.

Next Steps

If the protocol terms are still unfamiliar, read Shopify Storefront MCP: A Merchant Guide to AI Shopping.

Before building, run the Shopify Hydrogen AI Search Audit and review Product Schema for Shopify Hydrogen. The same product-data gaps that weaken search and structured data also weaken an assistant's recommendations.

Webmakers Studio builds custom Shopify apps, Hydrogen storefronts, and commerce integrations. If guided selling is commercially valuable for your catalog, contact us to scope the data, tools, interface, guardrails, and pilot.

Related Articles