Setup guide
Everything needed to take one webshop from nothing to a working agent. Each step checks itself against the live server — do the step, and it turns green on its own. Steps 1 and 2 are one-time; the rest are per shop.
Could not read setup status — check that the server is running and the admin key is correct.
Enter the shop's permanent .myshopify.com domain — not a custom domain. That is what the widget sends and what this server keys the store on, so a custom domain here produces an install link that cannot work. Find it in Shopify admin under Settings → Domains.
That isn't a .myshopify.com domain. The widget identifies the store by its permanent domain, so a custom domain here will produce an install link and a store record that never match real traffic.
Give the agent its model credentials
Without an Anthropic API key the agent still answers, but from canned mock text — never from your catalog. Set it once; it applies to every shop.
Checking…
Stored encrypted on the server; it is never sent back to this page. Get one from console.anthropic.com.
Connect your Shopify app credentials
Paste the API key and secret from partners.shopify.com → your app → API credentials below (those two are stored encrypted here). SHOPIFY_APP_URL and SHOPIFY_SCOPES are read from the server environment, so they go in Railway → Variables.
Also do this in Partners, where this page can't see it: add <your app url>/shopify/callback to Allowed redirection URLs, and make sure use_legacy_install_flow is true. Miss either and step 3's link fails on Shopify's side with no error here.
Checking…
Set these in the Partners dashboard. This page cannot read or verify them — if any is wrong, step 3 fails on Shopify's side with no error shown here.
Also set Embedded in Shopify admin: Yes, and keep use_legacy_install_flow = true — with managed installation Shopify never calls our callback, so no token is ever stored.
Install the app on this shop
Open this link (or send it to the merchant) and approve the scopes. The access token is stored before you're redirected; minting the Storefront token, scanning the catalog and registering the webhooks then run in the background and can each fail on their own — which is what steps 4 and 6 are here to catch.
Checking…
Confirm the catalog scan
The install scans products, collections, pages, blog articles and policies. Products are fetched page by page with no practical limit; collections, pages and articles take the first 100, 50 and 100 respectively. The agent can only talk about what landed here.
Checking…
Add the widget to the theme
In the shop's Shopify admin:
- Online Store → Themes → Customize
- Switch the top selector to a Product template
- Add block → App blocks → LEDGER sales agent
- Drag it where you want it — under the buy buttons works well
- Check Agent server URL reads the value below, then Save
Checking…
Don't see App blocks? Most often the extension was never published — run shopify app config link then shopify app deploy from the repo, and reload the theme editor. It can also mean the app isn't installed on this shop yet (step 3), or the theme is vintage and has no app-block support — for those, use the Liquid snippet in integration/shopify/ instead.
Verify the widget is live
Open any product page on the storefront. The widget calls this server on load, so this normally turns green within a few seconds of a real page view. Leave this page open — it re-checks on its own. If it stays amber, check the browser console on that product page for a CORS or 404 error.
Checking…
Ask it a question
Ask something only this catalog could answer. Every question is logged under Conversations, which is where the zero-party insight comes from.
Checking…
Analytics could not be loaded — check that the server is running.
The store has been quiet so far.
No conversations yet — install the widget on a product page and shoppers can start asking.
Questions per day
Last 14 days.
No questions yet — the chart fills in as shoppers ask.
Most asked
The five most common questions across all products.
No questions yet.
Products
The agent can only say what is written here. The scan fills in what Shopify knows — title, price, options, images — and deliberately leaves the editorial fields blank rather than inventing them, because everything on this page is quoted to shoppers as fact. Fill them in yourself, or draft them with AI and edit before saving.
Products could not be loaded — check that the server is running.
Nothing scanned yet. Connect a store and run a scan from the setup guide.
Conversations
Every chat a shopper had with the widget, grouped into threads and newest first. Open one to read it the way they saw it. Refreshes every 15 seconds.
No conversations yet.
Install the widget on a product page. As shoppers chat, each conversation lands here, logged, timestamped and exportable.
No conversations match your filter.
Website
URLs the agent uses as training context. Product pages sync automatically; pages, blog articles and policies come in when you connect & scan the store.
Nothing scanned yet — click + Connect store in the sidebar to import this shop's pages, articles and policies.
No URLs match this search.
| URL | Kind | Status | Last scan |
|---|
FAQs
A canonical FAQ list grounded in your product, policy and page data — clustered from real shopper questions once you have them, and written forward from the catalog before you do. Answers only ever use what the store data supports.
This steers which questions get covered and how they're framed. It can't add facts — if the data doesn't support a reassurance, the answer leaves it out rather than inventing it.
No FAQs yet. Generate them from the logged questions.
FAQPage JSON-LD
Styling
How the widget looks and opens on your product pages. Changes apply live — no code changes needed.
Settings could not be loaded — check that the server is running, then reload.
Preview
A static mock of the inline widget and pill with your choices.
Brand voice
How the assistant sounds. Empty fields fall back to your store profile.
Settings could not be loaded — check that the server is running, then reload.
Integrations
Keys and tokens the agent needs to talk to third-party services. Values are stored on the server encrypted with AES-256-GCM — they never appear here in plaintext and are never sent back to the browser.
Could not load integrations — check that the server is running.
Anthropic API key
not setRequired for live answers. Get one from console.anthropic.com/settings/keys. Without a key the agent runs in mock mode.
Shopify app credentials
not setRequired for the "official app" install flow. Get them from partners.shopify.com → your app → API credentials. Optional if you're using the direct snippet install.
Usage & billing
Token usage across chat, search and FAQ generation, and what it roughly costs.
Usage could not be loaded — check that the server is running.
Tokens per day
Last 14 days, input and output stacked.
No usage yet — token counts appear after the first live question.