Documentation

EditMuse is an AI shopping concierge for Shopify. Shoppers describe what they want (or answer a short quiz), and EditMuse recommends products from your catalogue — with short "Why these picks?" explanations.

It is designed so core discovery does not require shopper log-in or personal identity. EditMuse works with any Shopify theme that supports app blocks (Online Store 2.0 and above).

Step 1: Open the Shopify App Store, find EditMuse, and choose Add app.

Step 2: Approve installation. Shopify opens the app inside your admin.

Step 3: Use Setup & health (and Diagnostics if shown) to confirm everything is connected before you go live.

App proxy (why it matters)

The storefront talks to EditMuse through Shopify's app proxy at /apps/editmuse. If the proxy is misconfigured, the concierge cannot load.

1. In Shopify admin: Settings → Apps and sales channels → EditMuse and check App proxy (subpath is typically editmuse under apps).
2. In EditMuse, open Diagnostics and confirm the proxy is healthy.

1. In EditMuse: Experiences → Create experience.
2. Choose a mode — Guided Quiz, Ask, or Hybrid (see Experiences section below).
3. Set a name, how many results to show, tone, matching strictness (Strict / Balanced / Flexible), and which collections (and exclusions) apply.
4. Save. Set one experience as Default unless each theme block specifies an experience.

Link the theme block to the experience

In the Concierge block settings (theme editor), choose Default or a specific experience. Save the theme.

Fastest path: In EditMuse, open Setup & health. Use the quick-add links to open the theme editor, or add blocks manually.

1. Go to Online Store → Themes → Customize.
2. On the template where you want the button (often Home or a landing page), Add block and choose EditMuse Concierge (under Apps).
3. Set the button label, style, and placement. Save the theme.

Online Store 2.0 JSON templates work best. Very old themes may have limited app-block support — consider a modern theme or manual placement only where your theme allows app blocks.

Results page

After a run, shoppers land on a dedicated results page (default URL path /pages/editmuse-results).

1. Create a page in Shopify with handle editmuse-results (unless you change the Result URL in the Concierge block — then match that page).
2. Add the EditMuse Results block on that page's template.
3. Do not put that page in your main navigation — shoppers should arrive via the concierge (with a session in the URL), not by browsing the menu.

The fastest path from install to live:

1. Install from the Shopify App Store and approve permissions.
2. Run Diagnostics — confirm proxy health and app connection.
3. Create an Experience — pick a mode, select collections, set tone.
4. Add the Concierge block to your theme on the desired page.
5. Create the results page (/pages/editmuse-results) and add the Results block.
6. Link the theme block to your Experience (or use Default).
7. Test end-to-end — open your live storefront as a shopper, tap the concierge button, complete the flow, and confirm you see recommendations and "Why these picks?"
8. If something fails, check Diagnostics in the app and see Troubleshooting below.

An experience is your configuration for one concierge "recipe": how shoppers interact (quiz / ask / hybrid), which products are in scope, how many results to show, and how the AI sounds (tone).

You can create multiple experiences — for example, one for your homepage (store-wide) and another for a seasonal collection campaign — and pick which one each theme block uses.

Each experience operates independently with its own: - Mode (Guided Quiz, Ask, or Hybrid) - Product scope (included collections and excluded tags) - Result count and tone - Matching strictness (Strict, Balanced, or Flexible) - Search depth (varies by plan)

When creating or editing an experience, you configure:

Mode — Choose how shoppers interact:

Result count — How many products to recommend per session. Change this in Experiences in the app (the theme block follows the experience setting).

Tone — Controls how the AI communicates. Set the personality and formality to match your brand voice.

Matching strictness — Controls how tightly recommendations align with the shopper's input: - Strict — Favours exact product-type and facet alignment first. Best when your catalogue metadata is strong and you want tighter precision. - Balanced (recommended) — Keeps strict matching when enough exact options exist, then broadens selectively to avoid under-filled result sets. - Flexible — Allows broader discovery earlier, useful for sparse catalogues or exploratory shopping behaviour.

