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
In the SemAgent panel go to Settings → E-Commerce → Shopify. There are two ways to connect: one-click OAuth (recommended) or Admin API (Client Credentials). Both run with read-only scopes; 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 — OAuth (recommended)
- In the panel go to E-Commerce → Shopify → Quick Connect and type your store address:
store.myshopify.com(your.myshopify.comaddress, not your custom domain). - Click Connect with OAuth → on Shopify's consent screen click Install / Approve.
- Done — permissions are granted in one click; no manual token needed. Back in SemAgent the connection shows "✓ Connected".
Permissions you grant on the consent screen (all read-only):
| 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 + read_price_rules | Coupon / discount code validation. |
read_shipping | Shipping rates and delivery zones. |
Read-only by default — the chatbot cannot change anything in your store unless you explicitly allow it. Every scope above is read-only. 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. You can remove them any time with Disconnect.
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 — Admin API (Client Credentials)
You create your own Shopify app and provide its Client ID/Secret. 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_price_rules,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 go to E-Commerce → Shopify → Admin API (Client Credentials).
- 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.
This connection lets the customer widget read live data (read-only). For the agent to write to Shopify (create products, etc.) there's a separate connection: the Shopify (Admin API) card in Agent Connectors — it also uses the Client Credentials Grant, but its credentials live separately in the Agent Vault.
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. The Ticimax adapter is in development — announced in the changelog when ready.
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?" |
search_orders | "Show my orders / what's the status of my last order?" |
get_order_detail | "Where is order 12345?" |
get_shipment new | "What's my tracking number and which carrier?" (after email verification) |
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?" |
search_customers | Recognize the customer / context from past orders. |
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.
For write operations on the agent side there are shopify_query / shopify_mutation tools (subject to approval) — see the tool reference.
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. |
| 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 | A customer cannot start this from chat — for safety, refunds are issued by you (by approving a return request, or from your admin). The amount is computed by the store platform. |
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.
Webhook event triggers
With Shopify connected, events trigger the agent instantly (no polling): e.g. new order → stock check → suggestion card if critical. This is the basis of proactive ops. More: event triggers.
All e-commerce actions pass through the same security architecture: read-only answers run freely, operations that change the store require approval.