Skip to main content
A review is one customer’s rating of one product or one store, earned by an order. Mercur stores it as a single Review record (table review, id prefix rev) in the Review module. Knowing its fields tells you what a review can hold, what a store can add to it, and what an operator changes when moderating it.

​
One record per rating

Every review has the same shape, whatever it rates. The record holds the score and the text around it, while the product, store, order, and customer it belongs to live in module links rather than columns. A review has no product_id or seller_id column. The reference value tells you which link to follow, as covered in Product vs seller reviews.

​
Ratings are integers from 1 to 5 at the API

The rating column is an integer with no range check in the model itself. The Store and Admin API validators accept whole numbers from 1 to 5, so every review created over HTTP falls in that range:
  • Store API: rating is required on create and update, and must be an integer from 1 to 5
  • Admin API: rating is optional on update, with the same 1 to 5 range
  • Workflows: createReviewWorkflow and updateReviewWorkflow store whatever number you pass
When you run the workflows from your own code, validate rating yourself. A value outside 1 to 5 is stored as is and skews every average that includes it.

​
Two notes, two authors

A review keeps the two sides of the conversation in separate fields. The customer writes customer_note when they submit or edit the review, and the store writes seller_note once, through respondReviewWorkflow. Both are nullable text fields marked searchable, so a q search in the Admin and Vendor APIs matches their content.
This is the shape query.graph returns for a review’s own fields. The Store API caps customer_note at 300 characters, the Admin API at 1000, and both APIs cap seller_note at 300.

​
Status starts at pending

Every new review gets status: "pending", the model default. An operator then sets it to published or rejected with updateReviewWorkflow. Nothing in core hides a pending review from a storefront for you, since core has no public review listing: your own route decides which statuses to show. See Ratings and moderation for the full set of changes.