How to connect Shopify
Goal: Link your Shopify store so support or commerce assistants can use order/catalog context and event-driven CRM automations.
Who does what
| Role | Tasks |
|---|---|
| You (admin) | Install the Shopify Marketplace app, enter your Shopify app client ID and secret, shop domain, then Connect Shopify |
| Engineering | Qefro Runtime HTTPS callback (PUBLIC_API_URL) — not Shopify app credentials |
What you need
- Owner or Admin on the Qefro organization
- Shopify store admin access
- A target AI Workspace (e.g. Support or Commerce)
- The Shopify Marketplace app installed on that workspace
- A Shopify Partner app (client ID and secret) for this workspace
Steps (operator)
- Open app.qefro.com → your organization.
- Open the AI Workspace that should own commerce answers and tools.
- Open Tools → Marketplace app and install Shopify if it is not already installed.
- Under Store connection, enter:
your-store.myshopify.com- Shopify app client ID and secret from Partners (this workspace only — Qefro does not use a shared app secret)
- Click Connect.
- Approve the requested scopes in Shopify (products, customers, orders — from the app metadata).
- After redirect, the card shows Connected. Tokens are never shown in the UI.
- Confirm knowledge is ready for policies (shipping, returns) — Knowledge Base.
- From Admin Console chat, try:
- “List all orders” (shop-wide, staff only)
- “Where is order 1001?”
- “What is your return window?” (should cite knowledge, not invent policy)
- Optional: enable website widget or WhatsApp on the same workspace — Channels. On WhatsApp, “show my recent orders” uses that customer’s Hub email (OTP-verified if missing), not the shop-wide staff list.
- Optional outcomes: Order tracking, Abandoned cart.
Reconnect runs OAuth again and replaces credentials. Disconnect revokes the token and deletes stored credentials; tools then fail safely until you connect again.
Workflow
Shopify connected
- Pick workspace — Support vs Commerce isolation.
- Install Shopify app — Marketplace metadata app on this workspace.
- Connect store — Tenant Shopify app credentials + OAuth; shop cannot be stolen by another workspace.
- Verify tools in chat — Real order IDs in a safe environment first.
- Turn on channel — Widget and/or WhatsApp.
Events (webhooks)
After Connect, Qefro registers webhooks for the topics declared in the app metadata. Inbound requests hit a generic Qefro webhook (/webhooks/http/shopify), not a Shopify server in the package.
HMAC is checked on the raw body first. The shop domain header selects the workspace — the payload cannot pick a workspace. Topics map to Business Events:
| Shopify topic | Business Event |
|---|---|
orders/create | order.created |
orders/updated | order.updated |
orders/cancelled | order.cancelled |
customers/create | customer.created |
customers/update | customer.updated |
Those events go onto orchestration_events and can start CRM Automation. People are matched through Customer Hub (email/phone/existing mapping). Shopify customer ids are never used as Person IDs.
Troubleshooting
| Symptom | What to check |
|---|---|
| Assistant cannot see orders | Connected? Correct workspace? Scope read_orders granted? Protected customer data approved in Partner? |
| WhatsApp shows no orders / asks for email | Person needs a verified Hub email matching the Shopify customer. Reply with the email, then the OTP. Shop-wide list_orders is staff-only. |
| Customer sees another person's order | Should not happen — ownership is checked after Shopify responds. File a bug if it does. |
| Wrong store data | Confirm which shop is bound to this workspace |
| “Already connected to another workspace” | Disconnect the other workspace first |
| Events not starting flows | Event names + CRM Automation trigger — Event-driven triggers |
| Connect button fails | Client ID/secret for this workspace? Shop domain *.myshopify.com? Partner redirect URL matches Qefro callback? |