> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Shopify Integration
> Connect your Shopify store to enable AI-powered order tracking and product browsing.
## Introduction
Connect your Shopify store to Convocore so your customers can check their order status and browse your products through your AI agent.
## Overview
The Shopify integration allows your customers to:
* **Check their order status** by providing their order number
* **View order details** (items, shipping, total)
* **Browse your store products** and get product information
* **See product availability** and pricing
* **Look up a customer** by the data Shopify returns (name, email, order count)
This integration is **read-only** for security. Your agent can help customers
view information but cannot modify orders or products in your store.
## Prerequisites
Before connecting your Shopify store, you'll need:
* Admin access to the Shopify store
* Access to the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard) (same organization as the store)
* The store's admin domain (`your-store.myshopify.com`, not a custom brand URL)
**You must Install the app on the store.** Creating an app and pasting scopes
is not enough. Convocore exchanges Client ID + Client Secret for a short-lived
token. Shopify returns **HTTP 400** until the app is installed on that exact
store.
## Step-by-Step Setup Guide
Use the **Dev Dashboard** flow (Client ID + Client Secret). Do not use an old
Admin API `shpat_` token from Settings → Apps → Develop apps unless you already
have a legacy connection saved in Convocore.
### Step 1: Create an app in the Dev Dashboard
1. Go to [dev.shopify.com/dashboard](https://dev.shopify.com/dashboard)
2. Click **Create app**
3. Name it something like `Convocore AI Assistant`
4. Open the **Configuration** tab
### Step 2: Paste the required scopes
Do **not** hunt through checkboxes. Under **Access → Scopes** (or **Use legacy scopes**), paste this exact list and save:
```text theme={null}
read_orders,read_all_orders,read_products,read_product_listings,read_customers
```
| Scope | Why Convocore needs it |
| ----------------------- | ------------------------------------------ |
| `read_orders` | Order status, totals, fulfillments |
| `read_all_orders` | Orders older than 60 days |
| `read_products` | Products, variants, collections |
| `read_product_listings` | Published catalog |
| `read_customers` | Customer lookup (name, email, order count) |
Set an **App URL** so Shopify lets you save (use `https://example.com` if you do not have one). Click **Save**.
After any scope change you must **Save**, then **Install again**. A saved but
uninstalled app cannot issue tokens.
### Step 3: Install the app on the store (required)
This is the step that makes credentials work.
1. In the same Dev Dashboard app, click **Install**
2. Choose the store that matches `your-store.myshopify.com`
3. Confirm the install
The store must belong to the **same Shopify organization** as the app. If you
install on a different shop, Shopify returns `shop_not_permitted` or HTTP 400.
Client ID and Client Secret exist before install, but token exchange fails
until the app is installed on that store.
### Step 4: Copy Client ID and Client Secret
1. In the Dev Dashboard app, open **Settings**
2. Copy **Client ID**
3. Copy **Client Secret**
You do **not** copy an Admin API access token. Convocore requests a short-lived
token from Shopify on each API call using these two values.
### Step 5: Connect in Convocore
1. Open **Integrations** in your Convocore dashboard
2. Find **Shopify** and click **Connect**
3. Fill in:
* **Store Domain**: `your-store.myshopify.com`
* **Client ID**: from Dev Dashboard → Settings
* **Client Secret**: from Dev Dashboard → Settings
4. Click **Connect Store**
Convocore tests the credentials before saving. If you see HTTP 400, go back to
Step 3 and install the app on that store, then retry.
A successful test returns your shop name, currency, and timezone. Then assign
the connection to an agent.
## Assigning to Agents
After connecting your Shopify store, you need to assign it to the agents that should have access.
### Method 1: Through Integrations Page
1. **Go to Integrations** in your Convocore dashboard
2. **Find your connected Shopify store** and click **"Manage"**
3. **Switch to the "Agent Assignment" tab**
4. **Select the Shopify store** you want to assign (if you have multiple)
5. **Choose one or more agents** from the dropdown
6. **Click "Assign Shopify"**
You can assign the same Shopify store to multiple agents, and each agent will
have read-only access to your store data.
### Method 2: Through Agent Settings
1. **Go to the Agents tab** and select your agent
2. **Navigate to the Canvas** (or Nodes view)
3. **Edit a node** (typically the Start Node)
4. **In the Tools section**, find and enable the **"Shopify"** tool
5. **Save the node configuration**
### Agent Instructions
To help your agent understand when to use Shopify, add instructions like this to your agent's prompt:
```markdown theme={null}
You can help customers with their orders and questions about products:
- Check order status and delivery information
- Browse product catalog and pricing
- Check product availability and details
When customers ask about their orders or products, use the Shopify tool to get
real-time information from the store.
```
## What Your Customers Can Do
Once connected, your customers can interact with your agent to:
### Order Inquiries
* **"What's the status of my order #12345?"**
* **"When will my order arrive?"**
* **"What items are in my order?"**
* **"How much did I pay for my order?"**
* **"Has my order been shipped yet?"**
### Product Browsing
* **"What products do you have?"**
* **"Tell me about \[product name]"**
* **"How much does \[product] cost?"**
* **"Do you have \[product] in stock?"**
* **"Show me products in \[category]"**
## Usage Examples
### Customer Checking Order Status
```text Customer theme={null}
Hi, I want to check my order status. My order number is 677561797429.
```
```text Agent Response theme={null}
I found your order! Here are the details:
📦 **Order #677561797429**
💰 **Total**: $125.99
📅 **Ordered**: January 28, 2024
🔄 **Status**: Fulfilled
🚚 **Shipping**: Delivered via UPS
Your order contains 3 items and has been successfully delivered. Is there
anything else you'd like to know about your order?
```
### Customer Asking About Products
```text Customer theme={null}
Do you have any cotton t-shirts available?
```
```text Agent Response theme={null}
Yes! Here are our cotton t-shirts currently available:
🏷️ **Premium Cotton T-Shirt**
💰 **Price**: $29.99
📏 **Sizes**: Small, Medium, Large, XL
🎨 **Colors**: Black, White, Navy, Gray
✅ **In Stock**: Yes
🏷️ **Organic Cotton Tee**
💰 **Price**: $34.99
📏 **Sizes**: Small, Medium, Large
🎨 **Colors**: Natural, Charcoal
✅ **In Stock**: Yes
Would you like more details about any of these shirts or help with placing an
order?
```
## Managing Your Integration
### Viewing Connected Stores
1. **Go to Integrations** in your dashboard
2. **Find the Shopify card** - it will show "X Connections" if connected
3. **Click "Manage"** to see all connected stores
### Managing Agent Assignments
In the Manage modal, you'll see two tabs:
**Store Connections Tab:**
* View all connected Shopify stores
* See store details (domain, currency, timezone)
* Disconnect stores when needed
**Agent Assignment Tab:**
* See which agents are using Shopify
* Assign Shopify to new agents
* Remove Shopify from agents
### Disconnecting a Store
If you need to disconnect a Shopify store:
1. **Go to Integrations** → **Shopify** → **"Manage"**
2. **Go to "Store Connections" tab**
3. **Find the store** you want to disconnect
4. **Click the store** to expand details
5. **Click "Disconnect"** and confirm
Disconnecting a store will prevent any agents using it from accessing order
and product data. Make sure to remove agent assignments first if needed.
## Tips for Better Customer Experience
### Helpful Agent Prompts
To make your agent more effective with Shopify integration, consider adding these suggestions to your agent's system prompt:
```text System Prompt Addition theme={null}
When customers ask about orders:
- Always ask for their order number if not provided
- Provide clear status updates and tracking information
- Offer to help with any concerns about their order
When customers ask about products:
- Show relevant products with prices and availability
- Highlight key features and benefits
- Ask if they need help with sizing or have questions
- Offer to help them find similar products if something is out of stock
```
### Common Customer Questions
Your agent will be able to handle questions like:
* "What's the status of order #12345?"
* "When will my order arrive?"
* "Do you have \[product] in stock?"
* "How much does \[product] cost?"
* "What products do you have in \[category]?"
* "Can you help me find \[type of product]?"
## Troubleshooting
### Connection Issues
**Problem**: HTTP 400 / "token exchange failed" / "app is probably not installed"
**Solutions**:
* Install the app on this exact store from the Dev Dashboard (required)
* Confirm the domain is `something.myshopify.com`, not the brand URL
* Paste all 5 scopes, Save, then Install again
* The store and the app must be in the same Shopify organization
**Problem**: `shop_not_permitted`
**Solutions**:
* Install the app on the store you typed in Convocore
* Do not use a Client ID from an app in a different Shopify org
**Problem**: `invalid_client`
**Solutions**:
* Re-copy Client ID and Client Secret from Dev Dashboard → Settings
* Remove extra spaces
**Problem**: "Store not found"
**Solutions**:
* Use the admin `.myshopify.com` domain
* Check for typos
* Confirm the store is active
**Problem**: "Access forbidden" / missing scope
**Solutions**:
* Paste `read_orders,read_all_orders,read_products,read_product_listings,read_customers`
* Save, then reinstall the app so the new grant is applied
### Agent Can't Find Orders
**Problem**: Customer provides order number but agent says "order not found"
**Solutions**:
* Ask customer to double-check their order number
* Verify you're connected to the correct Shopify store
* Check that `read_orders` and `read_all_orders` are granted (reinstall after adding them)
* Confirm you are connected to the correct store
### Agent Not Responding to Shopify Questions
**Problem**: Agent doesn't use Shopify when customers ask about orders/products
**Solutions**:
* Make sure Shopify is assigned to the agent (check in Integrations → Manage → Agent Assignment)
* Verify the Shopify tool is enabled in your agent's node settings
* Check that your store connection shows as "Connected" in Integrations
* Add clearer instructions in your agent's prompt about using Shopify
* Try reconnecting your store if issues persist
### Error Messages
If you see error messages when connecting:
| Error Message | What It Means | Solution |
| ----------------------- | ------------------------------------- | ---------------------------------------------- |
| HTTP 400 token exchange | App not installed, or wrong store/org | Install the app on that `.myshopify.com` store |
| `shop_not_permitted` | Store is not allowed for this app | Install from the same Shopify org |
| `invalid_client` | Bad Client ID or Secret | Re-copy from Dev Dashboard → Settings |
| "Store not found" | Domain is wrong | Use `store.myshopify.com` |
| "Access forbidden" | Missing scopes | Paste all 5 scopes, Save, reinstall |
## Security & Privacy
Your data security is our top priority:
* ✅ **Read-only access** - Cannot modify your store data or process orders
* ✅ **Secure storage** - API credentials are encrypted at rest
* ✅ **HTTPS only** - All API calls use secure SSL connections
* ✅ **No data retention** - Order and customer data is not stored by Convocore
* ✅ **Disconnect anytime** - Remove access instantly from Integrations page
* ✅ **Scoped permissions** - Only requests the minimum required access
Your Shopify credentials are never exposed to end users or stored in logs.
They are only used server-side to make authenticated API requests to your
store.
## Advanced Configuration
### Multiple Store Support
You can connect multiple Shopify stores to your workspace:
1. **Each store** gets its own connection in Integrations
2. **Each agent** can be assigned to one or more stores
3. **Agents will search** across all assigned stores when helping customers
### Custom Agent Behaviors
You can customize how your agent uses Shopify by:
**In Agent Prompt:**
```markdown theme={null}
When using Shopify:
- Always format order information in a clear, easy-to-read format
- Include emojis to make responses more engaging
- If an order hasn't shipped yet, let customers know the expected timeline
- If a product is out of stock, offer to check similar items
```
## Support
Need help? Here's what to check:
1. **Connection Status** - Verify your store shows as "Connected" (green indicator) in Integrations
2. **Agent Assignment** - Make sure Shopify is assigned to your agent via Integrations → Manage
3. **Test Connection** - The system tests your credentials automatically when connecting
4. **Install + scopes** - App must be installed; all 5 scopes pasted, saved, and reinstalled
For additional support, contact our team through the dashboard or check our help center.
***
## Quick Start Checklist
* [ ] Create the app in the Shopify Dev Dashboard
* [ ] Paste all 5 scopes and Save
* [ ] **Install the app on the store** (required — credentials fail until this)
* [ ] Copy Client ID and Client Secret from Settings
* [ ] Connect store in Convocore Integrations (`store.myshopify.com` + Client ID + Secret)
* [ ] Assign Shopify to your agent(s)
* [ ] Add helpful instructions to agent prompt
* [ ] Test with sample customer questions
Your Shopify integration is now ready! Your customers can check their order status and browse your products through natural conversation with your AI agent. 🎉