Setting the file. One moment.
Product Reviews · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs
Back to the top of the page Mcloud
Product reviews build trust and influence purchase decisions. Reviews with ratings convert 270% better than products without.
Assumed knowledge : Claude knows how to build forms and display lists. This guide focuses on ecommerce review patterns and trust signals.
Star rating summary (1-5 stars) with distribution
Individual reviews with ratings, text, author, date
Sorting (Most Recent, Most Helpful, Highest/Lowest Rating)
Filtering by rating (5 stars only, 4+ stars)
Verified purchase badges
Helpful votes (upvote system)
Review submission form
Mobile-optimized
Below product details (after add-to-cart)
Before related products
Anchor link in product info: “★★★★★ (127 reviews)”
Only for very large catalogs (500+ reviews)
Link: “View All Reviews”
Most stores show reviews inline on product page
Average rating: “★★★★★ 4.5 out of 5”
Total review count: “Based on 127 reviews”
Large stars (24-32px)
Visual breakdown with clickable bars:
Click to filter reviews by rating
Shows only selected star ratings
“Show all” to reset filter
Why distribution matters:
Perfect 5.0 rating seems fake (customers trust 4.2-4.5 average)
Showing negative reviews builds trust
Distribution helps customers understand product quality
“No reviews yet”
“Be the first to review this product”
“Write a Review” button prominent
Don’t show 0 stars or empty rating
Most Recent (default) - shows latest feedbackMost Helpful (by upvotes) - surfaces best reviewsHighest Rating (5 stars first) - see positive feedbackLowest Rating (1 star first) - see concerns
All ratings (default)
5 stars only
4+ stars
3 stars or less (see negative feedback)
Verified purchases only (highest trust)
With photos only (visual proof)
Recent (last 30 days, 6 months)
“Showing 24 of 127 reviews”
Star rating (1-5 stars selector)
Review text (textarea, 50-500 characters)
Reviewer name (if not logged in)
Review title/headline
Upload images (2-5 max)
Would you recommend? (Yes/No)
“Write a Review” button opens modal or inline form
Position near rating summary
Rating must be selected
Minimum review length (50 characters)
Show character counter: “50 / 500 characters”
Validate before submit
“Thank you for your review!”
“Your review is pending approval” (if moderation enabled)
Badge or checkmark: “✓ Verified Purchase”
Position near reviewer name
Green color or checkmark icon
Only for confirmed customers
Builds trust (real customer, not fake)
Reduces suspicion of paid reviews
Higher credibility
“Was this review helpful?”
[👍 Yes (24)] [👎 No (2)]
Click to vote (one vote per user)
Powers “Most Helpful” sorting
Surfaces most useful reviews
Community validation
Reduces impact of unhelpful reviews
Customer-uploaded photos (3-4 max per review, 60-80px thumbnails, click to enlarge). Visual proof increases trust and engagement.
Seller replies below original review (indented, light gray background). Respond to negative reviews professionally - shows you care, addresses concerns without being defensive.
AggregateRating Schema (CRITICAL): Add structured data to show star ratings in search results. Include ratingValue (avg rating), reviewCount, bestRating (5), worstRating (1).
SEO benefits: Star ratings in search results, higher CTR, rich snippets. See seo.md for implementation details.
Important: Only include if reviews are real. Fake reviews violate Google guidelines.
Individual review card:
Star rating (16-20px) + text + reviewer name (first name + initial) + date + verified badge + helpful votes. Truncate long reviews (200-300 chars) with “Read more”.
Mobile:
Single column, touch-friendly votes (44px), full-screen sort select, filter bottom sheet, “Load more” pagination.
Not done: Star rating summary (average + count)Not done: Rating distribution bar chart (5 to 1 stars)Not done: Clickable bars to filter by ratingNot done: Sort dropdown (Most Recent, Most Helpful, Highest/Lowest)Not done: Filter options (verified, with photos, by rating)Not done: Individual reviews with: stars, text, name, dateNot done: Verified purchase badgeNot done: Helpful votes (upvote/downvote)Not done: Review submission form (rating, text)Not done: Form validation (minimum length, required rating)Not done: “Read more” for long reviewsNot done: Store responses to reviews (recommended)Not done: Review images (customer uploads, optional)Not done: Mobile: Touch targets 44px minimumNot done: Pagination or “Load more” buttonNot done: No reviews state (“Be the first to review”)Not done: AggregateRating structured data (SEO)Not done: ARIA labels for star ratingsNot done: Keyboard accessible (all interactions)