Skip to main content

​
Get Product Reviews

Retrieves customer reviews for a specific product with cursor-based pagination.

​
Path Parameters

​
productId
string (uuid)
required
Product identifier

​
Query Parameters

​
pageSize
integer
default:"10"
Number of reviews per page (default: 10)
​
lastId
string (uuid)
ID of the last review from previous page (for cursor pagination)

​
Response

​
items
array
Array of review objects
​
hasMore
boolean
Whether more reviews are available
​
lastId
string (uuid)
ID of the last review in this page (use for next request)

​
Response Codes

  • 200 OK - Reviews retrieved successfully
  • 404 Not Found - Product not found

​
Examples

# First page
curl -X GET "https://your-server.com/api/products/3fa85f64-5717-4562-b3fc-2c963f66afa6/reviews?pageSize=10"

# Subsequent pages
curl -X GET "https://your-server.com/api/products/3fa85f64-5717-4562-b3fc-2c963f66afa6/reviews?pageSize=10&lastId=last-review-id"

​
Success Response Example

{
  "items": [
    {
      "id": "review-1",
      "customerId": "customer-uuid",
      "customerName": "John Doe",
      "rating": 5,
      "comment": "Excellent product! Highly recommended.",
      "createdAt": "2024-01-15T10:30:00Z",
      "verifiedPurchase": true
    },
    {
      "id": "review-2",
      "customerId": "customer-uuid-2",
      "customerName": "Jane Smith",
      "rating": 4,
      "comment": "Good quality, fast shipping.",
      "createdAt": "2024-01-14T15:20:00Z",
      "verifiedPurchase": true
    }
  ],
  "hasMore": true,
  "lastId": "review-2"
}

​
Add Product Review (Customer)

Submits a new review for a product. Customers can only review products they have purchased.

​
Path Parameters

​
productId
string (uuid)
required
Product identifier

​
Request Body

​
customerId
string (uuid)
required
Customer identifier (must match authenticated user)
​
rating
integer
required
Rating from 1 to 5 stars
​
comment
string
required
Review text/comment (minimum length may apply)

​
Response Codes

  • 204 No Content - Review added successfully
  • 400 Bad Request - Invalid rating or comment, or customer hasn’t purchased product
  • 404 Not Found - Product or customer not found

​
Examples

curl -X POST "https://your-server.com/api/products/3fa85f64-5717-4562-b3fc-2c963f66afa6/reviews" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer-uuid",
    "rating": 5,
    "comment": "Amazing product! Exceeded my expectations. The quality is top-notch and delivery was fast."
  }'

​
Error Response Examples

Invalid Rating (400 Bad Request): 
"Rating must be between 1 and 5"
Not Purchased (400 Bad Request): 
"You can only review products you have purchased"
Product Not Found (404 Not Found): 
"Product not found"
Duplicate Review (400 Bad Request): 
"You have already reviewed this product"

​
Review Guidelines

​
Rating System

  • 5 Stars - Excellent, highly recommended
  • 4 Stars - Very good, minor issues
  • 3 Stars - Good, meets expectations
  • 2 Stars - Below expectations
  • 1 Star - Poor quality or experience

​
Review Requirements

Only customers who have purchased the product can submit reviews. This ensures authentic feedback from verified buyers.
Reviews should be honest and follow community guidelines. Inappropriate content may be removed by administrators.

​
Best Practices

  1. Be Specific - Mention specific features or aspects of the product
  2. Be Honest - Share both positives and negatives
  3. Be Helpful - Help other customers make informed decisions
  4. Be Respectful - Avoid offensive language or personal attacks

​
Review Policies

  • Customers can only submit one review per product
  • Reviews cannot be edited after submission (contact support for changes)
  • Verified purchase badge indicates the reviewer bought the product
  • Reviews may be moderated for quality and appropriateness

​
Review Metrics

Product ratings are calculated as:
  • Average Rating - Mean of all review ratings
  • Review Count - Total number of reviews
  • Rating Distribution - Breakdown by star rating (1-5)
These metrics appear on product detail pages to help customers make informed decisions.

Build docs developers (and LLMs) love

Get started for freeTalk to us