# Synthia > Synthia is AI search and merchandising for Shopify storefronts. Shoppers get a > dual-mode search widget — semantic product grids for product queries, and Sophie, > a catalog-grounded AI shopping assistant, for questions — with add-to-cart in the > conversation. Merchants get a dashboard that shows every search, flags the failing > ones with one-click fixes (pins, hides, synonyms), and attributes revenue to > individual search terms and merchandising decisions. Facts agents should rely on: keyword search is never metered (quotas apply only to Sophie's conversational answers — Free 70/7d, Growth $79 400/30d, Scale $299 2000/30d); out-of-stock and non-active products are excluded from results by design; zero-result searches can be fixed in the Optimize page by pinning the closest candidates or creating a synonym; attributed revenue is descriptive ("this order started from this search"), always shown with a coverage figure, and is never a causal "lift" claim; catalog re-sync after big changes is manual today (Settings → Re-sync catalog). Human-readable site: https://synthia-docs.pages.dev/ ## Docs - [Getting started](https://synthia-docs.pages.dev/getting-started.md): Install to live AI search, then the first week of optimization — written for a merchant, no developer required. - [Feature guide](https://synthia-docs.pages.dev/feature-guide.md): Every surface: the storefront widget (search grid, Sophie, add-to-cart), Home, Analytics, Optimize, Rules, Settings, Ask Synthia, Sidekick. - [Technical guide](https://synthia-docs.pages.dev/technical-guide.md): Architecture, integration surface, attribution pipeline, data handling and privacy, performance, troubleshooting. --- # Getting Started with Synthia **Audience:** a merchant (or their ops person) installing Synthia for the first time. **Goal:** from install to a working AI search on your storefront, then your first week of optimization. No developer required. --- ## What Synthia does, in one paragraph Synthia replaces your storefront's native search with a dual-mode AI search widget. Shoppers who type a product query ("linen sheets") get an instant semantic product grid — it matches meaning, not just exact words. Shoppers who ask a question ("what do you recommend for a cozy winter look?") get **Sophie**, an AI shopping assistant who answers from your catalog only and recommends real products with add-to-cart buttons. Behind it, a merchant dashboard shows you what shoppers search for, which searches fail, and — when a search leads to a purchase — the revenue attributed to it. ## 1. Install 1. Install Synthia from the Shopify App Store (or your install link). 2. Approve the permissions screen. Synthia requests four scopes and no more: - **read_products** — to index your catalog for search - **write_themes** — to add the search widget to your theme - **write_pixels** — to activate the purchase-attribution pixel - **read_customer_events** — to receive checkout events for attribution 3. When the OAuth screen completes you land in the Synthia dashboard, and two things start automatically: - **Catalog sync** — your products begin indexing immediately. Batches run every few minutes; a few hundred products typically finish in well under half an hour. Watch progress under **Settings → Catalog & sync**. - **Attribution pixel** — activated automatically, no setup step. ## 2. Put the widget on your storefront The widget ships as a Theme App Extension, so it's added from Shopify's own Theme Editor — no code: 1. In Shopify Admin: **Online Store → Themes → Customize** (your live theme). 2. On the page where you want search (the homepage works well, near the top), choose **Add section** (or **Add block** inside a section) and pick **Synthia Search** under Apps. 3. Position it — high on the page is best; the widget ships collapsed as a small launcher pill, so it doesn't dominate your layout. 4. **Save.** What shoppers see: a small pill ("✦ Sophie · Ask me anything"). Clicking it opens a chat-style drawer from the right with a greeting and suggested questions. As the shopper scrolls, the pill docks to the bottom-right corner so search is always one tap away. ## 3. Verify it works - On your storefront, open the widget and search a product word you know you carry ("snowboard", "sheets"). You should get a product grid. - Ask a question ("what do you recommend for a beginner?"). Sophie should reply in a few sentences with product cards. - If a search returns nothing while sync is still running, give it a few minutes — the catalog indexes in batches. Check **Settings → Catalog & sync** for the product count. ## 4. Name your assistant (optional, recommended) Sophie is the default persona. To rename her and set her tone, go to **Settings → Brand voice** and write a short instruction, e.g.: > Your name is Stella. Warm, breezy coastal tone. Keep it brief. The widget's greeting, header, and launcher pick up the new name automatically. Brand voice controls tone and vocabulary only — Sophie's guardrails (catalog-only answers, no invented products, no off-topic content) always stay in force. ## 5. Your first week — the optimization loop Synthia's dashboard is built around one loop: **Analyze → Act → Measure.** **Day 1–2: let data accumulate.** Home fills with searches as shoppers use the widget. **Check "Fix today" on Home.** It lists searches that came up empty or off-target, with how many shoppers hit each one. For each term you have three one-click moves: - **Synonym** — the shopper's word means something you call differently ("comforter" → "duvet"). Creates a synonym so both terms match. - **Pin** — opens that search in Optimize so you can pin the right products to it. - **Dismiss** — it's noise (an internal test, a product you don't carry). Hides it. **Browse Optimize.** The Optimize page opens with two clickable lists — **Needs attention** (failing searches) and **Top searches** (your most popular queries). Click any term to see exactly the grid shoppers see, then drag products into the order you want. Drag a product to a slot to pin it there; drag it to the tray to hide it from that search. Save, and your storefront reflects it immediately. **Watch "Did it work?" on Home.** After you add a synonym or pin a product, this panel tracks whether the failed searches actually stopped failing — so you close the loop instead of guessing. **Check attributed revenue.** When a shopper adds a product from Synthia's results and checks out, the revenue appears on Home (headline number) and Analytics (full detail, with a coverage percentage that tells you how much of your order volume the number is based on). Read it as a floor, not the full picture — shoppers who decline analytics consent aren't counted. ## 6. Plans and quotas | Plan | Price | Sophie answers | Window | |---|---|---|---| | Free | $0 | 70 | rolling 7 days | | Growth | $79/mo | 400 | 30 days | | Scale | $299/mo | 2,000 | 30 days | Two things worth knowing: - **Keyword search is never metered.** Quotas apply only to Sophie's conversational answers. If Sophie hits the quota, she politely pauses and shoppers still get the full keyword search grid — your search never goes dark. - Upgrades go through Shopify's own billing confirmation (**Settings → Plan**), so the charge appears on your regular Shopify invoice. ## 7. Keeping your catalog in sync - New products, price changes, and stock changes are picked up when the catalog syncs. **Today, sync after install is manual**: after a significant catalog change (a product launch, a large price update), press **Re-sync catalog** in Settings. The sync is incremental-safe — re-running it never duplicates anything. - Products that are draft/archived, or that have no purchasable variant (out of stock with no oversell), are deliberately excluded from search results so shoppers never land on a dead end. If a product is "missing" from search, check its status and inventory first — see the [Technical guide](technical-guide.md#troubleshooting). ## Where to go next - [Feature guide](feature-guide.md) — every dashboard surface and widget behavior. - [Technical guide](technical-guide.md) — architecture, data handling, troubleshooting. - [Functional design](functional-design.md) — how search decisions are actually made. --- # Synthia Feature Guide **Audience:** merchants using Synthia day-to-day. One section per surface: the storefront widget, then each dashboard page. Setup lives in [Getting started](getting-started.md); the mechanics behind these behaviors live in [Functional design](functional-design.md). --- ## The storefront widget ### Launcher and drawer The widget ships collapsed: a small pill with your assistant's name ("✦ Sophie · Ask me anything"). It sits where you placed the block in the Theme Editor; when the shopper scrolls past it, it docks to the bottom-right corner so it stays reachable. Clicking opens a right-side drawer (full-width on mobile) rendered above all theme content, with a greeting from your assistant and three tappable suggestion chips. ### One thread, two answer modes Every query goes into the same chat thread; Synthia decides per query how to answer: - **Product queries** ("blue snowboard", "linen sheets") render an instant product grid in the thread — "N matches for 'linen sheets'". On desktop the grid is three columns; long result sets scroll you to the top of the results, not past them. - **Questions and preferences** ("what's good for side sleepers?", "the softer one") stream a reply from Sophie with product cards inline. Sophie answers only from your catalog, in the order your search ranking and merchandising rules produced — she never invents products or prices. - The modes blend mid-conversation: a shopper can chat with Sophie, type a plain product word, get a grid, then keep chatting. If a mid-chat message looks like a keyword but matches nothing, Sophie answers instead — the shopper is never dead-ended. ### Product cards and add-to-cart Every card links to the product page. Single-variant products also get an **Add to cart** button directly on the card: - A successful add shows "Added ✓", updates your theme's own cart drawer/badge in the background, and keeps the shopper in the conversation. - If the product can't be added (sold out), the button turns into a disabled "Sold out" in place — the shopper picks another card rather than being navigated away. - Multi-variant products (sizes/colors) stay as product-page links, where your theme's variant picker takes over. ### Session continuity The conversation survives navigation: a shopper can open a product page, come back, and the thread — including result grids and the open drawer — restores exactly. Continuity is per-browser-tab and expires after 6 hours. ### Assistant persona Name and tone come from **Settings → Brand voice**. Guardrails are always on regardless of voice: catalog-only scope, polite refusal of off-topic requests, resistance to prompt manipulation, no profanity. --- ## Home — the daily glance - **Ask Synthia bar** — ask about your own search data in plain English: "what are shoppers failing to find?", "what are my top searches this month?", "why isn't 'wedding dress' showing results?". Answers are computed from your live data and come with a one-tap action (Fix → synonym, Merchandise → Optimize). Three suggestion chips seed the pattern; off-topic questions get a polite decline. - **This-week KPIs** — searches (with week-over-week delta and sparkline), zero-result rate, Sophie's share of searches, Sophie quota usage. - **Attributed revenue** — the headline number: revenue and orders attributed to Synthia searches this week, with the week-over-week delta. Full detail lives on Analytics. - **Fix today** — the top failing searches right now, each with Synonym / Pin / Dismiss actions and a count of shoppers affected. - **Did it work?** — outcomes of your recent changes: after a synonym or pin, did the failed searches for that term actually stop failing? - **Health strip** — catalog sync status, Sophie quota status, a link to the Theme Editor for widget placement. ## Analytics — the deep dive Window toggle: **7 days / 30 days** applies to the whole page. 1. **Zero-result searches (hero)** — every search that came up empty or off-target in the window, ranked by shopper count, each with Create synonym / Pin a product / Dismiss. Dismissed terms stay hidden everywhere (Home, Analytics, Optimize). 2. **Attributed revenue (hero)** — revenue and orders attributed to Synthia searches, a daily trend, and **coverage**: the share of your store's orders that carried a search attribution — read the revenue figure as a floor, not the full picture. Also shows how many merchandising decisions have a confirmed reason (see Optimize → "Why these choices?"). Per-rule revenue is on the Merchandising page. 3. **Search volume** — daily bars: teal matched a product, amber came up empty. Fewer amber bars over time = your fixes are landing. 4. **Top searches** — your 25 most frequent queries with counts and a keyword/ conversational tag, each with a **Merchandise →** link straight into Optimize. 5. **Sophie engagement** — conversational share, trend, quota meter, and an upgrade prompt when you approach the quota. 6. **Search performance** — p50/p95 response times per mode against budgets (keyword 600ms, conversational 800ms), flagged when worth a look. ## Optimize — the visual merchandiser **Start by browsing, not typing.** With no query selected, the page shows two clickable lists: **Needs attention** (searches that failed recently) and **Top searches**. Click any term — or type one in the search bar, or use the "Merchandise a query…" box that's in the top nav on every page. **The shelf editor.** For a query with results you see the live shopper grid — exactly what shoppers see, current rules applied: - **Drag a product to a slot to pin it there.** Pinned products hold their position; everything else follows Synthia's ranking. The rank number on each card is the slot. - **Pin here / Unpin** on each card toggles pinning without dragging. - **Hide** (or drag to the tray) removes a product from this search only — the tray below the grid shows everything hidden for this query, with one-click Restore. - **Save changes** in the sticky bar applies everything atomically; your storefront reflects it immediately. Discard reverts. - **Also applies to:** if the query participates in a synonym group, a note shows which other terms your changes will also affect. - Pins and hides are **query-scoped** — pinning the Lux duvet for "duvet cover" doesn't touch "lux". The same product can be pinned to as many different searches as you like, each at its own position. **When a search has no results**, the page explains why in plain language ("closest match scored 0.56, below the 0.65 confidence floor — so shoppers see nothing") and shows the closest candidates as pinnable cards. Pin one and save — it will genuinely appear in live results for that search, even though it didn't clear the bar organically. A "Create a synonym instead" link covers the vocabulary-mismatch case. **Why these choices? (reason capture).** After you save, each pinned/hidden product shows the reason Synthia inferred (Promotion, Clearance, Stock & availability, New arrival, Seasonal, Strategic choice, Competitive response). Confirm it or correct it — this is how Synthia learns what your merchandising decisions mean, and confirmed reasons appear alongside attributed revenue in Analytics. ## Merchandising (Rules & Synonyms) Reached via "Synonyms & advanced rules →" on Optimize. The form-based view of the same rule engine: - **Rules** — every pin and exclude as a list, each showing its **attributed revenue** ("$785.95 · 1 order", trailing 30 days) so you can see which merchandising decisions actually pay. - **Synonyms** — create groups of terms that should match each other ("comforter, duvet"; "beige, brown"). Groups apply to search matching and to rule scoping. ## Settings — periodic admin - **Catalog & sync** — last sync time, latest job status and product count, and **Re-sync catalog** (queued within 5 minutes; safe to re-run anytime). - **Plan & billing** — current plan, Sophie usage meter, upgrade buttons (Shopify billing confirmation; the charge lands on your Shopify invoice). - **Brand voice** — the persona instruction (name + tone) used by Sophie and the widget. ## Ask Synthia in Shopify Sidekick If you use Shopify's Sidekick assistant in Admin, it can answer the same three questions Synthia's Ask bar handles — failed searches, top searches, and "why isn't this query matching?" — with links back to the right Synthia page to act. No setup; it's available wherever Sidekick is. --- # Synthia Technical Guide **Audience:** a technically-minded merchant, agency, or developer evaluating or operating Synthia. Covers architecture, the integration surface, data handling, and troubleshooting. Internal algorithm detail lives in [Functional design](functional-design.md). --- ## Architecture at a glance Synthia runs entirely on Cloudflare's edge — there are no servers of ours to warm up, and search executes close to the shopper: | Component | What it is | |---|---| | Search worker | Cloudflare Worker — the query pipeline, Sophie, OAuth, ingestion, attribution | | Vector index | Cloudflare Vectorize — semantic index of your catalog (768-dim embeddings) | | Product cache | Cloudflare KV — product cards (title, price, image, handle) for instant rendering | | Merchant data | Cloudflare D1 (SQLite) — merchants, query logs, merch rules, conversions | | Dashboard | Remix app on Cloudflare Pages | | Widget | A self-contained Web Component (``), delivered via Shopify Theme App Extension from Shopify's CDN | | Attribution pixel | A Shopify Web Pixel (strict sandbox), auto-activated on install | | AI models | Embeddings via Workers AI (`bge-base-en-v1.5`); Sophie via Claude Haiku through Cloudflare AI Gateway, with a Workers AI fallback if the primary provider is unavailable | ## The integration surface ### Widget The Theme App Extension block renders: ```html ``` - `shop-domain` (required) — set automatically by the block; identifies the store. - `endpoint` (optional) — override of the query URL; not needed in normal installs. - The bundle is ~26 KB, loads `defer` from Shopify's CDN, is fully self-contained (Shadow DOM — your theme's CSS can't break it and it can't break your theme), and renders in the browser's top layer so theme stacking contexts can't trap it. - The widget's own styling is deliberately independent of the dashboard's brand; it is designed to sit inside any theme. ### Public endpoints the widget calls - `POST /query` — `{ shop_domain, query, messages? }`. Returns JSON (keyword grid, with a `qid` attribution id) or a Server-Sent-Events stream (Sophie, with the qid in an `X-Synthia-Qid` header). Prior turns are passed as `messages` (capped, plain text). - `GET /widget/config?shop_domain=` — public, cached (5 min): the assistant persona name derived from your brand voice. Everything else (dashboard APIs, ingestion, attribution ingest) is non-public surface and not a supported integration point. ### Cart integration Add-to-cart uses Shopify's standard AJAX API (`/cart/add.js`) from the shopper's own session — Synthia never handles payment or checkout. After a successful add, the widget refreshes your theme's cart drawer/badge via the theme's own section-rendering API when the theme exposes one (Dawn and most Dawn-derived themes do); on other themes the cart is still correct server-side and appears on the next page load. ## Attribution: how the revenue number is produced 1. Every search response carries a query id (**qid**). 2. When a shopper adds a product from Synthia's results, the widget attaches the qid to the cart line (`_synthia_qid` line property — the underscore keeps it out of customer-facing display) and as a cart attribute (`synthia_qid`, last-touch). 3. At `checkout_completed`, Synthia's web pixel — **consent-gated**: it only reports when the shopper has granted analytics consent — sends the order's line items and qids to the attribution endpoint. 4. The worker validates qids against real logged queries and writes idempotent conversion rows (an order can never be double-counted, even if the pixel fires twice). 5. Dashboards show **attributed revenue** (descriptive: "this order started from this search") plus **coverage** — the share of pixel-reported orders that carried a qid — so you always know how complete the number is. Synthia deliberately never labels this "lift"; no causal claim is made. ## Data handling & privacy **What Synthia stores:** - Your shop domain and an OAuth access token (Shopify's expiring-token model: 1-hour access tokens, refreshed server-side). - Your product catalog data (titles, types, tags, options, prices, images, selected metafields) — as embeddings and product cards, for search. - Query logs: the search text, mode, timing, result stats. Queries are not tied to shopper identity — no shopper accounts, emails, or names are collected. - Conversions: order id, line product/variant ids, line value, currency, and the qid. No customer name, email, or address ever reaches Synthia. **What Synthia deliberately does not do:** - No shopper PII collection; no cross-site tracking; the pixel reports nothing without analytics consent. - Sophie's conversation history lives in the shopper's browser tab (sessionStorage, 6-hour expiry) — it is not stored server-side. - GDPR webhooks (`customers/data_request`, `customers/redact`, `shop/redact`) are implemented; since no customer PII is stored, redaction requests are straightforwardly satisfiable. **OAuth scopes** — exactly four, all in active use: `read_products`, `write_themes`, `write_pixels`, `read_customer_events`. ## Performance characteristics - Keyword search: designed for a sub-300ms response; the dashboard's Search performance panel holds it to a 600ms p95 budget on your real traffic. - Sophie: streams tokens; first token typically around a second, budgeted at 800ms p95. Responses are capped at ~100 words for speed and scannability. - Sophie has an automatic fallback model path — if the primary AI provider is throttled or down, shoppers keep getting answers. - Quota exhaustion degrades gracefully: keyword search (unmetered) keeps working; Sophie explains she's resting. ## Catalog sync mechanics - **Install:** ingestion starts automatically after OAuth. Products are processed in batches of 150 on a queue that advances every 5 minutes; a few hundred products complete in well under 30 minutes. - **Ongoing:** sync is currently **manually triggered** (Settings → Re-sync catalog) — run it after significant catalog changes. Sync is idempotent: re-runs upsert, never duplicate. (Webhook-driven automatic sync is on the roadmap.) - Each product is indexed as three semantic vectors (identity, attributes, and an AI-written use-case description) — see [Functional design](functional-design.md). - Product metafields in common namespaces (`custom`, `shopify`, `global`, `descriptors`, `advantages`, `smart`) are folded into search, so attribute-style data ("matte finish", "SPF 30") is findable even when it isn't in the title. ## Troubleshooting **A product doesn't appear in search.** Synthia deliberately excludes products that are (a) not `active`, or (b) have no purchasable variant — zero inventory with oversell disallowed. This prevents shoppers landing on dead-end "Sold out" results. Check the product's status and inventory in Shopify Admin, then re-sync. If it's genuinely purchasable and still missing, check when the last sync ran (Settings) — products added since the last sync aren't indexed yet. **A search returns nothing but should match.** Open the term in Optimize — the page tells you whether the closest match fell below the confidence floor and lets you pin products to the term directly, or create a synonym if it's a vocabulary mismatch (shoppers say "comforter", your catalog says "duvet"). **The widget doesn't show on the storefront.** Confirm the Synthia Search block is added and saved in the Theme Editor for the *live* theme. After a fresh app update, Shopify can take a little while to propagate the new extension version to storefronts. **Add-to-cart says "Sold out".** That's correct behavior: Shopify rejected the add (out of stock at add time). The shopper stays in the conversation and picks another product. If it happens a lot for one product, its inventory is the thing to fix — and note the search-exclusion rule above will drop it from results at the next sync. **The cart drawer doesn't update after add-to-cart.** On themes that don't expose a section-rendering API for their cart drawer, the badge updates on next page load; the cart itself is always correct. Most modern (Dawn-family) themes update live. **Sophie's answers feel off-brand.** Adjust Settings → Brand voice. Voice affects tone/vocabulary only; if Sophie is recommending the wrong *products*, that's a search-ranking question — merchandise the underlying query in Optimize instead.