Skip to main content
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

productId
string
required
The product ID to review
orderId
string
required
The order ID that contains this product
rating
number
required
Rating from 1 to 5 stars
comment
string
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

message
string
Success message
review
object
The created or updated review object
review._id
string
Review unique identifier
review.productId
string
Product ID reference
review.userId
string
User ID reference
review.orderId
string
Order ID reference
review.rating
number
Rating from 1 to 5
review.comment
string
Review comment (may be empty)
review.createdAt
string
ISO 8601 timestamp of creation
review.updatedAt
string
ISO 8601 timestamp of last update

Example Request

curl -X POST https://api.donpalitojr.com/api/reviews \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "65f8a1b2c3d4e5f6g7h8i9j3",
    "orderId": "65f8a1b2c3d4e5f6g7h8i9j0",
    "rating": 5,
    "comment": "Deliciosas empanadas, muy recomendadas!"
  }'

Example Response

{
  "message": "Review submitted successfully",
  "review": {
    "_id": "65f8a1b2c3d4e5f6g7h8i9j5",
    "productId": "65f8a1b2c3d4e5f6g7h8i9j3",
    "userId": "65f8a1b2c3d4e5f6g7h8i9j1",
    "orderId": "65f8a1b2c3d4e5f6g7h8i9j0",
    "rating": 5,
    "comment": "Deliciosas empanadas, muy recomendadas!",
    "createdAt": "2024-03-17T15:30:00.000Z",
    "updatedAt": "2024-03-17T15:30:00.000Z"
  }
}

Error Responses

400 Bad Request
Invalid rating, product not in order, or order not delivered
{
  "error": "Rating must be between 1 and 5"
}
{
  "error": "Product not found in this order"
}
{
  "error": "Can only review delivered orders"
}
403 Forbidden
User is not authorized to review this order
{
  "error": "Not authorized to review this order"
}
404 Not Found
Order or product not found
{
  "error": "Order not found"
}
{
  "error": "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.
This endpoint is implemented in the backend but not used in the mobile app frontend.

Authentication

Required. User must be authenticated via Clerk and must own the review.

Path Parameters

reviewId
string
required
The review ID to delete

Response

message
string
Success message

Example Request

curl -X DELETE https://api.donpalitojr.com/api/reviews/65f8a1b2c3d4e5f6g7h8i9j5 \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Example Response

{
  "message": "Review deleted successfully"
}

Error Responses

403 Forbidden
User is not authorized to delete this review
{
  "error": "Not authorized to delete this review"
}
404 Not Found
Review not found
{
  "error": "Review not found"
}

Review Schema

Reviews are stored with the following structure:
{
  productId: ObjectId,      // Reference to Product
  userId: ObjectId,         // Reference to User
  orderId: ObjectId,        // Reference to Order
  rating: Number,           // 1-5 stars, required
  comment: String,          // Optional, max 500 chars
  createdAt: Date,          // Auto-generated
  updatedAt: Date           // Auto-generated
}

Unique Constraint

The combination of productId, 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:
  1. All reviews for the product are fetched
  2. Total rating is calculated by summing all ratings
  3. Product’s averageRating is updated: totalRating / numberOfReviews
  4. Product’s totalReviews is updated: numberOfReviews

Review Workflow

1

Customer Places Order

Order is created with status “pending”
2

Order is Delivered

Admin updates order status to “delivered”
3

Customer Can Review

Customer can now submit a review for products in the delivered order
4

Product Rating Updated

Product’s average rating and total reviews are recalculated automatically

Build docs developers (and LLMs) love