Review endpoints require authentication. Customers can only review products from their delivered orders.
Create Review
Create or update a product review for a delivered order. Reviews automatically update the product’s average rating and total review count.Authentication
Required. User must be authenticated via Clerk.Request Body
The product ID to review
The order ID that contains this product
Rating from 1 to 5 stars
Optional review comment (max 500 characters)
Validation Rules
- Order must exist and belong to the authenticated user
- Order status must be “delivered”
- Product must be in the order
- Rating must be between 1 and 5
- If a review already exists for this product/order/user combination, it will be updated (upsert)
Response
Success message
The created or updated review object
Review unique identifier
Product ID reference
User ID reference
Order ID reference
Rating from 1 to 5
Review comment (may be empty)
ISO 8601 timestamp of creation
ISO 8601 timestamp of last update
Example Request
Example Response
Error Responses
400 Bad Request
Invalid rating, product not in order, or order not delivered
403 Forbidden
User is not authorized to review this order
404 Not Found
Order or product not found
Delete Review
Delete a review. Only the user who created the review can delete it. The product’s average rating and total review count are automatically recalculated.Authentication
Required. User must be authenticated via Clerk and must own the review.Path Parameters
The review ID to delete
Response
Success message
Example Request
Example Response
Error Responses
403 Forbidden
User is not authorized to delete this review
404 Not Found
Review not found
Review Schema
Reviews are stored with the following structure:Unique Constraint
The combination ofproductId, userId, and orderId ensures a user can only have one review per product per order. Using upsert (findOneAndUpdate with upsert: true) allows updating existing reviews.
Product Rating Calculation
When a review is created or deleted:- All reviews for the product are fetched
- Total rating is calculated by summing all ratings
- Product’s
averageRatingis updated:totalRating / numberOfReviews - Product’s
totalReviewsis updated:numberOfReviews