Skip to main content
The Medusa integration connects your MedusaJS (v2) store with Totebot. Your AI agent gets access to your product catalog, recommends products with live prices and availability, answers order questions, and attributes orders back to the conversations that drove them. To access this integration, navigate to Integrations → Medusa in your dashboard.
Medusa is available on all plans.

​
Before you start

You need two API keys from your Medusa admin:
  • Secret API key: in your Medusa admin, go to Settings → Secret API Keys and create a key (starts with sk_).
  • Publishable API key: go to Settings → Publishable API Keys and create a key (starts with pk_). The key must be linked to the sales channel your storefront sells through.

​
Step 1: Connect your store

1

Open the connect form

Click Connect on the Medusa integration card.
2

Enter your server URL and keys

Enter your Medusa server URL (the backend, for example https://medusa.yourstore.com), the secret API key, and the publishable API key. Totebot validates both keys against your store before saving.
3

Add your storefront URL (recommended)

Enter the URL customers shop on (for example https://yourstore.com). The agent uses it to build product and checkout links it can share in chat. Without it, the agent can describe products but cannot link to them.
4

Finish

Click Connect. Your product catalog starts syncing automatically.

​
Step 2: Enable real-time updates

Medusa has no built-in webhooks, so Totebot provides a small subscriber file you add to your Medusa project. It notifies your agent the moment products change or orders are placed. Without it, the catalog only updates when you click Update Now in the dashboard.
1

Download the subscriber

On the Medusa integration page, open the Status tab and click Download subscriber to get totebot.ts.
2

Add it to your Medusa project

Place the file at src/subscribers/totebot.ts in your Medusa codebase.
3

Set the environment variables

Copy the three variables shown on the Status tab (TOTEBOT_API_URL, TOTEBOT_AGENT_ID, TOTEBOT_WEBHOOK_SECRET) into your Medusa server’s environment. Keep the webhook secret private; it signs every event sent to Totebot.
4

Deploy and verify

Restart or redeploy your Medusa server. Edit any product in your Medusa admin and confirm the change appears in the Product catalog tab within seconds.

​
Step 3: Add the chat widget to your storefront

Medusa storefronts are custom sites, so the widget installs like on any website: copy the embed snippet from Channels → Web widget in your dashboard and add it to your storefront layout. See the web widget guide for details.

​
Let the agent see and update the customer’s cart

Medusa is headless, so the agent can’t auto-discover the shopper’s cart — you add a small bridge to your storefront that shares it. Once it’s in place, the agent and the in-chat product cards can read and update the same cart the shopper sees, and add-to-cart from chat works. See the Medusa cart bridge guide for copy-paste setup (Next.js, React SPA, and vanilla JS), the live-refresh events, and the required STORE_CORS setting. The bridge also strengthens purchase attribution: orders are credited to conversations even when the customer checks out without clicking a link from the chat.

​
What the agent can do

  • Search and recommend products from your catalog, with live prices and availability. Sale prices from active price lists are reflected automatically.
  • Show product cards in chat so customers can view variants, options, and stock, and jump to the product page.
  • Read and update the customer’s cart — answer questions about items and totals, and add or change items from chat (requires the cart bridge).
  • Look up orders by order number and email when you enable the order lookup tool on the integration page. The email must match the one on the order.
  • Attribute purchases to conversations, so Analytics shows the revenue your agent generated.

​
Product catalog

The Product catalog tab on the integration page lists every synced product. You can check sync status, trigger a re-sync, exclude products from the agent, and open each product to see exactly what data the agent works with.