Theme block text — For Ask and Hybrid modes, you can customise the title and placeholder text in the Concierge block. Guided Quiz does not use Ask/Hybrid text fields.

Control which products EditMuse can recommend:

• Include collections where recommendations should come from.
• Exclude tags for products that must never appear (e.g. samples, archived, out-of-season).
• Choose whether out-of-stock products are allowed in results.

If the product pool is too small or mismatched, you will see weak or empty results — widen scope or improve product data first.

Catalogue quality (all industries)

EditMuse matches shopper language to text in your catalogue: titles, types, tags, options, and description snippets — not product photos as the main signal. Stronger, consistent product copy improves results for any vertical.

Tips for better matching: - Use descriptive, natural-language titles (not just SKU codes). - Tag products with common synonyms shoppers might use. - Keep product type consistent across similar items. - Fill in options (size, colour, material) accurately.

The tone setting controls how EditMuse communicates with shoppers. This affects:

• The language and formality of quiz questions
• How "Why these picks?" explanations are written
• The overall personality of the concierge

Set tone to match your brand voice. A luxury fashion store might use a refined, curated tone. A sporting goods store might be more energetic and direct. A gift shop might be warm and helpful.

The tone applies to the AI's output — it does not change the questions you configure in Quiz mode (those are always your exact wording).

"Why these picks?" behaviour

Tone and matching strictness work together but control different things: - Tone controls writing style (friendly, professional, luxe, etc.) - Matching strictness controls explanation emphasis: - Strict explains exact matches first. - Balanced explains exact matches first, then clearly calls out close alternatives when needed. - Flexible explains broader discovery and why wider matches are still relevant.

Quiz tips

• Aim for roughly 3–7 questions; long flows drop off.
• Use plain language and answers that map to how your products are titled and tagged.
• For select options: the label is what shoppers see; the value is what the app uses for matching — keep values short and aligned with your catalogue.
• See the in-app Creating experiences guide for detailed examples.

