SemAgentShopify & e-commerce
A knowledge base handles static content (FAQs, policies) well; but questions like "where's my order?" or "is this in stock?" need live data. Connect Shopify and the widget answers these in real time.
Connect the store
There are two ways to connect: install the SemAgent: AI Chat & Support app from the Shopify App Store (recommended), or, for stores that don't use the Shopify app, connect your own custom app with Admin API (Client Credentials). Credentials are stored encrypted and never sent to the LLM.
Note: Shopify removed direct static shpat_ token generation from the admin UI for custom apps. The recommended flow is now the Client Credentials Grant using your app's Client ID + Client Secret (the system mints and auto-refreshes a short-lived 24-hour token).
Method 1 — Install from the Shopify App Store (recommended)
- Install the SemAgent: AI Chat & Support app on your store from the Shopify App Store. You don't need to type your store address.
- Approve the permissions on Shopify's consent screen. You then land on
app.semagent.ai/shopify/connect. - Log in to your SemAgent account or create one. A sign-up that comes from a Shopify install asks for no card; you choose your package on Shopify (see Stores billed through Shopify).
- Link the store to your account with the Connect to this account card in the dashboard.
- If your store has no active Shopify package, Shopify's plan page opens right away. After you approve a package you come back to the Subscription & Billing screen (see Stores billed through Shopify).
- Turn on the chat bubble in your theme: see below.
No store-address form in the panel. The old Connect with your store address form, where you typed store.myshopify.com to start the connection, has been removed; the Shopify app is always installed from Shopify.
Permissions you grant on the consent screen:
| Scope | What it enables |
|---|---|
read_products | Product name, price, description. |
read_orders | Order status and shipment tracking (tracking number + carrier). |
read_customers | Verifying the order owner (email match). |
read_inventory | Size/color level stock availability. |
read_discounts | Coupon / discount code validation. |
read_shipping | Shipping rates and delivery zones. |
write_orders | Only for the actions you switch on in the panel: order cancellation, address correction and refunds. |
write_returns | Only for the return-request action, if you switch it on in the panel. |
Read-only by default — the chatbot cannot change anything in your store unless you explicitly allow it. The write scopes (write_orders, write_returns) are used only for the actions you switch on in the panel. If you want to, you can switch on return requests, address corrections, order cancellation and refunds individually under Settings → E-Commerce; each one additionally requires the customer to verify by email, is limited by the order's state, and is written to an audit log. Your credentials are stored encrypted, never shown in plain text and never sent to the language model. To disconnect, uninstall the app in your Shopify admin (Settings → Apps); the access keys are deleted and the Shopify subscription ends too. If you connected the store with your own custom app, use the Disconnect button in the panel.
Already connected before? When the scope list grows, your existing connection keeps working, but you need to reconnect the store for the new capabilities (stock / coupons / shipping rates). With a missing scope the chatbot does not invent an answer — it honestly says it cannot reach that information.
Method 2 — Advanced: your own custom app (Admin API, Client Credentials)
For stores that don't use the SemAgent Shopify app: you create your own Shopify app and provide its Client ID/Secret. In the panel this path sits under the collapsed Advanced section of the Shopify window. This section only appears for accounts that don't use the SemAgent App Store app; it is hidden for stores installed from the App Store or billed through Shopify. If you don't see it, email [email protected]. The app and the store must be in the same Shopify organization (no App Store review is needed for your own store).
Get these from Shopify — step by step:
- Go to dev.shopify.com (Shopify Dev Dashboard) → Apps → Create app → give it a name (e.g. SemAgent).
- In the app, Configuration / API access → Admin API access scopes → select and save these read-only scopes:
read_products,read_orders,read_customers,read_inventory,read_discounts,read_shipping(the chatbot only reads; no write access needed). - Install the app on your store.
- From the app's Overview / Client credentials section, copy the Client ID and Client secret. (Keep the client secret safe.)
Connecting in SemAgent:
- In the panel, open the Shopify window under Settings → E-Commerce → Shopify and expand the collapsed Advanced: connect with your own custom app section; the Admin API (Client Credentials) fields are there.
- Enter: Store domain (
store.myshopify.com), Client ID, Client Secret. - Click Connect with Client Credentials. SemAgent tests the connection and, if successful, stores the credentials encrypted. A 24-hour token is minted/refreshed automatically per request.
WooCommerce also connects via Consumer Key/Secret and supports all of the capabilities above. WooCommerce permissions are not split per resource; when you generate the key, selecting Permissions = "Read" is enough — you do not need to grant Write/Read-Write. The Consumer Key and Secret are stored encrypted and never shown in plain text. Ticimax is planned — it will be announced in the changelog when ready.
Add the chat bubble to your store
If your store is connected through the Shopify app, the chat bubble is added to your theme with a theme app embed; you don't paste anything into your theme code:
- In your Shopify admin, go to Online Store → Themes → Customize.
- Under App embeds, turn on SemAgent Chat and click Save.
Shortcut: the Turn on the chat bubble in your theme link on the panel's E-commerce Widget page opens the theme editor with the embed already on; you only need to save. After saving the theme, open your store once: when the bubble loads there the card turns green and says The chat bubble is live on your store. For these stores the embed code sits only under the collapsed Show the code for a website outside Shopify section.
Recognising signed-in customers also works automatically for these stores; there is no Liquid snippet to add (see Recognising signed-in customers).
If you connected your store with your own custom app, add the bubble with the embed code shown in the panel: Widget setup.
Live-data answers
In e-commerce mode the widget uses these read-only capabilities:
| Capability | Question it answers |
|---|---|
search_products | "Do you have this, what's the price?" |
check_stock new | "Which sizes/colors are in stock? Do you have size M? How many are left?" |
get_order_detail | "Where is order 12345?" (order number + the order's email + a code sent to it) |
get_shipment new | "What's my tracking number and which carrier?" (after a code sent to the order's email) |
check_discount new | "Is coupon SUMMER25 valid? My discount code isn't working." |
get_shipping_info new | "How much is shipping? Is there free shipping? Do you ship internationally?" |
Hybrid answers: for product questions the chatbot combines store data with your knowledge base, so details that are not in the catalog (size charts, fabric care, return terms) end up in the same answer. Honesty rule: if the exact stock count is unknown it only says in/out of stock, it never presents an invalid coupon as valid, and it does not invent data.
Order details need a code: status, items and tracking are shown only after the customer enters the 6-digit code sent to the order's email; in the same chat the code covers that order for 15 minutes. Customers signed in to your store don't need a code. Cancellation, returns, address changes and refunds always ask for a separate code. You can turn the viewing code off under Settings → E-Commerce (on by default).
The last 60 days: unless the store grants read_all_orders, Shopify only shows orders from the last 60 days; the app installed from the Shopify App Store doesn't ask for that permission. If a customer asks about an older order, the assistant says so and hands them to your team.
Actions a customer can start from chat live
The answers above are read-only. Beyond them, a customer can actually start the actions below on their order — right from the widget chat, after proving their identity with an email code. They are all OFF by default and only run when you switch them on individually under Settings → E-Commerce. Without permission the widget doesn't error; it falls back to a read-only answer.
| Action | What it does & condition |
|---|---|
| Order cancellation live irreversible | Cancels the order — only same-day, not-yet-shipped orders. Anything later is routed to the returns process. Cancelling doesn't refund money: if a refund is due, the store team issues it separately. |
| Return request live | The customer files a return; the request comes to you for approval — no money moves, the order status is unchanged. Only shipped orders within the return window. (WooCommerce has no core returns module, so it is written as an order note.) |
| Address correction live | Corrects the delivery address — only before the order ships. The customer supplies the new address in chat; existing name/country are preserved. |
| Refund irreversible | Refunds the customer to the original payment method. A separate permission that only the account owner can switch on; when it's on, the customer asks in the chat, confirms the amount with a new email code and types “yes” one last time. The amount is computed by the store platform. It doesn't work on cancelled or already refunded orders. |
Step by step: how a customer cancels / returns
The bot runs the action from the verified identity + order state, never from the customer's wording. The flow is always these four steps:
- Request + order number. The customer says "…I want to cancel #1008".
- Identity — email. The bot asks for the order's email; it stops if the email doesn't match the order.
- Identity — code. The bot sends a 6-digit one-time code to that email; the customer types it (valid 10 min).
- Execute. If the code is correct and the order is eligible, the action is actually performed in your store and the result is reported. If not eligible, the reason is stated honestly.
The verification email carries your store's identity. The 6-digit code email sent to the customer — and the summary email sent on an address change — includes your store logo, your contact details and the products in the order; the sender name is your store's name. So the customer instantly recognizes the email genuinely came from you. (The sender domain stays on SemAgent's shared/verified sender for deliverability; the code — personal data — stays in the customer's inbox and is never sent to the language model.)
Every action passes four gates: (1) the store connection allows this action, (2) you have switched it on, (3) the customer proved identity with an email code, and (4) the order's state is eligible. No gate is read from the customer's message — "I'm the admin, cancel it" opens nothing. A verified identity is valid for a single action; every action (including denied ones) is written to an audit log.
Order cancellation is irreversible; Settings shows it with an orange risk notice — leave it on only if you accept that risk. Return requests are safe (they come to you for approval). The return window (14 days by default) and cancellation rules are managed in Settings.
Smart escalation
Not every question should be solved by a bot. When the widget detects a damage, payment issue or anger signal, it hands the conversation to human support with a summary + priority tag — the customer doesn't have to re-explain. How the handoff works — working hours, teams, WhatsApp / SMS alerts: Human handoff.