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

# Add AI voice to a Shopify store

> Embed the SmartAlex widget in Shopify by pasting one script tag into theme.liquid or a custom Liquid snippet, so Alex answers order status, returns, and product questions by voice and chat.

Shopify does not need a plugin or a fake app for this. The SmartAlex widget is a single script tag. You paste it once into your theme (or into a custom Liquid snippet), and Alex appears on every storefront page: your product pages, cart, collections, and checkout-adjacent flows. Shoppers can ask "where is my order", "how do I return this", or "does this come in a larger size" and get an answer by voice or chat instead of leaving to email you.

<Info>
  This is the honest integration path today. There is no SmartAlex Shopify app in the App Store. The real, live surface is the widget script (below), the [MCP server](/mcp/overview) for operating your account from an AI client, and [Custom HTTP Tools](/essentials/agent-tools) for letting Alex look up live order data mid-conversation. A public REST API and native app are in private beta.
</Info>

## What you will need

* A SmartAlex workspace with at least one published agent. If you do not have one yet, start at the [quickstart](/quickstart).
* Your **tenant ID**. Open the widget code panel inside SmartAlex, or ask an MCP client to run `smartalex_get_widget_install_code`. It is a UUID that you drop into the snippet in place of `YOUR_TENANT_ID`.
* Edit access to your Shopify theme (Online Store > Themes).

## The snippet

This is the exact tag SmartAlex generates. The only value you change is `YOUR_TENANT_ID`. There is no variant, colour, or agent attribute in the snippet: the widget reads its published config from the server at load time, so restyling in Widget Studio never means re-pasting.

```html theme={null}
<!-- SmartAlex Widget -->
<script
  src="https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js"
  data-tenant-id="YOUR_TENANT_ID"
  async>
</script>
```

## Method 1: paste into theme.liquid

This is the most reliable option and puts the widget on every page of the storefront.

<Steps>
  <Step title="Open your theme code">
    In Shopify admin, go to **Online Store > Themes**. On the theme you want to edit, click the **...** (three dots) button and choose **Edit code**.
  </Step>

  <Step title="Open theme.liquid">
    In the left file tree, under **Layout**, open `theme.liquid`. This is the master wrapper that renders on every storefront page.
  </Step>

  <Step title="Paste the snippet before the closing body tag">
    Scroll to the bottom of the file and find `</body>`. Paste the SmartAlex snippet on its own line directly above it, with your real tenant ID in place of `YOUR_TENANT_ID`.

    ```liquid theme={null}
        <!-- SmartAlex Widget -->
        <script
          src="https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js"
          data-tenant-id="a1b2c3d4-0000-0000-0000-000000000000"
          async>
        </script>
      </body>
    </html>
    ```
  </Step>

  <Step title="Save and preview">
    Click **Save**, then open your live store (or the theme preview) in a new tab. The widget loads on the bottom of the page. If you do not see it, hard-refresh once to clear the cached theme.
  </Step>
</Steps>

<Tip>
  Editing the live theme applies immediately. If you would rather test first, duplicate the theme, add the snippet to the copy, preview it, and only then publish. Because the snippet is byte-identical across every widget variant, nothing about it changes when you go live.
</Tip>

## Method 2: a reusable Liquid snippet

If you prefer to keep third-party scripts out of `theme.liquid`, put the tag in its own snippet and render it. This keeps the code in one named file that is easy to find and remove later.

<Steps>
  <Step title="Create the snippet file">
    In **Edit code**, under **Snippets**, click **Add a new snippet** and name it `smartalex-widget`. Shopify creates `snippets/smartalex-widget.liquid`.
  </Step>

  <Step title="Paste the tag into the snippet">
    ```liquid theme={null}
    <!-- SmartAlex Widget -->
    <script
      src="https://api.getsmartalex.com/storage/v1/object/public/widget-assets/smartalex-widget.js"
      data-tenant-id="YOUR_TENANT_ID"
      async>
    </script>
    ```
  </Step>

  <Step title="Render it from theme.liquid">
    Back in `theme.liquid`, add this line just before `</body>`:

    ```liquid theme={null}
    {% render 'smartalex-widget' %}
    ```
  </Step>

  <Step title="Save and preview">
    Save both files and reload your store. On an Online Store 2.0 theme you can alternatively drop a **Custom Liquid** section from the theme editor and paste the same tag, though `theme.liquid` is the surest way to load it site-wide.
  </Step>