Ask lets shoppers type what they want in their own words. EditMuse interprets intent (what they're looking for) and avoid phrases (deal-breakers they mention).

The AI analyses the free-text input against your catalogue's titles, tags, types, and options to find the best matches. Results include "Why these picks?" explanations that reference both the shopper's request and the product attributes that matched.

Example flow: 1. Shopper types: "warm winter coat, not too bulky, under £200" 2. EditMuse identifies: intent = warm winter coat, avoid = bulky, constraint = under £200 3. Results show matching coats with explanations like "Lightweight insulated parka — warm without bulk, £189"

Ask mode relies heavily on your catalogue text quality. To get the best results:

Product titles — Use descriptive, natural language. "Women's Lightweight Down Parka — Navy" works better than "WDP-NV-2024".

Tags — Add common synonyms shoppers might use. If your product is tagged "jumper", also tag it "sweater" and "pullover" for broader matching.

Product type — Keep these consistent. Don't mix "T-Shirt", "Tee", and "T Shirt" across your catalogue.

Options — Fill in size, colour, material, and other attributes accurately. These are key matching signals.

Descriptions — The first ~200 characters of descriptions contribute to matching. Put the most relevant product info at the start.

Very short or vague shopper queries may still return a curated shortlist — set expectations in your tone and product scope.

When to choose Ask mode: - Your shoppers tend to know what they want but not the exact product name - You have a large, varied catalogue where filter navigation is overwhelming - Your products are described in natural language (fashion, beauty, food, gifts)

When Ask may not be ideal: - Products with very technical specs where structured inputs are clearer (consider Hybrid) - You need full control over the shopper journey (consider Quiz)

Configuration tips: - Set the Ask title and placeholder text in the Concierge block to guide shoppers on what to type - Use a tone that matches your brand — this affects how explanations read - Scope to relevant collections — store-wide Ask works well for general discovery, collection-specific Ask works for targeted campaigns - Monitor analytics to see what shoppers are asking for — this reveals catalogue gaps and opportunities

Hybrid runs quiz steps first, then an optional free-text step for refinements that don't fit a button.

Use the quiz for structured signals — budget bands, category taps, occasion selection — and the free-text step for nuance like "gift for someone who hates strong scents" or "nothing too formal".

This gives you the best of both worlds: structured data for reliable matching, plus the flexibility of natural language for edge cases and personal preferences.

Example flow: 1. Quiz step 1: "Who is this for?" → [Me, Gift for someone] 2. Quiz step 2: "Budget?" → [Under £50, £50–£100, £100+] 3. Quiz step 3: "Occasion?" → [Everyday, Special occasion, Active/Sport] 4. Free-text step: "Anything else?" → Shopper types: "nothing too heavy, prefer earth tones" 5. EditMuse combines all signals to recommend matching products

In Hybrid mode, you configure the quiz steps just like Guided Quiz, then EditMuse adds the free-text refinement step automatically.

Question design: - Keep quiz steps to 2–5 questions — the free-text step adds one more, so total interaction should stay under 7 steps - Use questions that capture high-signal structured data: budget, category, occasion, recipient - Save nuanced preferences for the free-text step — don't try to cover everything with buttons

The free-text step: - Customise the title and placeholder in the Concierge block settings (under "Hybrid extra details") - Good placeholder examples: "Any preferences, deal-breakers, or details?" or "Tell us more about what you're looking for" - This step is optional for the shopper — they can skip it and still get results based on quiz answers alone

Hybrid mode supports the same branching logic as Guided Quiz for the structured steps:

Conditional questions — Show or hide quiz steps based on previous answers. For example, if a shopper selects "Gift for someone", you can add a follow-up asking about the recipient's preferences.

Answer-dependent paths — Different answer combinations can lead to different question sequences, ensuring shoppers only see relevant questions.

Best practices for Hybrid branching: - Keep branching simple — the free-text step catches what branching misses - Use branching for major category splits (e.g. "Clothing" vs "Accessories" leads to different size questions) - Don't over-branch — if you need more than 3 levels of branching, Quiz mode may be a better fit - Test each path end-to-end to ensure smooth transitions to the free-text step

Guided Quiz is tap-only — good when you want a consistent path and predictable data for matching.

Designing your quiz: 1. Start with the highest-impact question — the one that most narrows down results (usually category or "who is this for?") 2. Follow with refining questions — budget, style, preferences, constraints 3. End with any optional preferences — these can have a "No preference" option 4. Aim for 3–7 questions total; longer flows increase drop-off

Important: Use clear labels and structured values for anything you rely on for matching. The label is what shoppers see. The value is what EditMuse uses internally — keep values short, consistent, and aligned with your catalogue tags and product types.

Quiz mode supports structured question formats that shoppers answer by tapping:

Single-select — Shopper picks one option. Best for mutually exclusive choices like budget bands, occasion type, or category.

Multi-select — Shopper picks one or more options. Best for preferences like "select all styles you like" or "which features matter most?"

For each question, configure: - Question text — Keep it conversational and clear. "What's your budget?" works better than "Select price range". - Answer options — Each has a label (displayed to shopper) and a value (used for matching). Example: Label = "Under £50", Value = "budget-under-50". - "No preference" option — Include this when the question is truly optional. Omitting it forces a choice, which can frustrate shoppers who genuinely have no preference. - Conditional visibility — Show this question only when a previous answer matches specific criteria (see Branching Logic).

Answer mapping is how quiz responses connect to product matching:

Values drive matching — EditMuse uses the answer values (not labels) to match against your catalogue. If your products are tagged "cotton" and "silk", use those as values, not "Natural fabric" or "Luxury material".

Align with your catalogue: - Match values to your product tags, types, and options where possible - Use the same casing and spelling as your catalogue data - If a value doesn't match anything, that signal is weaker — not an error, but less useful

Budget bands: - Format consistently: "under-50", "50-100", "100-plus" - These map to product prices, not tags — EditMuse handles the price filtering

"No preference" handling: - A "No preference" answer tells EditMuse to ignore that signal entirely - This is better than omitting the question, because you still collect data from shoppers who do have a preference

Testing answer mapping: - After setting up, run through the quiz with different answer combinations - Check that results make sense for each path - If results feel off, review your values against your actual product data

Open Usage in the app sidebar (page title: Usage & Analytics). The dashboard gives you an overview of how shoppers interact with your concierge.

Key views: - Filter by date range to compare periods - Filter by event type to focus on specific interactions - Narrow by experience where the UI allows — useful if you run multiple experiences

The dashboard shows aggregate data. For individual session details, use the export feature.

Each shopper interaction creates a session with data about:

• Session started — When the shopper opened the concierge
• Flow completion — Whether they finished the quiz/ask flow
• Results viewed — The products recommended
• Clicks — Which recommendations the shopper clicked

The conversion funnel

Track the key path: Session started → Results viewed → Recommendation clicked

This funnel reveals where shoppers drop off and helps you optimise your experience configuration, question design, and product scope.

Use Export CSV on the Usage page for spreadsheets or BI tools.

What's included: The export may include more event types than the main on-screen table. Checkout-intent rows may be hidden in the UI but present in the CSV export.

Use exports for: - Deeper analysis in Google Sheets, Excel, or BI platforms - Comparing performance across experiences - Identifying trending shopper queries and preferences - Feeding into your own reporting dashboards

The metrics that matter most for evaluating EditMuse performance:

Completion rate — What percentage of shoppers who open the concierge complete the flow and see results? Low completion suggests too many questions or unclear wording.

Click-through rate — What percentage of shoppers who see results click on a recommended product? Low CTR may indicate scope mismatch or catalogue quality issues.

Credits used — Compare with your plan allocation. Events in analytics may show credits used for heavier steps — compare with Billing if numbers look unexpected.

Top queries (Ask/Hybrid) — What shoppers are typing reveals demand signals and catalogue gaps. If many shoppers ask for something you don't stock, that's market intelligence.

EditMuse can emit anonymous browser events on your storefront for your own marketing tools:

• Klaviyo — Track concierge interactions alongside your email/SMS campaigns
• Google Analytics 4 (GA4) — Include EditMuse events in your GA4 reporting
• Meta Pixel — Feed concierge data into your Meta ad optimisation

EditMuse does not inject those tools into your theme — you add their base tags as usual (via Shopify, Google Tag Manager, or your theme), then add small EditMuse-specific listeners.

Step 1: In EditMuse, go to Billing → Marketing integrations and turn events on.

Step 2: Ensure your marketing tool's base code (Klaviyo snippet, GA4 tag, Meta Pixel) is already loading on your storefront.

Step 3: Add the EditMuse event listener snippet for your tool. Exact listener code is provided in the in-app documentation after install — it's specific to each tool.

Step 4: Test by running a concierge session and checking your tool's real-time event view.

If events never appear: - Confirm the toggle is on in EditMuse settings - Check that your theme loads the listener after the concierge runs - Verify your marketing tool's base code is active on the same pages

When integrations are enabled, EditMuse emits these browser events:

editmuse_recommendations_shown — Fired when results are displayed to the shopper

editmuse_product_clicked — Fired when a shopper clicks a recommended product

editmuse_add_to_cart — Fired when a shopper adds a recommended product to cart

Each event payload includes: - Session context — session ID, experience name, mode used - Product context — product IDs, titles, and relevant attributes

Payloads do not include shopper name, email, or order IDs. EditMuse events are anonymous by design — your marketing tools handle identity resolution through their own mechanisms.

Concierge button does nothing or doesn't show:

1. Confirm the Concierge block is on the correct template and not hidden or covered by another layer.
2. Check Diagnostics in EditMuse for app proxy errors — if the proxy is misconfigured, the widget cannot load.
3. Test without ad blockers or privacy extensions — some block third-party scripts.
4. Open the browser console (F12 → Console) and look for JavaScript errors from other scripts that might interfere.
5. Verify the theme is saved and published (not just in draft).

Results page says "no session": The results page expects a session from a completed concierge run. Do not link it in the main nav — shoppers should always arrive via the flow. For testing, use the full URL from after completing a run.

Empty or weak results: - Widen collections — your product scope may be too narrow for the shopper's query - Relax excluded tags — you may be filtering out relevant products - Check stock rules vs. real availability — if you exclude out-of-stock items, ensure enough are in stock - Improve product data — titles, product type, tags, and options are how the AI matches. Vague or inconsistent data leads to weak results

Recommendations feel wrong: - Align experience scope with placement — a collection-specific experience on your homepage may miss relevant products from other collections - Improve catalogue text and synonyms — if shoppers say "jumper" but your products say "sweater", add synonym tags - Check plan search depth — very large catalogues may benefit from a higher-tier plan with deeper search

Slow loading: - Check your theme's overall performance — heavy themes with many apps can slow everything down - Ensure you're not loading duplicate scripts - EditMuse loads asynchronously and should not block your page render

High credit usage: - Credits are consumed when results are delivered, not when the widget opens - If usage seems unexpectedly high, check analytics for unusual traffic patterns - Review your experience configurations — very broad scopes on high-traffic pages consume more credits

Drop-off during flow: - Reduce the number of quiz questions (aim for 3–7) - Simplify question wording - Ensure the flow works well on mobile — test on real devices, not just browser resize

Marketing tools show no EditMuse events:

1. Enable integrations — In EditMuse, go to Billing → Marketing integrations and confirm events are turned on
2. Check base code — Ensure your Klaviyo / GA4 / Meta base code loads on the storefront pages where the concierge appears
3. Verify listener — The EditMuse event listener must be present and load after the concierge script
4. Test in real-time — Use your marketing tool's real-time event viewer while running a test session
5. Check browser console — Look for JavaScript errors that might prevent events from firing

Still stuck? Use our Contact page or email support@editmuse.ai. Include your store URL, what you tried, and screenshots if helpful — no shopper personal data needed for most issues.

Credits are charged when results are delivered to the shopper. The number of credits depends on how many products are in the result set (tiered usage). Opening the widget or abandoning before results does not use credits in that way. For exact numbers, see Billing in the EditMuse app and the Pricing page.

Each plan includes a monthly credit allocation. Your Billing page in the app and Shopify's invoice are the sources of truth for credit usage.

Credits reset at the start of each billing cycle. Unused credits do not roll over.

Trial period: New stores may receive a trial with up to 7 calendar days and up to 50 credits — whichever limit you hit first. No overage charges during the trial. Approve a paid plan in Shopify to continue when limits are reached.

Paid plans: Plans include monthly credits, experience limits, how many products can be considered per search (search depth), and an overage rate. Higher plans provide: - More credits per month - More experiences (concurrent configurations) - Deeper search depth for large catalogues - Lower per-credit overage rates

Add-ons: Credit packs and extra experience slots are available on paid plans where offered.

To upgrade: Go to Billing in the EditMuse app, or check our Pricing page for plan comparisons.

Billing through Shopify: EditMuse is billed monthly through Shopify. Your subscription appears on your regular Shopify invoice alongside other app charges.

What happens if you exceed your credits: Sessions continue to work. Overage is billed at your plan's per-credit rate on your next Shopify invoice.

Changing plans: Upgrades take effect immediately. Downgrades typically apply at the next billing cycle.

Cancellation: You can remove EditMuse through Shopify's app management. Retention and deletion of data connected to the app are described in our Privacy Policy (including what happens when you uninstall).

Full pricing detail: Pricing page and in-app Billing section.