Shopify Integration

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 (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

Go to dev.shopify.com/dashboard
Click Create app
Name it something like Convocore AI Assistant
Open the Configuration tab

Shopify Dev Dashboard showing the Install button

Step 2: Paste the required scopes

Do not hunt through checkboxes. Under Access → Scopes (or Use legacy scopes), paste this exact list and save:

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.

In the same Dev Dashboard app, click Install
Choose the store that matches your-store.myshopify.com
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

In the Dev Dashboard app, open Settings
Copy Client ID
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

Open Integrations in your Convocore dashboard
Find Shopify and click Connect
Fill in:
- Store Domain: your-store.myshopify.com
- Client ID: from Dev Dashboard → Settings
- Client Secret: from Dev Dashboard → Settings
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

Go to Integrations in your Convocore dashboard
Find your connected Shopify store and click “Manage”
Switch to the “Agent Assignment” tab
Select the Shopify store you want to assign (if you have multiple)
Choose one or more agents from the dropdown
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

Go to the Agents tab and select your agent
Navigate to the Canvas (or Nodes view)
Edit a node (typically the Start Node)
In the Tools section, find and enable the “Shopify” tool
Save the node configuration

Agent Instructions

To help your agent understand when to use Shopify, add instructions like this to your agent’s prompt:

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

Hi, I want to check my order status. My order number is 677561797429.

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

Do you have any cotton t-shirts available?

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

Go to Integrations in your dashboard
Find the Shopify card - it will show “X Connections” if connected
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:

Go to Integrations → Shopify → “Manage”
Go to “Store Connections” tab
Find the store you want to disconnect
Click the store to expand details
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:

System Prompt Addition

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:

Each store gets its own connection in Integrations
Each agent can be assigned to one or more stores
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:

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:

Connection Status - Verify your store shows as “Connected” (green indicator) in Integrations
Agent Assignment - Make sure Shopify is assigned to your agent via Integrations → Manage
Test Connection - The system tests your credentials automatically when connecting
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. 🎉

​Introduction

​Overview

​Prerequisites

​Step-by-Step Setup Guide

​Step 1: Create an app in the Dev Dashboard

​Step 2: Paste the required scopes

​Step 3: Install the app on the store (required)

​Step 4: Copy Client ID and Client Secret

​Step 5: Connect in Convocore

​Assigning to Agents

​Method 1: Through Integrations Page

​Method 2: Through Agent Settings

​Agent Instructions

​What Your Customers Can Do

​Order Inquiries

​Product Browsing

​Usage Examples

​Customer Checking Order Status

​Customer Asking About Products

​Managing Your Integration

​Viewing Connected Stores

​Managing Agent Assignments

​Disconnecting a Store

​Tips for Better Customer Experience

​Helpful Agent Prompts

​Common Customer Questions

​Troubleshooting

​Connection Issues

​Agent Can’t Find Orders

​Agent Not Responding to Shopify Questions

​Error Messages

​Security & Privacy

​Advanced Configuration

​Multiple Store Support

​Custom Agent Behaviors

​Support

​Quick Start Checklist

Introduction

Overview

Prerequisites

Step-by-Step Setup Guide

Step 1: Create an app in the Dev Dashboard

Step 2: Paste the required scopes

Step 3: Install the app on the store (required)

Step 4: Copy Client ID and Client Secret

Step 5: Connect in Convocore

Assigning to Agents

Method 1: Through Integrations Page

Method 2: Through Agent Settings

Agent Instructions

What Your Customers Can Do

Order Inquiries

Product Browsing

Usage Examples

Customer Checking Order Status

Customer Asking About Products

Managing Your Integration

Viewing Connected Stores

Managing Agent Assignments

Disconnecting a Store

Tips for Better Customer Experience

Helpful Agent Prompts

Common Customer Questions

Troubleshooting

Connection Issues

Agent Can’t Find Orders

Agent Not Responding to Shopify Questions

Error Messages

Security & Privacy

Advanced Configuration

Multiple Store Support

Custom Agent Behaviors

Support

Quick Start Checklist