Reviews

Get product reviews

GET /access/api/v1/reviews/:productId

Public. Returns all approved reviews for a product. :productId is the product _id.

Query parameters: page, limit

Response:

{
  "status": "success",
  "data": [
    {
      "_id": "69e8c4a23ffcea9688dcf401",
      "rating": 5,
      "comment": "Great product, arrived on time.",
      "media": [],
      "date": "2026-04-10T09:22:11.000Z",
      "variationLabel": "6925a18b3ca2e25fa94c29dd-6925a18b3ca2e25fa94c29d5",
      "buyerName": "Ja** Do**"
    }
  ]
}

Buyer names are masked for privacy (first two characters visible, rest replaced with *). variationLabel is an empty string for non-variant products. media is an array of uploaded review images.

Possible errors: REVIEW_PRODUCT_NOT_FOUND

---

Get product review summary

GET /access/api/v1/reviews/:productId/summary

Public. Returns aggregate rating data for the star rating display on product pages.

Response:

{
  "status": "success",
  "data": {
    "average": 4.5,
    "count": 12,
    "hidden": 2
  }
}

average is rounded to one decimal place. count is the number of approved reviews. hidden is the count of reviews hidden by the merchant (useful to indicate moderation is active).

Possible errors: REVIEW_PRODUCT_NOT_FOUND

---

Get my review for an order

GET /access/api/v1/reviews/my

Requires customer JWT. Returns the reviews a customer has submitted for a specific order.

Query parameters:

Parameter	Required	Description
orderId	Yes	The order to fetch reviews for

Headers:

Authorization: Bearer <customer_token>

Response:

{
  "status": "success",
  "data": [
    {
      "_id": "69e8c4a23ffcea9688dcf401",
      "productId": "69bc36fda53000e2ede23dca",
      "rating": 5,
      "comment": "Great product.",
      "status": "approved",
      "date": "2026-04-10T09:22:11.000Z"
    }
  ]
}

Returns an empty array if no reviews exist for the order.

---

Add a review

POST /access/api/v1/reviews

Requires customer JWT. A customer can only review a product they have ordered, and only once per order.

Headers:

Authorization: Bearer <customer_token>

Request body:

{
  "orderId": "69e8b024e6e568525a008c6d",
  "productId": "69bc36fda53000e2ede23dca",
  "variationLabel": "",
  "rating": 5,
  "comment": "Great product, arrived on time."
}

Pass variationLabel as an empty string for products without variations. For variant products, pass the variation key ID as stored on the order (e.g. "6925a18b3ca2e25fa94c29dd-6925a18b3ca2e25fa94c29d5").

Response:

{
  "status": "success",
  "data": {
    "_id": "69e8c4a23ffcea9688dcf401",
    "productId": "69bc36fda53000e2ede23dca",
    "orderId": "69e8b024e6e568525a008c6d",
    "rating": 5,
    "comment": "Great product, arrived on time.",
    "variationLabel": "",
    "status": "pending",
    "date": "2026-04-10T09:22:11.000Z"
  }
}

Reviews start with status: "pending" until approved by the merchant.

Possible errors:

Code	Meaning
REVIEW_PRODUCT_NOT_FOUND	Product not found in the order
REVIEW_ORDER_NOT_FOUND	Order not found or not owned by user
REVIEW_ORDER_STATUS_INVALID	Order must be delivered, completed, cancelled, or refunded to review
REVIEW_ALREADY_EXISTS	Customer already submitted a review for this product in this order