Reviews & Ratings — Setup per platform

Plans: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓ (reviews integration is plan-agnostic; the underlying platform/app is what enables review collection)

Audience: merchants who want aggregateRating and review schema in their products (improves SERP rich results and LLM trust signals). Also Clione devs working on the schema generator and Pulse score.

---

Why it matters

Schema.org's aggregateRating and review on Product are the only signals that:

• Render the star rating widget in Google Search SERP (huge CTR impact).
• Are explicitly cited by LLM crawlers when users ask "is X any good".
• Boost the Pulse score (10-15 points depending on weighting).

Without them, the Product schema is missing data crawlers expect. Clione's score will reflect that.

⚠️ Important: enable reviews FIRST in your platform, then in Clione

Clione does NOT create reviews. It reads them from your e-commerce platform. If your platform doesn't have reviews enabled, there's nothing for us to pull — and we won't fake placeholder values (Schema.org explicitly forbids that; Google flags it as spam).

---

BigCommerce

Enable reviews

1. BC admin → Settings → Channels → Edit channel (e.g. "Storefront") → Customer Reviews → toggle Enable.
2. (Optional) Configure moderation: Settings → Customer Reviews → choose "Require approval before publishing" or "Auto-publish".
3. (Optional) Configure invitation emails: Marketing → Marketing Emails → Review request → enable and set delay (e.g. 14 days after purchase).

Verify reviews are flowing

In BC admin, open any product → tab Reviews. You should be able to add a manual review here (useful for testing).

Pull into Clione

Once a product has at least one review in BC, Clione's sync will pick it up automatically on the next run. To force a sync now:

• Clione dashboard → store → Sync → Sync products → wait for completion.
• Confirm by opening the product detail in Clione → check that aggregateRating shows a rating count + average.

Third-party review providers

If you use Yotpo, Judge.me, Stamped.io, Reviews.io, Okendo (popular for BC), they typically expose reviews via their own widgets and a separate API. Clione's BC sync reads native BC reviews only. If you want third-party reviews in your schema, two options:

• Tell your review provider to write back into BC's native reviews (most support this — check their "Sync to BigCommerce" setting).
• Use the provider's own schema markup (they inject their own JSON-LD via their widget script). Don't mix; pick one source of truth.

---

Shopify

Enable reviews

Shopify removed the native "Product Reviews" app in 2023. You need a third-party app. Most common:

• Judge.me (free tier, easiest)
• Yotpo Product Reviews & UGC (free tier + paid)
• Loox (paid, photo reviews)
• Stamped.io (free tier + paid)
• Shopify Product Reviews (deprecated but still installed in many stores; legacy)

Confirm the app writes Shopify metafields

Clione reads reviews from Shopify product metafields under namespace reviews.* (the canonical convention used by Judge.me, Yotpo, Loox, Stamped.io when configured correctly). Specifically:

• reviews.rating_count → number of reviews
• reviews.rating → average (0-5)
• reviews.individual → array of individual review objects (optional)

If your review provider doesn't write these metafields, enable the "Schema/SEO integration" setting in the provider's app — they all have it, sometimes called "Rich Snippets" or "Microdata".

Pull into Clione

Clione dashboard → store → Sync → Sync products. After the sync, the product's aggregateRating should appear.

---

How Clione uses the data

When the platform exposes reviews, the schema generator at packages/semantic-core/src/signals/jsonld.ts adds:

{
  "@type": "Product",
  // ... other fields ...
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "reviewCount": "143",
    "bestRating": "5",
    "worstRating": "1"
  },
  "review": [
    {
      "@type": "Review",
      "author": { "@type": "Person", "name": "Jane Doe" },
      "datePublished": "2026-04-12",
      "reviewRating": { "@type": "Rating", "ratingValue": "5" },
      "reviewBody": "Excellent quality, highly recommend."
    }
    // ... up to 5 most recent reviews
  ]
}

Rules we follow:

• Only emit if reviewCount >= 1. Never placeholders.
• review array is capped at 5 most recent (avoid bloating the JSON-LD payload).
• Author names are sanitized (no emails, no PII).

---

How the Pulse score treats reviews

When reviews are not enabled in the platform, Pulse used to mark "Product missing aggregateRating" / "Product missing review" as failures, which capped the score below 100.

