Reviews

Collect and moderate product reviews with star ratings, photo uploads, helpfulness voting, abuse reporting, and merchant responses.

The reviews module adds a full product review system to your store. Reviews go through a moderation queue before becoming publicly visible, unless you enable autoApprove. Customers can submit photo reviews, vote on helpfulness, and report abuse. Merchants can respond to reviews from the admin dashboard.

Source: modules/reviews · npm: @86d-app/reviews

Installation

npm install @86d-app/reviews

Add the module to your store configuration:

import reviews from "@86d-app/reviews";
import { createModuleClient } from "@86d-app/core";

const client = createModuleClient([
  reviews({
    autoApprove: "false", // default: requires moderation
  }),
]);

Configuration

autoApprove · string · default: "\"false\""

When set to "true", new reviews are immediately published without going through the moderation queue. When "false" (default), reviews start in pending status and require admin approval.

Review lifecycle

createReview()         → pending
updateReviewStatus()   → approved  (publicly visible)
updateReviewStatus()   → rejected  (hidden from store)

With autoApprove: "true", new reviews skip pending and go directly to approved.

Store endpoints

Method	Path	Description
POST	/reviews	Submit a review (with optional images, duplicate prevention)
GET	/reviews/me	List the authenticated customer’s own reviews (paginated)
GET	/reviews/products/:productId	List approved reviews and rating summary for a product
POST	/reviews/:id/helpful	Vote a review as helpful (deduplicated for authenticated users)
POST	/reviews/:id/report	Report a review for abuse or spam

Submit a review (POST /reviews)

{
  "productId": "prod_abc",
  "authorName": "Jane Doe",
  "authorEmail": "[e-mail]",
  "rating": 5,
  "title": "Excellent product!",
  "body": "Exactly what I needed.",
  "images": [
    { "url": "https://example.com/photo.jpg", "caption": "Front view" }
  ]
}

Returns 409 if the authenticated customer has already reviewed this product. Up to 5 images are accepted per review.

List product reviews (GET /reviews/products/:productId)

Query param	Type	Default	Description
take	number	20	Page size (max 100)
skip	number	0	Pagination offset
sortBy	string	recent	recent | oldest | highest | lowest | helpful

{
  "reviews": [...],
  "summary": {
    "average": 4.3,
    "count": 12,
    "distribution": { "1": 0, "2": 1, "3": 2, "4": 4, "5": 5 }
  }
}

Report a review (POST /reviews/:id/report)

{
  "reason": "spam",
  "details": "This review is advertising another product"
}

reason must be one of: spam, offensive, fake, irrelevant, harassment, other.

Admin endpoints

Method	Path	Description
GET	/admin/reviews	List all reviews (filter: status, productId)
GET	/admin/reviews/:id	Get a single review
PUT	/admin/reviews/:id/approve	Approve a review
PUT	/admin/reviews/:id/reject	Reject a review
POST	/admin/reviews/:id/respond	Add a merchant response
DELETE	/admin/reviews/:id/delete	Permanently delete a review
GET	/admin/reviews/analytics	Review analytics including report counts
GET	/admin/reviews/reports	List abuse reports (filter: status, reviewId)
PUT	/admin/reviews/reports/:id/update	Resolve or dismiss a report
GET	/admin/reviews/requests	List review request emails
GET	/admin/reviews/request-stats	Review request statistics
POST	/admin/reviews/send-request	Send a review request email to a customer

Store components

Use these components in your MDX template files.

ReviewsSummary

Compact star rating and review count for use on product cards.

productId · string · required

Product ID to fetch the rating summary for.

<ReviewsSummary productId={product.id} />

---

ProductReviews

Full reviews section with rating summary, distribution bars, review list, and a submit form. Drop this on your product detail page.

productId · string · required

Product ID to display reviews for.

title · string · default: "\"Customer Reviews\""

Section heading.

<ProductReviews productId={product.id} />

---

ReviewForm

Standalone review submission form. Use this when you want to embed the form separately from the review list.

<ReviewForm productId={product.id} />

---

ReviewCard

A single review card showing author, rating, title, body, images, and helpfulness controls.

<ReviewCard />

---

StarDisplay

Read-only star rating display for a given numeric score.

<StarDisplay />

---

StarPicker

Interactive star rating input for use inside a review form.

<StarPicker />

---

DistributionBars

Horizontal bar chart showing the rating distribution (1 to 5 stars) for a product.

<DistributionBars />

Types

type ReviewStatus = "pending" | "approved" | "rejected";
type ReportStatus = "pending" | "resolved" | "dismissed";
type ReviewSortBy = "recent" | "oldest" | "highest" | "lowest" | "helpful";

interface ReviewImage {
  url: string;
  caption?: string;
}

interface Review {
  id: string;
  productId: string;
  customerId?: string;
  authorName: string;
  authorEmail: string;
  rating: number;          // 1 to 5
  title?: string;
  body: string;
  status: ReviewStatus;
  isVerifiedPurchase: boolean;
  helpfulCount: number;
  images?: ReviewImage[];
  merchantResponse?: string;
  merchantResponseAt?: Date;
  moderationNote?: string;
  createdAt: Date;
  updatedAt: Date;
}

interface RatingSummary {
  average: number;
  count: number;
  distribution: Record<string, number>;
}

interface ReviewReport {
  id: string;
  reviewId: string;
  reporterId?: string;
  reason: string;
  details?: string;
  status: ReportStatus;
  createdAt: Date;
}

Only approved reviews appear in product listings and rating summaries. The isVerifiedPurchase field can only be set server-side; it is always false for reviews submitted through the store endpoint.