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

# Shopify

> Integrate your AI Employee with Shopify to provide automated customer support, answer product questions, and assist with orders directly in your online store.

> **Important:**
> The Shopify integration allows you to embed an AI Employee on your Shopify store to handle customer inquiries, provide product recommendations, assist with orders, and improve the shopping experience.

***

## 🔢 Table of Contents

1. [Overview](#1-overview)
2. [Prerequisites](#2-prerequisites)
3. [Installation Steps](#3-installation-steps)
4. [Configuring Your AI Employee](#4-configuring-your-ai-employee)
5. [Customization Options](#5-customization-options)
6. [Common Use Cases](#6-common-use-cases)
7. [Troubleshooting](#7-troubleshooting)
8. [Best Practices](#8-best-practices)

***

## 1. Overview

### What This Integration Does

The Shopify integration embeds a chat widget on your store, powered by your AI Employee. Customers can:

* Ask questions about products
* Get sizing and specification information
* Track order status
* Request returns or exchanges
* Get shopping recommendations
* Receive instant support 24/7

### Key Features

* **Easy Installation**: Add with a simple script tag
* **Customizable Widget**: Match your store's branding
* **Mobile Responsive**: Works on all devices
* **Product Knowledge**: Connect datastores with product info
* **Order Integration**: Can integrate with Shopify APIs (via HTTP Tool)
* **Lead Capture**: Collect customer information
* **Multi-language**: Support multiple languages

### Technical Requirements

* Active Shopify store (any plan)
* Access to theme code editor
* ZappWay AI Employee created and configured
* Basic familiarity with HTML (helpful but not required)

***

## 2. Prerequisites

### Before You Begin

**1. Create an AI Employee:**

If you haven't already:

1. Go to [AI Employees](https://app.zappway.ai/agents)
2. Click **"Create AI Employee"**
3. Configure settings and instructions
4. See [AI Employee Guide](/agent/get-started) for details

**2. Add Product Knowledge:**

Create a datastore with your product information:

* Product descriptions
* Sizing guides
* Shipping policies
* Return policies
* FAQs

See [Datastore Guide](/datastore/get-started) for setup.

**3. Connect Datastore to AI Employee:**

1. Open AI Employee settings
2. Go to **Tools** tab
3. Add **Datastore Tool**
4. Select your product datastore
5. Save configuration

**4. Obtain Your Agent ID:**

1. Open your AI Employee in the dashboard
2. Copy the **Agent ID** from the URL or settings
3. Keep this handy for installation

**Example Agent ID:** `clf1a2b3c4d5e6f7g8h9`

***

## 3. Installation Steps

### Step 1: Access Theme Code Editor

1. Log in to your **Shopify Admin** dashboard
2. Navigate to **Online Store → Themes**
3. Find your current active theme
4. Click **Actions → Edit code**

<img src="https://mintlify.s3.us-west-1.amazonaws.com/zappway/shopify/theme.png" alt="Shopify Theme Editor" />

### Step 2: Copy Integration Script

Copy the following script, replacing `YOUR_AGENT_ID` with your actual Agent ID:

```html theme={null}

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'YOUR_AGENT_ID',
  })

```

**Example with real Agent ID:**

```html theme={null}

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'clf1a2b3c4d5e6f7g8h9',
  })

```

### Step 3: Insert Script in Theme

1. In the theme code editor, locate the **`theme.liquid`** file in the **Layout** folder
2. Find the closing **`</head>`** tag (usually near the top of the file)
3. **Paste the script above the `</head>` tag**
4. Click **Save** in the top-right corner

<img src="https://mintlify.s3.us-west-1.amazonaws.com/zappway/shopify/code.png" alt="Code Insertion" />

**Important:** The script must be placed **before** the `</head>` tag, not after.

### Step 4: Verify Installation

1. Visit your Shopify store in a new browser tab
2. Look for the chat bubble in the bottom-right corner
3. Click the bubble to open the chat widget
4. Send a test message to your AI Employee
5. Verify responses are working correctly

**If the bubble doesn't appear, see [Troubleshooting](#7-troubleshooting).**

***

## 4. Configuring Your AI Employee

### Recommended Instructions for Shopify

Configure your AI Employee with instructions specific to e-commerce:

```
You are a helpful customer service assistant for [Your Store Name].
Your goal is to help customers find products, answer questions, and provide excellent shopping support.

PERSONALITY:
- Friendly, enthusiastic, and helpful
- Product-focused and solution-oriented
- Patient with customer questions

CAPABILITIES:
- Answer product questions (features, sizing, materials)
- Provide shopping recommendations
- Help with order tracking
- Explain shipping and return policies
- Assist with account issues
- Offer promotions and discounts when available

PROCESS:
1. Greet customers warmly
2. Understand what they're looking for
3. Search product knowledge base
4. Provide helpful, accurate information
5. Suggest related products when appropriate
6. Ask if they need anything else

PRODUCT RECOMMENDATIONS:
When recommending products:
- Ask about customer preferences and needs
- Suggest 2-3 specific products with details
- Mention key features and benefits
- Include pricing information
- Provide direct product links when possible

WHEN TO ESCALATE:
- Order cancellations or modifications
- Payment issues
- Damaged or defective products
- Complex technical problems
- Custom or bulk orders

Always be enthusiastic about our products and help customers have a great shopping experience!
```

### Connecting Product Data

**Create Product Datastore:**

1. Go to [Datastores](https://app.zappway.ai/datastores)
2. Click **"Create Datastore"**
3. Name it "Product Catalog" or similar
4. Add datasources:
   * **Product descriptions** (copy from Shopify product pages)
   * **Sizing guides** (PDF or text)
   * **Shipping policy**
   * **Return policy**
   * **FAQs**

**Connect to AI Employee:**

1. Open AI Employee → **Tools** tab
2. Add **Datastore Tool**
3. Select "Product Catalog" datastore
4. Save

### Optional: Order Tracking Integration

To enable order tracking, set up the HTTP Tool to query Shopify's API:

**See:** [HTTP Tool Guide](/agent/tools/http-tool)

**Basic Setup:**

1. Add **HTTP Tool** to AI Employee
2. Configure endpoint: `https://your-store.myshopify.com/admin/api/2024-01/orders.json`
3. Add authentication (Shopify API key)
4. Update instructions to mention order tracking capability

***

## 5. Customization Options

### Widget Appearance

Customize the chat bubble and widget to match your store's branding:

```html theme={null}

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'YOUR_AGENT_ID',
    
    // Bubble customization
    theme: {
      primaryColor: '#4F46E5',      // Your brand color
      position: 'right',             // 'right' or 'left'
      bottom: 20,                    // Distance from bottom (px)
      right: 20,                     // Distance from side (px)
    },
    
    // Widget customization
    window: {
      title: 'Shopping Assistant',  // Chat window title
      welcomeMessage: 'Hi! How can I help you find the perfect product today?',
    },
  })

```

**Available Options:**

| Option                  | Type   | Default   | Description                  |
| ----------------------- | ------ | --------- | ---------------------------- |
| `theme.primaryColor`    | string | `#3B82F6` | Main brand color             |
| `theme.position`        | string | `right`   | Bubble position (left/right) |
| `theme.bottom`          | number | `20`      | Distance from bottom (px)    |
| `theme.right`           | number | `20`      | Distance from right (px)     |
| `theme.left`            | number | `20`      | Distance from left (px)      |
| `window.title`          | string | `Chat`    | Widget header title          |
| `window.welcomeMessage` | string | -         | Initial greeting message     |
| `window.height`         | number | `600`     | Widget height (px)           |
| `window.width`          | number | `400`     | Widget width (px)            |

### Show on Specific Pages

To show the widget only on certain pages:

```html theme={null}

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  // Only show on product pages
  if (window.location.pathname.includes('/products/')) {
    Chatbox.initBubble({
      agentId: 'YOUR_AGENT_ID',
    });
  }

```

**Common Shopify Page Paths:**

* Product pages: `/products/`
* Collection pages: `/collections/`
* Cart page: `/cart`
* Checkout: `/checkout`
* All pages: (no condition)

### Hide on Mobile

If you want to hide the widget on mobile devices:

```html theme={null}

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  // Only show on desktop
  if (window.innerWidth > 768) {
    Chatbox.initBubble({
      agentId: 'YOUR_AGENT_ID',
    });
  }

```

***

## 6. Common Use Cases

### Product Recommendations

**Customer:** "I'm looking for a gift for my wife"

**AI Employee:**

```
I'd love to help you find the perfect gift! 
To give you the best recommendations, could you tell me:

1. What are her interests or hobbies?
2. What's your budget range?
3. Are you looking for something specific (jewelry, clothing, accessories)?
```

**Setup Required:**

* Product datastore with detailed descriptions
* Instructions to ask qualifying questions
* Knowledge of product categories

### Order Tracking

**Customer:** "Where is my order #12345?"

**AI Employee:**

```
I'll look up your order for you!
[Uses HTTP Tool to query Shopify API]

Your order #12345 was shipped on January 10th via USPS.
Tracking number: 9400111899223344556677
Expected delivery: January 15th

You can track it here: [tracking link]
```

**Setup Required:**

* HTTP Tool configured with Shopify API
* API credentials with order read permission
* Instructions for handling order queries

### Sizing Assistance

**Customer:** "What size should I get for the Classic T-Shirt?"

**AI Employee:**

```
Great choice! To help you find the perfect fit, 
could you share your usual shirt size (S, M, L, XL)?

Our Classic T-Shirt runs true to size. Here's our sizing guide:
- Small: Chest 34-36", Length 28"
- Medium: Chest 38-40", Length 29"
- Large: Chest 42-44", Length 30"
- X-Large: Chest 46-48", Length 31"

Would you like me to recommend a size based on your measurements?
```

**Setup Required:**

* Sizing guide uploaded to datastore
* Instructions to ask clarifying questions
* Product-specific sizing information

### Returns and Exchanges

**Customer:** "I want to return my order"

**AI Employee:**

```
I'm sorry to hear that! I can help you with the return process.

Our return policy:
- 30-day return window from delivery date
- Items must be unworn and in original packaging
- Free return shipping

To start your return:
1. What's your order number?
2. Which item(s) would you like to return?
3. Reason for return? (helps us improve)

I'll generate a prepaid return label for you!
```

**Setup Required:**

* Return policy in datastore
* Form Tool for collecting return details
* Instructions for return process

### Abandoned Cart Recovery

**Trigger:** Customer has items in cart but hasn't checked out

**AI Employee:**

```
Hi! I noticed you have some items in your cart. 
Is there anything I can help you with to complete your purchase?

- Questions about the products?
- Need help with sizing?
- Looking for a promo code?
- Issues at checkout?

I'm here to help! 🛍️
```

**Setup Required:**

* Proactive message trigger (custom implementation)
* Instructions for cart recovery
* Knowledge of current promotions

***

## 7. Troubleshooting

### Chat Bubble Not Appearing

**Problem:** Widget doesn't show on your store

**Checks:**

1. **Verify Agent ID is correct:**
   * Check for typos in the script
   * Ensure Agent ID matches your dashboard

2. **Check script placement:**
   * Must be **before** `</head>` tag
   * Not inside any other script tags
   * Saved correctly in theme.liquid

3. **Clear browser cache:**
   * Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
   * Try incognito/private browsing mode

4. **Check browser console for errors:**
   * Open DevTools (F12)
   * Go to Console tab
   * Look for error messages
   * Common error: "Failed to load module"

5. **Verify theme file:**
   * Ensure you edited the **active theme**
   * Check that changes were saved
   * Preview theme before publishing

### AI Not Responding

**Problem:** Chat opens but AI doesn't reply

**Checks:**

1. **Test AI Employee directly:**
   * Go to AI Employee in ZappWay dashboard
   * Use test chat interface
   * If it works there, issue is with integration

2. **Check AI Employee status:**
   * Ensure AI Employee is not disabled
   * Verify instructions are configured
   * Check that datastores are connected

3. **Review rate limits:**
   * Check if rate limits are exceeded
   * See [Rate Limit Guide](/agent/rate-limit)

4. **Check datastore status:**
   * Ensure datastores are processed (not "Processing")
   * Verify content is indexed

### Widget Styling Issues

**Problem:** Widget doesn't match store design

**Solutions:**

1. **Customize colors:**

```html theme={null}
   theme: {
     primaryColor: '#YOUR_BRAND_COLOR',
   }
```

2. **Adjust position:**

```html theme={null}
   theme: {
     position: 'left',  // or 'right'
     bottom: 30,
     left: 30,
   }
```

3. **Change widget size:**

```html theme={null}
   window: {
     height: 700,
     width: 450,
   }
```

### Script Loading Slowly

**Problem:** Widget takes time to appear

**Causes:**

* CDN loading delay (rare)
* Slow network connection
* Other scripts blocking

**Solutions:**

1. **Use async loading:**

```html theme={null}
   
     import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';
     Chatbox.initBubble({ agentId: 'YOUR_AGENT_ID' });
   
```

2. **Self-host the script** (advanced):
   * Download library from CDN
   * Upload to Shopify theme assets
   * Update script src to point to local file

***

## 8. Best Practices

### Content Strategy

**Keep Product Info Updated:**

✅ **Do:**

* Update datastore when products change
* Include seasonal product info
* Add new products to datastore immediately
* Remove discontinued products

❌ **Avoid:**

* Outdated pricing information
* Products no longer in stock
* Inconsistent product descriptions

**Comprehensive Product Knowledge:**

Include in your datastore:

* Detailed product descriptions
* Materials and specifications
* Care instructions
* Sizing charts (with measurements)
* Color options and variations
* Product use cases and benefits
* Customer reviews and testimonials
* Comparison with similar products

### AI Employee Configuration

**Encourage Browsing:**

```
If customers seem unsure, offer to:
- Show bestsellers or new arrivals
- Suggest products based on season
- Offer category-specific recommendations
- Mention current sales or promotions
```

**Handle Price Questions:**

```
When discussing pricing:
- Mention current prices accurately
- Highlight any active discounts
- Compare value vs similar products
- Explain what's included (free shipping, warranty, etc.)
- Offer payment plan options if available
```

**Product Links:**

Train your AI to provide direct product links:

```
For each recommended product, provide:
- Product name
- Key features (2-3 bullet points)
- Price
- Direct link: [View Product](https://your-store.com/products/product-name)
```

### Customer Experience

**Response Time:**

* AI should respond within 2-3 seconds
* If processing longer (e.g., API calls), show typing indicator
* Provide status updates for complex queries

**Tone and Voice:**

Match your store's brand voice:

**Luxury Brand:**

```
Good afternoon. I'm delighted to assist you in finding 
the perfect piece from our collection. How may I be of service today?
```

**Casual/Fun Brand:**

```
Hey there! 👋 Ready to find something awesome? 
I'm here to help you discover your next favorite thing!
```

**Professional/Technical:**

```
Welcome! I can help you find the right product based on your 
specific requirements. What are you looking for today?
```

### Analytics and Improvement

**Track Key Metrics:**

* Most common customer questions
* Products frequently asked about
* Drop-off points in conversations
* Questions AI couldn't answer

**Regular Reviews:**

**Weekly:**

* Check conversation logs
* Identify knowledge gaps
* Update datastore with missing info

**Monthly:**

* Analyze top product inquiries
* Update AI instructions based on trends
* Add new FAQs to datastore

**Quarterly:**

* Major knowledge base overhaul
* Review and refine AI personality
* A/B test different approaches

### Security

**Protect Customer Data:**

* Don't store payment information in chat
* Don't ask for sensitive data (passwords, full card numbers)
* Comply with privacy regulations (GDPR, CCPA)
* Use secure connections (HTTPS) only

**What AI Should NOT Do:**

❌ Process payments directly\
❌ Access customer credit cards\
❌ Modify orders without confirmation\
❌ Share other customers' information\
❌ Make unauthorized discounts

***

## 📞 Support & Resources

### Getting Help

**In-App Support:**

* Help button in ZappWay dashboard
* Live chat (available on Pro+ plans)

**Shopify Resources:**

* [Shopify Theme Documentation](https://shopify.dev/docs/themes)
* [Liquid Template Language](https://shopify.dev/docs/api/liquid)

**Common Resources:**

* [AI Employee Guide](/agent/get-started)
* [Datastore Setup](/datastore/get-started)
* [Widget Customization](/widgets/chatbot/bubble)

### Feedback

**Report Issues:**

* Email: [support@zappway.ai](mailto:support@zappway.ai)
* Include:
  * Shopify store URL
  * Agent ID
  * Screenshots of issue
  * Browser console errors (if any)

***

## ✅ Quick Reference

### Installation Checklist

```
✓ AI Employee created and configured
✓ Product datastore created and populated
✓ Datastore connected to AI Employee
✓ Agent ID copied
✓ Script added to theme.liquid (before </head>)
✓ Theme saved
✓ Store tested in browser
✓ Chat bubble appears correctly
✓ Test conversation completed
✓ Responses are accurate
```

### Script Template

```html theme={null}

  import Chatbox from 'https://cdn.jsdelivr.net/npm/@zappway/embeds@latest/dist/chatbox/index.js';

  Chatbox.initBubble({
    agentId: 'YOUR_AGENT_ID',
    theme: {
      primaryColor: '#4F46E5',
      position: 'right',
    },
    window: {
      title: 'Shopping Assistant',
      welcomeMessage: 'Hi! How can I help you today?',
    },
  })

```

### Common Customizations

**Change bubble position to left:**

```javascript theme={null}
theme: { position: 'left', left: 20 }
```

**Show only on product pages:**

```javascript theme={null}
if (window.location.pathname.includes('/products/')) {
  Chatbox.initBubble({ agentId: 'YOUR_AGENT_ID' });
}
```

**Hide on mobile:**

```javascript theme={null}
if (window.innerWidth > 768) {
  Chatbox.initBubble({ agentId: 'YOUR_AGENT_ID' });
}
```

***

**Last Updated:** March 2026\
**Platform:** ZappWay × Shopify Integration