Understanding Quality Scores

Plans: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓

Read this before showing scores to a customer

The Quality Scores on every product (Durability, Quality Perception, Value for Money, Price Positioning, Typical Competitors) are 100% generated by the LLM based on the product text. They are not backed by reviews, returns, sales data, certifications or any external evidence — yet.

What the LLM uses

When scoring a product, Clione passes the LLM:

• Title
• Description
• Price + currency
• Vendor
• Categories
• Any answers you provided in the Enrichment Wizard (target audience, materials, key benefits, etc.)

What the LLM does NOT use

• Real customer reviews (Google / Trustpilot / internal)
• Returns rate
• Sales / conversion data
• External catalog comparatives
• Manufacturer certifications (ISO, CE, GOTS, OEKO-TEX, etc.)
• Lifecycle test results
• Sustainability databases

What this means for you

1. Scores are synthetic opinion, not verified facts.
2. Same product can produce different scores between runs if the model temperature is non-zero.
3. Useful relatively, not absolutely — the LLM has common sense (Hermès → luxury, Primark → budget). Scores help you differentiate products within your own catalog; they don't benchmark you against competitors.
4. typical_competitors has the same limitation — they're plausible inferences, not verified market data.

How to tell which scores are grounded

Each product shows a badge next to the Quality Scores:

• 🟢 Data-grounded — external evidence backs the score (future: reviews, returns, certifications)
• 🔵 AI + owner hints — you filled the Enrichment Wizard for this product
• 🟡 AI-inferred — pure LLM opinion based on title/description/vendor (default)

How we're fixing this

Already shipped (April 2026)

Enrichment Wizard — evidence questions. The Wizard now has a dedicated Evidence section after the original context questions. Five new fields, all optional:

• Warranty — None / 6m / 1y / 2y / 3y / 5y / 10y / Lifetime
• Certifications — comma-separated list (ISO 9001, CE, GOTS, OEKO-TEX, MIL-STD-810, B-Corp, Fair Trade, etc.)
• Returns rate — brackets from <2% to >20%, plus a Don't know opt-out
• Customer reviews — aggregate rating + count from any source (Google, Trustpilot, internal, marketplaces)
• Manufacturing origin — country + manufacturer name

Filling 3+ of these upgrades your product's badge from amber (AI-inferred) to green (Data-grounded). Filling 1-2 upgrades to cyan (AI + owner hints). The wizard tells you when you've reached the evidence section and what filling does.

Owner-verified Typical Competitors. The Edit tab on a product now has a Typical Competitors section where you can list the real competing products (brand + model + optional reference price + notes). When at least one entry is saved, Clione flags the list as owner-verified and stops letting the LLM regenerate it on re-enrichment. This is the same grounding pattern as the evidence wizard — your input wins over the LLM's guess.

If you don't fill anything, the LLM's inferred competitors continue to appear with an AI-INFERRED label so you always know what you're looking at.

Roadmap (coming)

1. External data connectors — Google Analytics conversion rate, Judge.me & Yotpo reviews APIs, Shopify Refunds API / BigCommerce Returns webhook
2. Per-score provenance — each individual score carries its own source (owner / reviews / returns / llm_synthetic / composite) with an evidence trail, and the UI shows why this score on demand
3. Composite scoring — when multiple sources disagree, the dashboard explains the weighted result instead of picking one and hiding the others

See the full grounding roadmap for technical detail.

Until the external connectors land, treat scores as the LLM's reading of your catalog text, sharpened by whatever evidence + competitors you feed in via the Wizard and Edit tab.

Per-platform notes

The scoring model is identical across platforms. What differs is the input richness the synchronizer can pull and the surface that exposes the scores.

BigCommerce

• The synchronizer reads meta_keywords, search_keywords, brand, options, custom fields, and category path. The richer this is, the sharper the scores.
• BC Reviews (built-in) are not pulled into scoring yet — the connector is on the roadmap. If you have reviews enabled, surface a representative sample in the product description so the LLM sees the language.
• BigCommerce Channels with different price books are not scored separately — the scoring uses the default channel's prices.

Shopify

• The synchronizer reads productType, vendor, all tags, variants (size/color/material), and collection memberships (manual + smart).
• Reviews from Shopify Reviews / Judge.me / Stamped are not pulled into scoring yet. Same workaround as BC: paraphrase representative reviews in the description.
• Shopify Markets with different currencies and prices are not scored separately — scoring uses the primary Market.

How the scoring badge surfaces on the storefront

Scores are never exposed verbatim on the storefront. They are an internal signal used to:

• Rank products in your own dashboard's sortable lists.
• Inform the LLM's reasoning paragraph (which is exposed via the /llm API and JSON-LD description).
• Power the "Typical Competitors" comparison strip on the public Pulse page (if you opt in).

If you want to publish a score-derived signal (e.g. an "editor's pick" badge), use the Promotions module to encode that as a coupon trigger keyed on score range.

Auditing scores in bulk

The Products list has a Score column filter — pick a single score (e.g. Durability) and sort high-to-low to spot outliers. If a high-end product is showing a low durability score, the LLM probably hasn't seen enough description text to infer it; open the Edit tab and add a sentence about construction.

