Shopify Setup
Free to install. 2-minute setup. Catalog syncs automatically.
What you get
Clearly Agent installs as a standard Shopify app with a native embedded merchant admin inside Shopify Admin itself. You never leave Shopify to manage it.
- -Storefront chat widget (Theme App Extension, one-click toggle)
- -Live agent trained on your real catalog, policies, and inventory
- -Merchant inbox — every conversation, status tags, live chat takeover
- -Tickets & escalations — refunds, bulk orders, abandoned carts, size help
- -Knowledge base — brand voice, FAQs, size guides, policies
- -Analytics & revenue attribution — tied to actual orders via cart attributes
- -15+ languages — auto-detected from the visitor’s locale
Prerequisites
- -A Shopify store on any plan (Basic, Shopify, Advanced, Plus, or Starter)
- -Access to your Shopify Admin
- -That’s it — no Clearly.sh account needed; OAuth creates one for you.
1. Install from the Shopify App Store
Find Clearly Agent on the Shopify App Store and click Add app.
Shopify will show the permissions Clearly requests:
- read_products, write_products — catalog sync + AI-drafted descriptions
- read_inventory — real-time stock answers
- read_orders, read_checkouts — order tracking and conversion attribution
- read_customers — customer memory across visits
- read_shipping, read_price_rules, write_discounts — policy answers and agent-applied discounts
- write_themes — install the Theme App Extension
- unauthenticated_* — storefront visitor access (the chat widget)
Click Install app to authorize. Clearly never sees customer payment data.
2. Complete the onboarding wizard
After install, Shopify Admin opens the embedded Clearly app with a short wizard:
- -Name your agent — e.g. *Luna*, *Kai*, *Aria* (20 chars max). Customers never see the word “chatbot.”
- -Tone — Friendly, Professional, Casual, or Witty
- -Greeting — the first message a visitor sees when the widget opens
- -Brand accent — pick a color or paste your brand hex
Your catalog begins syncing in the background. Most stores finish in under 30 seconds; stores with 100K+ products may take a few minutes via Shopify’s Bulk Operations API.
3. Enable the Theme App Extension
Go to Shopify Admin → Online Store → Themes → Customize.
In the Theme Editor, click App embeds (bottom-left toggle icon).
Find Clearly Agent and toggle it on, then Save.
This adds the chat widget to every page of your store. It survives theme changes and updates, and can be enabled/disabled per-page via the Theme Editor section targeting.
4. Test on your store
Open your storefront in a new tab. You should see the chat widget FAB in the bottom-right. Open it and ask a real question — "do you ship to Canada?", "anything in a size 10?" — the agent should answer in seconds with real policy and inventory data.
Every test conversation appears live in Conversations inside the Shopify Admin, so you can watch it stream in.
5. (Optional) Start free, upgrade when ready
The Free plan includes every feature, limited by conversation volume — perfect for trying the agent with real customers. When you’re ready for unlimited conversations, white-label branding, and priority support, upgrade to Clearly at a flat monthly rate. Billed through Shopify; upgrade or cancel any time.
Embedded merchant admin
After install, every page of Clearly lives inside admin.shopify.com/apps/clearly. Nothing to learn, nothing to log into separately.
Dashboard — revenue attributed to the agent, usage meter, quick nav.
Conversations — every chat with status tags (Open, Waiting, Resolved). Click any row to see the transcript, or hit Take Over to jump in as yourself.
Tickets — refunds, bulk orders, abandoned carts, and size inquiries land here automatically with priority + assignee.
Knowledge — teach the agent your brand voice, policies, FAQs, size guides. Luna uses all of it, word for word.
Appearance — accent color, avatar image, widget position, custom instructions.
Settings — tone, model tier, language defaults, support email.
How catalog sync works
Initial sync: On install, Clearly fetches your entire catalog via Shopify’s Bulk Operations API — handles stores with 100K+ products without rate-limit issues.
Ongoing sync: Clearly registers webhooks for products/create, products/update, products/delete, and inventory_levels/update. Changes appear in the agent’s knowledge within ~5 seconds.
What gets indexed: title, description (HTML stripped), price, compare-at price, variants (size, color, material — each with own SKU/stock), images, tags, collections, vendor, product type, inventory, and metafields.
Conversion attribution
When the agent adds an item to a customer’s cart, it writes a clearly_conversation_id attribute on the cart.
When the order is placed, Shopify fires orders/create and orders/paid webhooks. Clearly checks for the conversation attribute and records the conversion — visible in your Dashboard as agent-attributed revenue within minutes.
Webhooks registered
| Topic | Purpose |
|---|---|
| products/create | Add new products to agent knowledge |
| products/update | Update details (price, description, variants) |
| products/delete | Remove products from agent knowledge |
| inventory_levels/update | Update stock status in real time |
| orders/create | Conversion attribution via cart attributes |
| orders/paid | Revenue confirmation |
| app_subscriptions/update | Billing tier changes |
| app/uninstalled | Cleanup + pause billing |
| customers/data_request | GDPR data export |
| customers/redact | GDPR customer redaction |
| shop/redact | GDPR shop redaction on uninstall |
Shopify CLI (for developers)
If you’re developing locally or extending the integration:
`
npm install -g @shopify/cli
shopify version # 3.x+`
The CLI is useful for:
- Creating a development store for testing
- Running the embedded admin locally with shopify app dev
- Managing Theme App Extensions
See the Testing guide for local development setup.