After the contextualization fix (task #41), the score will:

• Detect if the platform has reviews enabled (via the Settings → Channels → Customer Reviews check in BC, or via the presence of a review app metafield in Shopify).
• If disabled, those fields are marked as N/A in the Pulse breakdown — neutral, not penalty.
• If enabled but empty, marked as "feature enabled, no data yet" — still neutral.
• If enabled with data but our sync hasn't pulled them, marked as warning (sync issue).
• Only when enabled with data AND we have it, expected to be present and emitted; absence is a failure.

This way, a small store with no reviews can still score 100 if everything else is right.

---

Onboarding tip placement (UI)

The dashboard should surface a contextual tip in three places:

1. Pulse breakdown, next to "Product missing aggregateRating" — show "Habilita reviews en BC (Settings → Channels → Customer Reviews) o instala Judge.me en Shopify" with a link to this doc.
2. Product detail page in Clione, on the schema tab — same message.
3. Onboarding wizard when first connecting a store — show "Recomendamos habilitar reviews en tu plataforma para puntuación máxima". Link to this doc.

Task #TBD tracks the UI work.

---

Comparison: review providers at a glance

Provider	Platforms	Free tier	Writes Shopify reviews.* metafields	Clione integration
BC native Reviews	BigCommerce	Built-in	N/A (native)	Automatic on sync
Shopify Product Reviews	Shopify	Yes (legacy)	Yes	Automatic on sync
Judge.me	Shopify	Yes	Yes (toggle "Rich Snippets" on)	Automatic on sync
Yotpo Product Reviews	Shopify + BC	Yes (limited)	Yes (toggle "Rich Snippets" on)	Automatic on sync
Loox	Shopify	No (paid only)	Yes (toggle "SEO integration" on)	Automatic on sync
Stamped.io	Shopify + BC	Yes	Yes (toggle "Schema markup" on)	Automatic on sync
Okendo	Shopify + BC	No (paid)	Yes	Automatic on sync
Reviews.io	Shopify + BC	Yes (limited)	Yes (under "Integrations → Schema")	Automatic on sync

Most third-party apps default to "Off" for the metafield/schema integration. The first action after install is always: open the app settings, find "Rich Snippets" or "Schema markup", and toggle on. Without that toggle, Clione has nothing to pull.

Troubleshooting

aggregateRating missing on the storefront JSON-LD even after the review app is installed and configured — Three places to check:

1. The app actually wrote the metafields. Open Shopify admin → product → Metafields section → look for reviews.rating_count. If absent, the app didn't write — check the app's "Rich Snippets" or "Schema integration" toggle.
2. Clione's sync picked them up. Open the Clione product detail → Raw JSON tab → search for aggregateRating. If absent, run a fresh sync.
3. The Schema Injector / Theme App Extension is enabled. Without it, the metafield exists but doesn't reach the page. See Schema Injector.

BC product shows 5 reviews in BC admin but Clione says 0 — Sync timing. Clione's sync reads reviews per product on the product walk. Run a fresh sync; if still 0 after sync completes, the BC channel might be filtering the reviews. Check Settings → Channels → Storefront → Customer Reviews — is it set to "Auto-publish" or "Require approval"? Pending reviews don't count.

Shopify product shows reviews in the app's widget but not in Clione's JSON-LD — Almost always the "Rich Snippets" toggle in the review app. After flipping it on, allow the app a few minutes to backfill the metafields, then run a fresh Clione sync.

Reviews count is correct but the average rating is wrong — Each app computes the average slightly differently (weighted vs simple, rounding rules). Clione uses the value from the reviews.rating metafield verbatim — fix the discrepancy at the review-app level.

Star rating doesn't appear in Google SERP even though JSON-LD is correct — Google takes 4-12 weeks to surface stars on SERPs for new products, and it's never guaranteed. Use Google's Rich Results Test to confirm the markup is valid; SERP visibility is a separate ranking decision.

Per-platform install steps for the most common providers

Judge.me (Shopify) — fastest path

1. Shopify App Store → install Judge.me.
2. Judge.me dashboard → Settings → SEO → toggle Rich Snippets on.
3. (Optional) Settings → Display → toggle Show ratings on collection pages to render the small star icon in catalog grids.
4. Wait ~5 minutes for Judge.me to backfill metafields on existing reviews.
5. In Clione, run Store → Sync → Products to pull the metafields.

Yotpo (Shopify) — extra step

1. Shopify App Store → install Yotpo Reviews.
2. Yotpo dashboard → Apps → enable Rich Snippets.
3. Apps → enable Product Metafields Sync (Yotpo-specific — without it, only widget-rendered stars; no metafields).
4. Wait for sync.
5. In Clione, Store → Sync → Products.

Stamped.io (Shopify or BC)

1. Install via app store.
2. Stamped dashboard → Settings → Display Settings → SEO → toggle Rich Snippets / Schema Markup.
3. Settings → Product Reviews → Integrations → toggle "Sync to Shopify metafields" (Shopify) or "Sync to BC native reviews" (BC).
4. Wait for sync.
5. In Clione, Store → Sync → Products.

Loox (Shopify)

1. Install from app store (paid).
2. Loox dashboard → Settings → Schema markup → toggle on.
3. Wait for sync.
4. Clione sync.

Why we don't fabricate ratings

The merchant FAQ we get most often is "can Clione generate placeholder ratings?". The answer is no, and won't change:

• Google's Rich Results documentation explicitly forbids placeholder or self-generated ratings.
• Detected fake ratings result in manual penalties (rich results suppressed, sometimes a search ranking penalty).
• LLM crawlers are increasingly suspicious of unverified ratings and may deweight them anyway.
• It's bad for shoppers — a 4.7 stars rating with no underlying reviews is more damaging than no rating at all when shoppers discover it.

The right path is to collect real reviews. If your store has no reviews yet, use the LLM-friendly proxies Clione does generate (reasoning, recommended_for, decision_logic) instead — they don't pretend to be third-party validation.

Related

• docs/SIGNALS.md — what signals we generate per entity type.
• docs/PULSE_SCORING.md — how the score is weighted.
• packages/semantic-core/src/signals/jsonld.ts — schema generator (review/aggregateRating block).
• Task #41 — contextualize Pulse score (don't penalize for unavailable features).