Clean & minimal
Premium / luxury stores.
- Menu link instead of floating launcher
- Outline buttons, muted accents
- PDP Assistant on product pages only
- Welcome Popup off
- Hide prices in recommendations
User manual
Setting up and customising Refina
A reference guide. Use the menu to jump straight to what you need — or follow Getting started top to bottom for a first-time setup.
Getting started
Quick start — 5-minute setup
Already familiar with Shopify apps? This gets Refina running in under five minutes. Each step links to the detail below.
- Choose a planRefina → Billing
- Build knowledge baseGet Started page
- Enable app embedThemes → Customize
- Set categoryRefina → Settings
- Test itOpen the launcher, ask a real question
What happens next: Refina builds your catalogue intelligence in the background (usually 5–15 seconds per product, depending on each product's data amount). A store with 1,000 products should allow approximately 2.5 hours for knowledge build - this is where Refina's magic happens! You can customise appearance and settings while you wait.
Choose a plan
Refina needs an active plan before it can build your store's knowledge base. The plan you choose affects your monthly query allowance and available features. All plans include a 30-day free trial with full features.
Plan selection tips:
- Lite — smaller stores testing Refina, up to roughly 15,000 monthly sessions.
- Growth — established stores up to roughly 60,000 monthly sessions.
- Pro — high-traffic stores over roughly 60,000 monthly sessions.
Build store knowledge base
Once your plan is active, return to the Get Started page and click Start building intelligence. This kicks off the catalogue sync and AI enrichment. For the concept behind it, see Catalogue intelligence.
Build time: most stores finish in 1-2 hours. Larger catalogues (2,000+ products) may take longer. The build is governed by the amount of data for each product and runs in the background while you customise.
Enable Refina in your theme
Refina appears on your storefront through Shopify's app embed and app blocks. The minimum setup is enabling the app embed, which adds the launcher and full assistant.
Steps:
- In Shopify Admin, go to Online Store → Themes.
- Click Customize on your active theme.
- In the left sidebar, click App embeds.
- Find Refina and toggle it on.
- Click Save.
Important: you must click Save after enabling the app embed, or changes won't apply to your live storefront.
To also add the product-page card, see Product Page Assistant. To configure wording, colours, and placement, see Full assistant.
Set your store category
Your store category tells Refina which vocabulary to use — skincare needs "ingredients", apparel needs "materials", technical gear needs "specifications". Set it in Refina Admin → Settings.
How category affects terminology
The same question — "What's in this product?" — produces category-appropriate language:
| Category | How Refina answers "What's in this product?" |
|---|---|
| Beauty & Skincare | "Contains niacinamide, hyaluronic acid, and vitamin B5. The ingredients work together to…" |
| Outdoor & Technical Gear | "Uses 800-fill duck-down insulation and a ripstop nylon shell. The materials provide warmth-to-weight…" |
| Supplements & Wellness | "Each capsule has 400mg magnesium glycinate with B6. The active ingredients are chelated for…" |
Customising Admin settings
Brand name
Sets the store/brand name used in Refina configuration.
Example"IANS Beauty"
Store category
Helps Refina use appropriate terminology (ingredients, materials, specifications).
TipChoose the category matching your primary focus.
Tone
Sets the broad response style for recommendations.
TipProfessional for most; friendly for lifestyle; expert for technical/B2B.
Setup complete — what's next?
- Wait for the knowledge build to finish (check the Dashboard).
- Customise each surface (Full assistant, Product Page Assistant).
- Test with real shopper questions (Testing).
- Review Analytics to monitor performance.
Overview & Customisations
Refina has several entry points for product advice. They're not separate apps — they're different surfaces at different stages of the journey.
| Surface | What it does | Best for | Where to enable |
|---|---|---|---|
| Full assistant | AI advisor for open-ended questions. | Complex questions, comparisons, follow-ups. | Opened by launcher, menu link, or popup. |
| Launcher button | Floating button that opens the assistant. | Sitewide access. | App embeds → Refina. |
| Menu link | Navigation item that opens the assistant. | Clean navigation-based access. | Shopify menu → /#refina. |
| Product Page Assistant | Product-context card with quick suggestions. | Alternatives & comparisons on a product. | Product template → Add block. |
| Welcome Popup | Optional invitation to get help. | Increasing discovery. | App embeds → Refina. |
Recommended starting setup: enable the launcher first and test it, then add the Product Page Assistant. Only enable the Welcome Popup once you trust recommendation quality.
Customising Configurations
Suggested combinations for different store types.
Maximum visibility
New stores building awareness.
- Floating launcher (right)
- Welcome Popup (10s, once/day)
- PDP Assistant on all product templates
- Show on all pages except cart
- Show badges and prices
Product-page focused
Strong product pages.
- Prominent PDP Assistant
- Hide launcher on product pages
- Show launcher on home/collection
- Custom chip prompts
- Welcome Popup off
Mobile-first
High mobile traffic.
- Vertical launcher orientation
- Show on mobile enabled
- Compact mode on PDP Assistant
- Bottom offset 30–40px
- 2-column product grid
Technical / B2B
Complex products or B2B.
- Expert tone, formal wording
- Show prices and specifications
- Comparison-focused PDP Assistant
- Menu link over floating launcher
Large catalogue
500+ products.
- Clear store category
- Rich descriptions with specs
- Multiple chip prompts
- Launcher + PDP Assistant both on
- Regular intelligence refreshes
Full assistant
The full assistant is Refina's main AI advisor for open-ended questions. Shoppers ask in their own words and receive recommendations with clear explanations. It's customised via your Shopify admin's theme app embed editor: Themes → Customize → App embeds → Refina.
What shoppers can ask
- "What would you recommend for sensitive skin?"
- "Which magnesium is best for sleep?"
- "Show me bikes like the Yeti ASR"
- "What's the difference between these two?"
- "Which one would you choose and why?"
What Refina returns
- Recommended products from your catalogue
- Clear reasons each product matches
- Comparison explanations when useful
- Follow-up guidance to help decide
- Product cards with images, prices, links
How shoppers open it
Floating launcher
A button that floats on your storefront. Maximum visibility and consistent sitewide access.
Menu link
A navigation item linking to /#refina. Clean and unobtrusive, with no floating elements.
Content settings
Heading
Main heading at the top of the modal.
Example"Need help choosing?"
Subheading
Supporting text below the heading.
Example"Ask about ingredients, benefits, or which suits you best."
Launcher button text
Text on the floating launcher.
Example"Help choosing products"
In-widget button text
Button text inside the widget.
Example"Help me choose"
Wording affects engagement. Compare a generic default with category-specific copy:
Generic
Heading: "Need help choosing?"
Subheading: "Ask questions about our products."
Problem: vague value — doesn't say what help they'll get.
Customised
Heading: "Find your perfect skincare routine"
Subheading: "Tell us your skin type — get personalised picks in seconds."
Better: category-specific, clear value, explains what to expect.
Appearance settings
Primary colour
Main button background colour.
TipMatch your store's primary CTA; test contrast on light and dark.
Accent colour
Highlight and interaction colour.
TipUse a complementary colour, distinct enough to draw the eye.
Launcher border radius
How rounded the launcher is (0 = square, 50+ = pill).
TipModern 12–20px · Playful 30–50px · Corporate 4–8px.
Button style
Solid (filled) or outline (border only).
TipSolid for visibility; outline for a subtle look.
Product grid columns
Cards per row in recommendations.
Tip2 for mobile-first; 3 for desktop-heavy. Auto-adapts.
On light backgrounds
Help choosing products
Solid
Help choosing products
Outline
On dark backgrounds
Help choosing products
Solid
Help choosing products
Outline
Behaviour & placement
Trigger method
Floating launcher or menu-link trigger.
UseFloating for visibility; menu link for a clean nav.
Launcher position
Left or right side of the screen.
UseRight matches most chat widgets; left stands out.
Launcher orientation
Horizontal (wide) or vertical (tall).
UseVertical saves horizontal space on mobile.
Bottom offset
Distance from the bottom edge (px).
Use20–30px; increase for sticky footers.
Left / right offset
Distance from the side (px).
Use20–30px; adjust to avoid other floating elements.
Show on mobile
Whether the launcher appears on mobile.
UseEnable for mobile-heavy stores.
Page visibility
Hide on product pages
Removes the launcher from product pages.
UseWhen the PDP Assistant covers product pages.
Hide on cart page
Removes the launcher from cart/checkout.
UseKeep the cart focused on purchase.
Open on page load
Opens the modal automatically.
UseDedicated landing pages only — never sitewide.
Show product badges
Shows "New"/"Sale" badges on cards.
UseHighlight special products; off for cleaner cards.
Show product prices
Shows prices on recommended cards.
UseOn for price-conscious shoppers.
Do not enable "Open on page load" sitewide. Interrupting shoppers on every page is a poor experience. Use it only on specific landing pages.
Welcome Popup
The Welcome Popup is an optional timed prompt that invites shoppers to open Refina. Customise it in the Refina app embed settings. Use it sparingly — start with it off and enable it once you trust recommendation quality.
Enable popup
Turn the popup on or off.
TipStart OFF; enable after testing.
Delay before popup
Seconds before it appears.
Tip8–12s — time to orient, not so long they've left.
Headline
Main popup message.
Example"Need help choosing?"
Subheading
Supporting text.
Example"Get personalised recommendations in seconds."
Yes button
Opens Refina.
Example"Get help"
No-thanks button
Dismisses the popup.
Example"I'm good"
Footer note
Small text beneath the buttons.
Example"Takes 10 seconds"
Show frequency
How often it appears.
Tip"Once per session" is least intrusive. Never "Every visit".
Avoid
- 2-second delay — interrupts shopping
- Frequency "every visit" — annoys returning customers
- Aggressive, salesy wording
- Excessive urgency ("Wait! Don't leave!")
Prefer
- 10-second delay — time to orient
- "Once per session" — respects returning visitors
- Helpful framing — service, not pressure
- Clear value — "takes about 10 seconds"
Product Page Assistant (PDP)
The Product Page Assistant adds a block to product pages that helps shoppers explore alternatives, compare options, and find similar products while viewing a product. It opens a drawer with suggested picks and can hand off to the full assistant for deeper questions.
Similar products
Products close to what the shopper is viewing — alternatives in the same category.
Cheaper options
Lower-priced alternatives for budget-conscious shoppers who like the current product.
Better value
Products offering stronger value or more premium features for a similar price.
Add the block
- In the theme editor, use the page selector at the top.
- Navigate to Products → Default product (or your custom product template).
- Click Add block where you want the assistant to appear.
- Open the Apps tab and select Refina PDP Assist.
- Position it (typically below the Add to cart button) and click Save.
Common mistake: if you're editing the Home page, the block won't appear in the Apps list. Switch to a product template first using the page selector.
Customising Product-page block
Block headline
Main text on the card.
Example"Not sure this is the one?"
Block subcopy
Supporting text beneath the headline.
Example"Get 2–3 best-fit alternatives with reason why."
Button label
CTA text.
Example"Show me alternatives"
Compact mode
Hides subcopy for a tighter layout.
UseWhen space is tight.
PDP Drawer & chips
Drawer heading
Title shown in the drawer.
Example"Similar options"
Drawer subheading
Supporting drawer text.
Example"3 close matches, ranked for you."
Chips 1–4
Preset prompt buttons.
Example"Compare similar", "Best value", "Cheaper options", "Premium choices"
Default price cap
Optional limit for "Cheaper options".
TipBlank uses the current product's price as the ceiling.
Appearance
Button colour
Background of the primary CTA and icon.
TipMatch your product-page CTA buttons.
Button text colour
Text colour on the button.
TipWhite on dark, black on light — keep contrast strong.
Border radius
How rounded the card and buttons are.
Tip8–14px is standard for modern e-commerce.
Drawer accent
Accent for the side drawer (Neutral, Forest, Midnight, Sienna).
TipNeutral matches the button colour.
Testing the Product Page Assistant
- Visit several product pages and open the card.
- Test each preset chip.
- Verify suggestions are relevant to the product being viewed.
- Check price filtering works (if using "Cheaper options").
- Test the handoff to the full assistant with a complex question.
Catalogue intelligence
Catalogue intelligence is Refina's foundation — how it learns what you sell, researches what makes each product unique, and how to match shopper questions to the right products.
- SyncRead your Shopify catalogue
- IndexOrganise for semantic search
- EnrichAdd AI context via Gemini
- LearnBuild product knowledge
- RecommendGenerate product suggestions
1. Product sync
Reads your catalogue via the Admin API: titles, descriptions, images, prices, variants, types, tags, collections, availability.
Frequency: initial sync, then automatic updates.
2. Semantic indexing
Products are indexed by meaning, so "moisturiser for dry skin" matches even without those exact words.
How: vector embeddings map concepts into searchable space.
3. AI enrichment
Gemini adds context — ingredients, materials, specifications, benefits, use cases, comparisons.
Note: Gemini enriches; your catalogue decides what's recommended.
4. Knowledge layer
Combines your data with enriched context so Refina can explain why a product suits a shopper.
Store-specific: built on your catalogue, not a generic database.
When to refresh
Refina syncs changes automatically, but refresh manually when you:
- Add many products at once (bulk import).
- Significantly update descriptions or details.
- Change your store category or product focus.
- Notice recommendations are out of date after big changes.
Product data quality
Recommendation quality is directly tied to product data. Richer information enables better matching and more helpful explanations.
What Refina uses
Title
Primary identifier and search matching.
Do"Hydrating Face Serum with Hyaluronic Acid", not "Serum #42".
Description
What it does, who it's for, why choose it.
DoBenefits, use cases, target customer — real detail over fluff.
Product type
Category matching and filtering.
DoConsistent types across similar items.
Tags
Attributes and characteristics.
Do"Dry Skin", "Fragrance-Free" — not "sample-tag".
Variants
Options and availability.
Do"30ml / 50ml", not "Option 1 / Option 2".
Images
Visual context and cards.
DoHigh-quality photos; clear primary image.
Price
Price-conscious recommendations.
DoKeep current; set compare-at prices for sales.
Collections
Relationships and context.
DoGroup related products meaningfully.
Good vs weak — skincare
Well-optimised
Title: Niacinamide Brightening Serum — 10% Concentration
Description: Lightweight 10% niacinamide serum to reduce dark spots and even tone. Best for combination/oily skin prone to hyperpigmentation. Fragrance-free, vegan.
Tags: Brightening, Niacinamide, Dark Spots, Oily Skin, Vegan
Poorly optimised
Title: Face Serum 2
Description: Good for skin. Apply to face.
Tags: skincare, new, sample-tag
Problem: no ingredients, benefits, who it's for, or how it differs.
Good vs weak — outdoor
Well-optimised
Title: Alpine 500 Down Sleeping Bag — 15°F / -9°C
Description: 3-season down bag rated to 15°F. 800-fill, mummy design, fits up to 6'2", 2.8 lbs, DWR shell. Left/right zip.
Tags: 3-Season, Down, Backpacking, Cold Weather, Lightweight
Poorly optimised
Title: Sleeping Bag - Blue
Description: Warm sleeping bag for camping.
Tags: outdoor, camping
Problem: no rating, materials, weight, or use case. Colour in the title is irrelevant.
Quick audit
- Every product has a descriptive title (no placeholders).
- Descriptions are 100+ words with benefits, use cases, specifications.
- Product types are assigned consistently.
- Tags describe real attributes.
- All products have at least one high-quality image.
- Variants have clear, descriptive names.
- Prices are current and accurate.
- Target customer or use case is mentioned.
Common mistake: assuming AI can "figure out" products from minimal data. Refina enriches understanding, but still needs your data as the foundation.
Improving existing data
- Start with top sellers — improve your 20 most popular products first.
- Add specifications — ingredients, materials, or dimensions.
- Explain use cases — who it's for and when to choose it.
- Fix product types — standardise naming.
- Clean up tags — remove placeholders, add meaningful ones.
- Refresh catalogue intelligence so changes are indexed.
Testing & quality assurance
Test with real shopper questions, not generic queries or placeholder data.
Before launching
- The intelligence build has completed (check the Dashboard).
- The store category is set correctly.
- You've tested on mobile, tablet, and desktop.
- You've asked at least 10 real shopper-style questions.
- All recommended products are actually from your catalogue.
- Explanations make sense and use the right terminology.
- The Product Page Assistant works on multiple product pages.
- The launcher doesn't overlap other site elements.
- Welcome Popup timing and wording aren't intrusive.
Good test questions by category
Beauty & skincare
- "Dry, sensitive skin — what moisturiser?"
- "Difference between these two serums?"
- "Best cleanser for acne-prone skin?"
- "Cheaper alternative to this?"
Supplements & wellness
- "Which magnesium is best for sleep?"
- "Difference between these protein powders?"
- "I'm vegetarian — which suit me?"
- "Can I take these two together?"
Outdoor & gear
- "Bike similar to the [competitor]?"
- "5'8", 160lbs — which frame size?"
- "Full suspension or hardtail for trails?"
- "Sleeping bag for freezing temps?"
Apparel & fashion
- "Best material for summer running?"
- "Jackets like this but cheaper?"
- "Best jeans fit for my body type?"
- "I wear size M — what size here?"
What to look for
Good responses
- Recommends products from your catalogue
- Gives specific reasons products match
- Uses appropriate category terminology
- Explains differences between similar products
- Handles follow-ups naturally
- Cards show correct images, titles, prices
Problematic responses
- Recommends products you don't sell
- Generic explanations without specifics
- Wrong images or outdated prices
- Ignores key details from the question
- Invents features or ingredients
- Fails to explain why products were chosen
Don't test with generic questions like "Show me products", placeholder text, or questions about products you don't sell. They won't reveal whether Refina works with real queries.
Common mistakes
- Testing too early — wait for the build to complete.
- Placeholder products — Refina can't recommend well from empty data.
- Not testing mobile — most traffic is mobile.
- A single question — ask 10+ across product types.
- Only happy paths — also test out-of-stock items and unclear queries.
Analytics & performance
Use the Dashboard and Analytics to monitor usage, understand shopper needs, and improve recommendation quality.
Dashboard
Knowledge status
Whether intelligence is built, building, or needs refresh.
- Active: current
- Building: in progress
- Needs refresh: catalogue changed
Usage summary
Query activity this billing period.
Watch: compare to plan limits; upgrade near the cap.
Quick actions
Refresh knowledge · View analytics · Test Refina.
System health
Alerts for missing category, empty catalogue, or API problems.
Key metrics
Total queries
Questions and recommendations generated.
UseTrack engagement; rising means shoppers find value.
Popular questions
The most common queries.
UseImprove descriptions or customise chip prompts.
Surface breakdown
Split between full assistant and PDP assistant.
UseSee which surfaces shoppers prefer.
Product click-through
Recommendations that lead to product visits.
UseMeasures relevance; low CTR means poor matching.
Follow-up rate
Sessions with multiple questions.
UseHigh follow-up means recommendations are helpful.
Availability: specific metrics and historical depth depend on your plan. Higher tiers include deeper analytics and longer retention.
Troubleshooting
Common setup and usage issues with step-by-step solutions.
I can't see the Refina app block in the theme editor
Cause: you're editing the wrong template — the Product Page Assistant block only appears on product templates.
- Use the page selector at the top.
- Navigate to Products → Default product.
- Click Add block → Apps.
- Refina PDP Assist should appear.
Refina is enabled but I don't see it on my store
- App embed not enabled: App embeds → ensure Refina is on and you clicked Save.
- Launcher hidden here: check "Hide on product pages" / "Hide on cart page".
- Mobile visibility off: check "Show on mobile".
- Menu link misconfigured: verify it points to
/#refina. - Cache: hard refresh or use a private window.
"Start building intelligence" is greyed out
Cause: no active plan.
- Go to Refina Admin → Billing.
- Select a plan and complete activation.
- Return to Get Started — the button should now be active.
Recommendations seem weak or off-target
- Product data: see Product data quality.
- Build incomplete: check the Dashboard.
- Wrong store category: update it in Settings.
- Stale knowledge: click "Refresh knowledge".
- Testing too early: wait for the build.
Refina is slow to respond
Expected: fresh recommendations take 3–8 seconds because Refina searches your product knowledge before explaining.
Investigate if responses take 15+ seconds consistently or time out.
- Check the Dashboard build status.
- Test on a different network.
- Contact support if it persists after the build is confirmed.
Welcome Popup appears too often or at the wrong time
- Too frequent: set frequency to once per session/day.
- Too quick: increase the delay to 10–15 seconds.
- Interrupts checkout: verify it's disabled on cart/checkout.
- Still intrusive: disable it and rely on the launcher/menu link.
Menu link doesn't open Refina
- Verify the URL is exactly
/#refina. - Confirm the app embed is enabled.
- Check the trigger method allows menu-link opening.
- Test in a private window.
- Try from different pages to isolate the issue.
Launcher overlaps other site elements
- Chat widget: adjust offsets or switch sides.
- Sticky footer: increase bottom offset by 60–80px.
- Back-to-top button: change side or adjust offsets.
- Cookie banner: usually temporary — leave unless permanent.
Product images not showing in recommendations
- Missing in Shopify: add images to the products.
- Needs refresh: refresh intelligence after adding images.
- Loading errors: check the browser console for 404s.
Refina recommends out-of-stock products
Behaviour: the current version may include out-of-stock items if they strongly match.
- Ensure availability is set correctly in Shopify.
- Refresh intelligence to sync availability.
- Check the Changelog for stock-filtering improvements.
Analytics shows very low usage
- Launcher not visible: confirm it shows on mobile and desktop.
- Poor placement: a crowded or hidden launcher gets missed.
- Unclear value: test clearer button text.
- No PDP Assistant: adding it increases discovery.
- Low traffic: at 100 visits/day, 2–5 queries is normal.
I need to restore default settings
There's no reset button, but you can restore defaults manually:
- Clear custom text fields (Refina uses defaults).
- Reset colours to your theme's button colours.
- Set launcher to Right, orientation Horizontal.
- Set offsets to 20–30px.
- Enable "Show on mobile"; disable page-specific hiding.
- Disable the Welcome Popup, then Save.
Still stuck? Contact support with: your store URL, theme name, what you're trying to do, what you've tried, and screenshots if applicable.
Frequently asked questions
Does Refina recommend products from outside my store?
No. Refina only recommends products from your Shopify catalogue. If a shopper mentions a competitor product, Refina uses it as context, then finds the closest relevant alternatives in your catalogue.
How does Refina use Google Gemini?
Gemini enriches product understanding with broader context — ingredients, materials, specifications, benefits, use cases, comparisons — which helps Refina explain why products match. Your catalogue still determines what gets recommended.
What is catalogue intelligence?
Refina's store-specific knowledge layer, built from your Shopify data, indexed for semantic search, and enriched with AI context. It matches questions to products by meaning, not just keywords. See Catalogue intelligence.
Full assistant vs product-page assistant?
Full assistant: an advisor for open-ended questions and comparisons. Product-page assistant: fast, product-context suggestions via preset prompts, with handoff to the full assistant for deeper questions.
Do I need the floating launcher?
No. Use the launcher, a menu link, the Product Page Assistant, the Welcome Popup, or any combination. Many stores prefer menu link + PDP Assistant for a cleaner design.
Can I add Refina to my navigation menu?
Yes. Create a menu item linking to /#refina. Clicking it opens the full assistant.
What happens when I add new products?
Refina syncs additions and changes automatically. For major updates (bulk imports, big rewrites), refresh catalogue intelligence on the Dashboard.
Can Refina answer follow-up questions?
Yes. The full assistant is built for conversations — "What's cheaper?", "Compare these two", "Which would you choose?".
How long does the intelligence build take?
Most stores: 5–15 minutes. Large catalogues (1,000+ products): 20–30 minutes. It runs in the background.
Does Refina work with my Shopify theme?
Yes. Refina uses Shopify's standard app embed and app block system, which works with all themes. The launcher and assistant render as overlays.
Can I customise Refina's appearance?
Yes — colours, button styles, wording, launcher position, PDP prompts, and popup messaging. See Full assistant and Product Page Assistant.
What if a shopper asks about something I don't sell?
Refina acknowledges it doesn't have that product and redirects to the closest relevant alternatives. It won't invent products.
How do I know if Refina is working well?
Check three things: the Dashboard shows "Active"; test questions return relevant products with clear explanations; and Analytics shows query volume rising over time.
Can I use Refina alongside other product quiz apps?
Yes, but consider whether it's necessary. Refina handles open-ended questions; quiz apps use structured flows. Running both can confuse shoppers. Test separately first.
Support
If you need assistance, include: your store URL, theme name, where you've enabled Refina, an example question you've tested, and whether catalogue intelligence has finished building.