Review Module
In this section of the documentation, you will find resources to learn more about the Review Module and how to use it in your application. Mercur has product and seller review features available out-of-the-box through the Review Module. A module is a standalone package that provides features for a single domain. Each of Mercur’s marketplace features are placed in custom modules, such as this Review Module. Learn more about why modules are isolated in this documentation.Review Features
- Dual Review Types: Support reviews for both products and sellers using a single unified system.
- Rating System: 1-5 star rating system for quantitative feedback.
- Customer Notes: Allow customers to write detailed review comments.
- Seller Responses: Enable sellers to respond to reviews about their products or service.
- Order Verification: Link reviews to orders to ensure only verified purchasers can review.
- Review Removal Requests: Allow sellers to request removal of unfair reviews through the request system.
How to Use the Review Module
In your Medusa application, you build flows around Commerce Modules. A flow is built as a Workflow, which is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism. You can build custom workflows and steps. Mercur provides pre-built workflows for review operations in the@mercurjs/reviews package.
For example, the createReviewWorkflow:
src/workflows/review/create-review.ts
API Route
src/api/store/reviews/route.ts
Concepts
In this document, you’ll learn about the main concepts related to reviews in Mercur.Review
A review represents customer feedback about a product or seller. It is represented by the Review data model. A review holds information about:- Reference type (product or seller)
- Rating value (1-5)
- Customer note (written review comment)
- Customer ID (who wrote the review)
- Seller note (seller’s response to the review)
- Created and updated timestamps
Dual Reference System
The Review Module uses a single data model to handle two types of reviews:Product Reviews
Reference:productReference ID: Product ID
Purpose: Rate and review specific products Customers can review:
- Product quality
- Accuracy of description
- Value for money
- Overall satisfaction
Seller Reviews
Reference:sellerReference ID: Seller ID
Purpose: Rate and review seller service Customers can review:
- Shipping speed
- Communication quality
- Packaging quality
- Overall seller experience
Rating System
Reviews use a 1-5 star rating system:- 5 stars: Excellent
- 4 stars: Good
- 3 stars: Average
- 2 stars: Below Average
- 1 star: Poor
rating field stores the numeric value (1-5). Marketplaces can calculate:
- Average ratings per product/seller
- Rating distributions (e.g., “80% 5-star reviews”)
- Trending ratings over time
Customer Notes
Thecustomer_note field allows customers to write detailed review comments (up to 300 characters in typical implementations).
This provides qualitative feedback beyond the numeric rating:
- Specific product details
- Use case descriptions
- Pros and cons
- Recommendations
Seller Responses
Theseller_note field allows sellers to respond to reviews:
Use Cases:
- Thank customers for positive reviews
- Address concerns in negative reviews
- Provide additional product information
- Offer solutions to problems
- Customer service quality
- Responsiveness
- Professionalism
- Commitment to customer satisfaction
Order Verification
Reviews are linked to orders through module links, ensuring:- Only verified purchasers can review
- Customers can only review products/sellers they’ve bought from
- One review per customer per product/seller per order
- Review authenticity is guaranteed
Review Removal System
Sellers can request review removal through the Request Module when they believe a review:- Violates marketplace policies
- Contains inappropriate content
- Is fraudulent or fake
- Is unfair or inaccurate
- Seller creates
review_removerequest with review ID and reason - Admin reviews the request and both the original review
- If approved:
RemoveReviewRequestUpdatedEvent.REMOVEDis emitted - Subscriber triggers
deleteReviewWorkflow - Review is deleted from the system
Search Engine Integration
When reviews are created or updated, the workflow emitsAlgoliaEvents.REVIEW_CHANGED:
- Product reindexing with updated average rating
- Seller profile reindexing with updated rating
- Search results updated with current ratings