Overview
The Review entity captures customer feedback and ratings for products. It supports verified purchase validation, content moderation, community voting, and merchant responses to build trust and provide valuable product insights.
Entity Properties
| Name | Type | Required | Description |
|---|---|---|---|
reviewId | UUID | Required | Unique identifier for the review |
productId | UUID | Required | Product being reviewed |
customerId | UUID | Required | Customer who wrote the review |
orderId | UUID | Optional | Order associated with this review (for verified purchases) |
rating | integer | Required | Rating given by customer (1-5 stars) |
title | string | Optional | Review title or headline |
content | string | Required | Review content and comments |
isVerifiedPurchase | boolean | Required | Whether this review is from a verified purchase |
isRecommended | boolean | Optional | Whether customer recommends this product |
helpfulVotes | integer | Required | Number of helpful votes received |
totalVotes | integer | Required | Total number of votes received |
status | string | Required | Current review status |
moderationNotes | string | Optional | Internal moderation notes |
images | array | Optional | URLs of images uploaded with the review |
pros | array | Optional | List of positive aspects mentioned |
cons | array | Optional | List of negative aspects mentioned |
merchantResponse | object | Optional | Response from merchant to this review |
createdAt | DateTime | Required | Date and time when the review was created |
updatedAt | DateTime | Optional | Date and time when the review was last updated |
moderatedAt | DateTime | Optional | Date and time when the review was moderated |
Relationships
- Product: Each review belongs to one
Product(identified byproductId). - Customer: Each review is written by one
Customer(identified bycustomerId). - Order: Each review can be linked to one
Orderfor purchase verification (identified byorderId).
Review Lifecycle
submitted → pending → approved → published
↓ ↓
rejected flagged
Examples
- Review #1: 5-star review for iPhone 15 Pro, verified purchase, “Excellent camera quality!”
- Review #2: 3-star review for Running Shoes, helpful votes: 15/20, includes photos
- Review #3: 1-star review flagged for inappropriate content, pending moderation
Business Rules
- Reviews can only be submitted by customers who purchased the product
- Rating must be between 1-5 stars
- Verified purchase reviews are given higher weight in calculations
- Inappropriate content is flagged and requires moderation
- Customers can only review the same product once per purchase
- Helpful votes help surface most valuable reviews
- Merchant responses are limited to one per review
- Reviews older than 2 years may have reduced weight in calculations