> ## Documentation Index
> Fetch the complete documentation index at: https://docs.totebot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Connect Totebot to your MedusaJS store

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.

> [!NOTE]
>
> 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](/integrations/web-widget) 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](/integrations/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](/integrations/medusa-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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.