Skip to main content

Reviews & Ratings — Setup per platform

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.

  • 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).