product-reviews-ratings

What this skill does

# Product Reviews & Ratings

## Overview

Product reviews are the strongest social proof signal in e-commerce — products with 5+ reviews convert at 270% higher rates than products with none. Every major platform has review apps that handle collection, moderation, schema.org markup for Google star ratings, and verified purchase badging without custom code. Only build a custom review system if you need proprietary moderation logic, deep API integration, or review data in your own database.

## When to Use This Skill

- When launching a new store and needing a review collection and display system
- When implementing schema.org `AggregateRating` markup to enable star ratings in Google Search results
- When building a moderation workflow to prevent fake or spam reviews
- When displaying verified purchase badges to increase review credibility
- When triggering post-purchase review request emails automatically after delivery
- When importing reviews from one platform or app to another

## Core Instructions

### Step 1: Determine platform and choose the right review tool

| Platform | Recommended Tool | Why |
|----------|-----------------|-----|
| **Shopify** | Judge.me | Free plan includes unlimited reviews, photo reviews, verified purchase badges, schema.org markup, and post-purchase email requests |
| **Shopify** | Yotpo | More advanced features: Q&A, loyalty integration, Google Shopping reviews syndication — best for mid-market+ stores |
| **WooCommerce** | WooCommerce built-in reviews + WP Product Review plugin | WooCommerce has built-in star ratings; add WP Product Review for schema.org markup and verified purchase gating |
| **WooCommerce** | Judge.me for WooCommerce | Same feature set as the Shopify version; available as a WooCommerce integration |
| **BigCommerce** | Judge.me or Yotpo | Both available on the BigCommerce App Marketplace with full feature parity |
| **Custom / Headless** | Build review API | Required when reviews need to live in your own database with custom moderation logic |

---

### Step 2: Platform-specific setup

---

#### Shopify

**Option A: Judge.me (recommended — free, full-featured)**

1. Install **Judge.me Product Reviews** from the Shopify App Store
2. Judge.me automatically sends a post-purchase review request email after a configurable delay:
   - Go to **Judge.me → Settings → Review Request Emails**
   - Set delay to **5–7 days after fulfillment** (gives customers time to receive and use the product)
   - Customize the email template with your brand colors and product images

3. Configure review display:
   - Go to **Judge.me → Widgets → Install Widgets**
   - Enable the review widget on your product template (Judge.me provides a one-click install)
   - Enable the star rating snippet in product listings

4. Enable schema.org markup:
   - Go to **Judge.me → Settings → SEO**
   - Ensure "Add aggregate rating schema" is enabled — this is what enables star ratings in Google search results

5. Configure verification and moderation:
   - Go to **Settings → Review Settings**
   - Enable **Verified Purchase Only**: only customers who bought the product can leave a review
   - Enable **Auto-publish verified reviews**, manual moderation for unverified reviews
   - Set profanity filter to "Medium" or higher

**Option B: Yotpo (mid-market and enterprise)**

1. Install **Yotpo Reviews** from the App Store
2. Configure review request timing in **Yotpo → Settings → Review Request**
3. Enable **Google Shopping Reviews syndication** if you run Google Shopping campaigns — Yotpo sends review data directly to Google
4. Use **Yotpo Q&A** to add a question-and-answer section below reviews on the PDP

**Testing schema.org markup:**
After enabling Judge.me or Yotpo schema output, validate with [Google's Rich Results Test](https://search.google.com/test/rich-results) using your product page URL. Star ratings appear in Google Search within 1–2 weeks of indexing.

---

#### WooCommerce

**WooCommerce built-in reviews (free, basic):**

1. Go to **WooCommerce → Settings → Products → Reviews**
2. Enable **Enable product reviews**
3. Enable **Show "verified owner" label on customer reviews** — this restricts reviews to customers who purchased the product
4. Enable **Reviews can only be left by "verified owners"** to gate unverified submissions

**Adding schema.org markup and enhanced display:**

1. Install **WP Product Review** from the WordPress plugin directory
2. WP Product Review adds:
   - Aggregate star rating schema.org markup (required for Google rich results)
   - Star rating display in product listings
   - Review pros/cons fields
3. Configure in **WP Product Review → Settings**

**Automating review request emails:**

1. Install **Klaviyo** or **AutomateWoo** for post-purchase email automation
2. In Klaviyo: create a **Flow** triggered by the "Placed Order" event with a 7-day delay, containing a review request link
3. In AutomateWoo: go to **AutomateWoo → Workflows → Add** → trigger: "Order Status Changed to Completed" with a 7-day delay

**Judge.me for WooCommerce:**
- Install **Judge.me for WooCommerce** (available at judge.me)
- Provides the same review request emails, verified purchase gating, and schema markup as the Shopify version

---

#### BigCommerce

**Judge.me for BigCommerce:**

1. Go to **Apps → Search "Judge.me"** and install
2. Same configuration as the Shopify version — review request emails, schema markup, and verified purchase gating work identically

**BigCommerce built-in product reviews:**
1. Go to **Products → [Product] → Reviews tab** to manually moderate reviews
2. Go to **Settings → Store Settings → Miscellaneous** → enable **Product Reviews**
3. Built-in reviews do not include schema.org markup — install Judge.me or Yotpo to get Google star ratings in search results

**Yotpo for BigCommerce:**
1. Install from the BigCommerce App Marketplace
2. Includes Google Shopping Reviews syndication and SMS review requests alongside email

---

#### Custom / Headless

For headless storefronts, build a review pipeline with post-purchase trigger, moderation, Bayesian aggregate scoring, and schema.org output:

```typescript
// lib/reviews.ts

// POST /api/reviews — accept review submission with signed token verification
export async function submitReview(req: Request, res: Response) {
  const { token, productId, rating, title, body, authorName } = req.body;

  // Validate signed token (generated in post-purchase email, prevents spam)
  const tokenData = await verifyReviewToken(token);
  if (!tokenData) return res.status(401).json({ error: 'Invalid or expired review token' });

  const verifiedPurchase = await db.orderItems.exists({ orderId: tokenData.orderId, productId });

  // Auto-moderation: spam score + profanity check
  const spamScore = await checkSpam({ body, authorName, ip: req.ip });
  const hasProfanity = await checkProfanity(body + ' ' + title);

  const status =
    spamScore > 0.8 ? 'spam' :
    hasProfanity ? 'pending' :
    verifiedPurchase ? 'approved' : 'pending';

  const review = await db.reviews.create({
    productId, orderId: tokenData.orderId, customerId: tokenData.customerId,
    authorName, authorEmail: tokenData.email, rating, title, body,
    verifiedPurchase, status, approvedAt: status === 'approved' ? new Date() : null,
  });

  if (status === 'approved') await updateProductRatingSummary(productId);

  res.json({ reviewId: review.id, status });
}

// Bayesian aggregate: prevents a 2-review product with 5.0 outranking a 200-review product with 4.7
export async function updateProductRatingSummary(productId: string) {
  const reviews = await db.reviews.findMany({ where: { productId, status: 'approved' } });

  const rawAverage = reviews.length > 0
    ? reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length : 0;

  const globalMean = await db.reviews.globalAverageRating();
  const C = 5; // confidence weight — trust product's own average after 5+ reviews
  const bayesianAverage = (C * globa