Troubleshooting

A premium product is showing budget Price Positioning — The LLM weighs the price input against the description language. If you sell a 2000€ chair and the description doesn't mention craftsmanship, materials, or brand heritage, the LLM may anchor on the category (chairs) rather than the brand. Fix: expand the description, or add the brand heritage to the Wizard.

Same product, different scores on re-enrich — Expected behaviour at temperature > 0. Lock the score in by filling the Wizard's evidence section — once 3+ evidence fields are filled, the LLM is constrained much more tightly and re-runs converge.

Score badge stays amber even after I fill the wizard — The badge requires 3+ evidence fields plus a re-enrich run. Filling the wizard doesn't retroactively update existing enrichments. Click Enrich on the product detail to regenerate.

Typical Competitors keeps regenerating despite owner-verified entries — Make sure at least one competitor row is saved with all required fields (brand + model). The owner-verified flag only flips when there's at least one complete row.

Scores look inconsistent across categories within the same store — The LLM scores within the catalog context, but it doesn't normalize across categories. A "high quality" pair of socks is a different absolute bar from a "high quality" mattress. This is by design — you're meant to use scores to rank within a category, not across.

Score field reference

Every product enrichment produces these score fields:

Field	Type	Range	Meaning
durability	float	1.0 – 5.0	Inferred build / longevity.
quality_perception	float	1.0 – 5.0	Inferred perceived quality.
value_for_money	float	1.0 – 5.0	Inferred price-to-quality ratio.
price_positioning	enum	budget / mid / premium / luxury	Inferred market segment.
typical_competitors	array	up to 5 brand+model entries	Inferred competitive set.
confidence	float	0.0 – 1.0	LLM's own confidence in the scores (higher = less ambiguous source data).
evidenceSources	array	strings	Which evidence fields the LLM used: owner_wizard, description, vendor_brand, category_context.

Categories, collections, and pages do not get scores — the score model is product-specific. They get the same identity + reasoning + keywords artifacts.

Where scores are exposed via API

If you want to consume scores from your own analytics:

• GET /api/v1/products/:id/enrichment returns the full enrichment payload including all score fields and the evidenceSources array.
• GET /api/v1/public/seo-signals/:platform/products/:id exposes the customer-facing meta + JSON-LD but not the raw scores.

The raw scores are deliberately not exposed on public endpoints — they're an internal signal, not a public claim.

When to re-enrich vs trust existing scores

Three triggers warrant a re-enrich:

1. You added evidence to the Wizard — re-enrich to make the LLM use the new evidence and shift the badge from amber to green.
2. You substantially changed the description — sync brought in the new text but the LLM scored on the old text until you re-enrich.
3. You added owner-verified competitors — re-enrich to lock the LLM out of regenerating the competitor list.

Don't re-enrich just because you don't like a score — re-enrichment burns a credit and the scores are unlikely to swing wildly unless inputs change.

Score badge color reference

Badge	Color	Meaning	What triggers it
Green	Data-grounded	External evidence backs scores	3+ evidence fields filled in Wizard
Cyan	AI + owner hints	Some owner input	1-2 evidence fields filled
Amber	AI-inferred	Pure LLM opinion	No evidence fields filled
Grey	Not enriched	No enrichment run yet	Default state

Badges appear next to the score block on every product detail page and in the export CSVs.

Auditing a single product's scores

When a single product's scores look off, the diagnostic order is:

1. Open the product → Enrichment tab → look at the score values + badge color.
2. Open the Corpus tab — see exactly what text the LLM was given. If the description is sparse or has unrelated content (e.g. instructions for a different SKU), fix the description first.
3. Open the Wizard — fill any unfilled context + evidence fields.
4. Re-enrich.
5. Compare against the previous enrichment via the Versions tab to see what changed.

When scores fluctuate during the same enrichment run

Bulk-enriching 100 products and noticing that the 50th product scored differently from a similar one at position 5? The LLM treats each call independently (no shared context across products in the same batch). Run-to-run variability of ±0.3 on a 1-5 scale is normal.

To minimize fluctuation:

• Fill the Wizard for hero SKUs (locks evidence).
• Use the Enrichment Wizard's Lock scores after first enrich option (Pro/Agency) — once set, re-enrich preserves the score values and only updates the text fields.

Decision: how to use scores in your dashboards

Treat scores as relative signals within the same category. Good uses:

• Rank products within a category to surface high-quality items.
• Filter the catalog to find low-scored products that need description updates.
• A/B test description changes — re-enrich and watch the score shift.

Bad uses:

• Marketing claims ("rated 4.5 by AI!" — see "Why we don't fabricate ratings" in Reviews setup).
• Cross-category comparisons.
• Pricing decisions (the LLM doesn't see real demand data).
• Vendor benchmarking (it scores what's in the text, not what's true).

Score stability across the four entity types

Only products get the full quality-score block. The other entity types get a simpler view:

• Categories / Collections — popularity_indicator (LLM-inferred from product mix), audience_clarity (1-5).
• Pages — content_freshness, intent_clarity, target_audience_match.

These are stored on each entity and are not propagated to the storefront — they're internal signals used by Clione's own catalog organization.