Skip to main content
Use Mercur to let customers rate the products they bought and the stores that sold them. A review is one customer’s rating of one target: a master product or a store. Each review is tied to the order that earned it, starts as pending, and waits for an operator to publish or reject it. The Review module ships inside @mercurjs/core, so it’s registered with the rest of the marketplace modules and needs no extra install. It connects to products, stores, orders, and customers through module links. Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998. Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998.
The panels call the target a store. The code calls the same record a Seller, so a store review has reference: "seller". Reviews use the id prefix rev and resolve with MercurModules.REVIEW.

​
Key features

The Review module covers a review from submission to the number on a storefront:
  • One model, two targets: a single Review record rates a product or a store, chosen by its reference field
  • Order-backed: the order must belong to the customer, and each order can review a given target once
  • Moderation: reviews start pending, and an operator sets them to published or rejected
  • Store responses: a store answers a review once through seller_note
  • Rating helpers: service methods compute average ratings per product or per store at query time
  • Compensation: every review workflow rolls its write back if a later step fails

​
How it works

A review moves through four stages:
  1. A customer calls POST /store/reviews with an order they own, which runs createReviewWorkflow
  2. The workflow validates the order, creates the review as pending, and links it to its customer, order, and target
  3. An operator publishes or rejects it with updateReviewWorkflow, and the store answers it with respondReviewWorkflow
  4. Your own storefront route reads published reviews and averages them with the service’s rating helpers
Core ships no public endpoint that lists a product’s or a store’s published reviews, and no route returns an average rating. GET /store/reviews returns only the signed-in customer’s own reviews. Add a route for storefront display, as shown in Compute aggregate ratings.

​
Get started

Learn how reviews, their targets, and their statuses fit together.

The review model

The fields of a review: rating, notes, status, and display id.

Product vs seller reviews

How reference picks the target and which links anchor each review.

Ratings & moderation

Status changes, store responses, and how averages are computed.

​
Examples

Build against reviews in your own server code.

Create a review

Run createReviewWorkflow from a custom route.

Moderate a review

Publish, reject, and delete reviews in code.

Respond to a review

Attach a store’s answer with respondReviewWorkflow.

Aggregate ratings

Serve average ratings for products and stores.

​
Resources

The data model, links, workflows, service methods, and events behind reviews.

Data models

The Review model, its fields, and its indexes.

Links

The four links to products, sellers, orders, and customers.

Workflows

Create, update, respond, and delete workflows with their steps.

Service

Generated methods and the rating helpers.

Events

The mutation events the module emits.