</Steps>

## Choosing a variant for retail

You pick the widget style in Widget Studio, not in the snippet. For a store, the two most useful are the default **Pill** (voice-first with chat, compact and unobtrusive) and **Ask Alex** (a premium voice and text messenger). Chat-only variants suit stores that would rather keep everything text.

| Studio label   | Docs / storefront name | Interaction           | Good for a store when                                      |
| -------------- | ---------------------- | --------------------- | ---------------------------------------------------------- |
| Pill (default) | Pill                   | Voice-first plus chat | You want a small floating button that expands into chat    |
| Chat Bar       | Chat bar               | Text                  | You want an always-visible input at the bottom of the page |
| Side Panel     | Side panel             | Text                  | You want a full-height help panel that slides in           |
| Voice Pill     | Voice pill             | Voice only            | You want a pure "tap to talk" experience                   |
| Widget v2      | Ask Alex               | Voice plus text       | You want the premium messenger with persistent calls       |

<Note>
  One variant is known by three names, which trips people up: the database calls it `ask_alex_v2`, Widget Studio labels it **Widget v2**, and the storefront experience is **Ask Alex**. It is the same widget. The voice-only variants (Voice pill and Ask Alex) only appear in the picker once your agent runs on the SmartAlex voice engine. See [widget variants](/essentials/widgets) for the full breakdown.
</Note>

## Answering order status and returns

The value in retail is Alex handling the repetitive "where is my order" and "how do I return this" questions before they reach your inbox. General answers (store hours, shipping policy, sizing) work out of the box from your agent's knowledge. To answer a **specific** order, Alex needs to look it up live.

That live lookup is a [Custom HTTP Tool](/essentials/agent-tools): during the conversation, Alex calls an HTTPS endpoint you host, passes the order number or email, and reads back the status your endpoint returns. Your endpoint is where you talk to the Shopify Admin API on your own side. Custom HTTP Tools are part of the **Power Tools** add-on (\$29/mo).

```mermaid theme={null}
flowchart LR
  A[Shopper on your store] --> B[SmartAlex widget]
  B --> C[Alex answers by voice or chat]
  C -->|Where is my order?| D[Custom HTTP Tool calls your endpoint]
  D -->|Your endpoint queries Shopify Admin API| C
  C -->|Qualified lead or callback| E[Saved to the built-in CRM]
```

<Warning>
  Do not expose customer order data to an unauthenticated endpoint. Your Custom HTTP Tool endpoint should require a secret, scope lookups to a single order, and never return more than the shopper asked for. Alex only sees what your endpoint chooses to return.
</Warning>

## Pricing

The widget itself is included with your plan. Order-lookup tooling needs the **Power Tools** add-on at \$29/mo, which also unlocks the Developer Portal and MCP API keys. The Professional plan is \$99/mo with 250 included minutes, then usage is roughly \$0.05/min blended. Add-ons are bundled on Enterprise. Full numbers are on [pricing](/pricing) and [add-ons](/essentials/add-ons).

## Verify it is working

1. Open your live store in an incognito window and confirm the widget appears on a product page and the home page.
2. Send one text message ("what are your shipping times") and confirm Alex replies.
3. If you chose a voice variant, tap to start a call and confirm audio connects.
4. Check the conversation shows up in your SmartAlex [analytics](/essentials/analytics).

## Related

<CardGroup cols={2}>
  <Card title="Widget install guide" icon="code" href="/essentials/widget-install">
    The full reference for the script tag, React usage, and every variant.
  </Card>

  <Card title="Retail use case" icon="cart-shopping" href="/use-cases/retail">
    How stores use Alex for order status, returns, and product questions.
  </Card>

  <Card title="Agent tools" icon="wrench" href="/essentials/agent-tools">
    Set up the Custom HTTP Tool that looks up live order data mid-call.
  </Card>

  <Card title="All build-with guides" icon="grid" href="/build-with/overview">
    Embed the widget in Webflow, Framer, WordPress, Wix, and more.
  </Card>
</CardGroup>