Product Reviews

Scope

This page documents the existing order-linked product review flow. The testimonial addition does not change this behavior. Customer-submitted reviews still follow this lifecycle, while admin-seeded fake reviews are an additional entry path into the same public product-review stream.

Lifecycle

1. customer authenticates in mobile app / storefront
2. customer submits review with:
   • orderId
   • productId
   • rating
   • optional comment
3. backend verifies:
   • product exists
   • order exists
   • order belongs to customer
   • product is present in order
   • order is eligible for review
   • duplicate review does not already exist
4. review is inserted as pending
5. admin reviews and sets approved or rejected
6. approved reviews become visible through public product review endpoints

Public Read Surfaces

• GET /api/products/:slug/reviews
• GET /api/products/id/:productId/reviews
• GET /api/mobile/products/id/:productId/reviews

These endpoints expose only approved reviews.

Admin Moderation Surface

• GET /api/admin/reviews
• GET /api/admin/reviews/:id
• PATCH /api/admin/reviews/:id/status

Admin filters currently include:

• status
• productId
• orderId
• customerId
• search

Important Invariants

• product reviews remain bound to real order history
• admin-seeded product reviews are separate from testimonial endpoints
• testimonial endpoints do not replace or bypass customer purchase validation
• moderation state remains required before public display
• public product review endpoints do not mix in testimonials
• public product review endpoints can include both approved customer reviews and approved admin-seeded product reviews