Customer Reviews

TimberCloud includes a complete customer review system that allows customers to leave ratings and feedback on products and orders. This helps build trust, provides valuable feedback, and drives social proof for your products.

Overview

The review system provides:

• Product Reviews — Customers can rate and review products they've purchased
• Order Reviews — Feedback on the overall order experience
• Verified Purchase Badges — Authenticity indicators for genuine buyers
• Star Ratings — 1-5 star rating system with half-star display
• Moderation Workflow — Admin approval workflow for quality control
• Seller Responses — Reply to customer feedback directly
• Admin Dashboard — Dedicated review management interface

Features

Star Ratings

Customers rate their experience from 1 to 5 stars:

The system supports half-star display for average ratings (e.g., 4.5 stars).

Verified Purchase Badges

Reviews from customers who actually purchased the product display a "Verified Purchase" badge:

• System automatically checks order history when a review is submitted
• Badge displays on approved reviews in the storefront
• Helps customers identify authentic feedback from real buyers
• Verified status is set server-side and cannot be manipulated

Rating Statistics

Product pages display comprehensive rating information:

• Average Rating — Overall star average (rounded to one decimal)
• Total Reviews — Number of approved reviews
• Rating Breakdown — Visual distribution chart showing how many 5-star, 4-star, etc.

Customer Experience

Writing a Product Review

Customers can leave reviews on product pages:

1. Navigate to the product page
2. Scroll to the "Customer Reviews" section
3. Click "Write a Review"
4. Select star rating (1-5, required)
5. Add optional review title (max 200 characters)
6. Write review comment (minimum 10 characters, required)
7. Submit for moderation

The form validates:

• Rating is required
• Comment must be at least 10 characters
• One review per product per customer

Writing an Order Review

Customers can review products from their order detail page:

1. Navigate to the order detail page
2. Reviews section appears after order is delivered
3. Select which product from the order to review
4. Complete the review form
5. Submit for moderation

Note: Reviews are only available after the order status is "Delivered" or the order has a completion/delivery date.

Guest Reviews

Customers without accounts can also leave reviews by providing:

• Name (required)
• Email (required, not displayed publicly)

Guest reviews:

• Are associated with the company but not linked to a customer profile
• Can still receive verified purchase badges if email matches an order
• Go through the same moderation process

Duplicate Prevention

The system prevents duplicate reviews:

• Authenticated users: One review per product/order per customer
• Guest users: One review per product/order per email address
• If a customer has already reviewed an item, their existing review is displayed instead of the form

Review Eligibility

The system checks if customers can leave reviews:

Moderation Workflow

All reviews go through a moderation process to ensure quality.

Review Statuses

Moderation Process

1. Customer submits review → Status: Pending
2. Admin notification sent (email + in-app)
3. Admin reviews in the Reviews dashboard
4. Admin approves or rejects the review
5. Only Approved reviews are visible on the storefront

Admin Reviews Dashboard

Access the reviews dashboard at Reviews in the main navigation.

Features:

• Stats Overview — Pending, Approved, Rejected counts with average rating
• Filter by Status — View all, pending, approved, or rejected reviews
• Quick Actions — Approve or reject directly from the table
• Detail Modal — View full review with customer and product/order info
• Pagination — 20 reviews per page

Moderation Guidelines

Consider rejecting reviews that:

• Contain inappropriate language or profanity
• Are spam or promotional content
• Include personal information (phone numbers, addresses)
• Are not genuine customer experiences
• Violate your terms of service
• Are off-topic or irrelevant to the product

Seller Responses

Respond to customer reviews to show engagement and address feedback.

Adding a Response

1. Go to Reviews in the admin dashboard
2. Click on a review to open the detail modal
3. Type your response in the "Response" field
4. Save the review
5. Response appears below the customer review on the storefront

Response Best Practices

Tips:

• Respond within a few days
• Keep responses professional and friendly
• Never argue with customers publicly
• Offer solutions when appropriate
• Follow up after resolving issues

Display Components

Product Page Review Section

The full review section on product pages includes:

• Average rating with large visual display
• Rating breakdown bar chart (5-star to 1-star distribution)
• "Write a Review" button with eligibility check
• Paginated list of approved reviews (5 per page)
• "See all reviews" link for navigation

Order Page Review Section

On order detail pages:

• Appears after order is delivered
• Shows buttons for each product to review
• Displays existing reviews for the order
• Shows seller responses inline

Compact Review Blurbs

For product cards and listings:

• Average star rating display
• Review count
• "See All Reviews" link to full section

Review Cards

Individual reviews display:

• Reviewer name (or "Anonymous")
• Avatar with first initial
• Verified purchase badge (if applicable)
• Star rating
• Review title (if provided)
• Review comment with "Read more" for long text
• Relative timestamp (e.g., "3 days ago")
• Seller response (if any) in a styled callout

Admin Notifications

When a new review is submitted:

1. In-App Notification — Appears in the notification bell
2. Email Notification — Sent to admin users (if configured)

Notifications include:

• Customer name
• Product or order reviewed
• Star rating
• Review preview
• Link to review in dashboard

API Reference

Public Endpoints

These endpoints are accessible without authentication:

// Get approved reviews for a product
GET /api/reviews/product/:productId
// Query params: page, pageSize
// Header: company (required)
 
// Get product review statistics
GET /api/reviews/product/:productId/stats
// Header: company (required)
 
// Check if user can review (requires JWT for full check)
GET /api/reviews/can-review?productId=123
// or
GET /api/reviews/can-review?orderId=456
// Header: company (required)

Authenticated Endpoints

These endpoints require JWT authentication:

// Submit a new review
POST /api/reviews
{
  "data": {
    "rating": 5,              // Required: 1-5
    "comment": "Great!",      // Required: min 10 chars
    "title": "Love it",       // Optional: max 200 chars
    "product": 123,           // Required if no order
    "order": 456,             // Required if no product
    "company": 789,           // Required
    "reviewer_name": "John",  // For guest reviews
    "reviewer_email": "j@ex.com" // For guest reviews
  }
}
 
// Get company review stats (admin)
GET /api/reviews/company/stats
// Header: company (required)
 
// Standard CRUD operations
GET /api/reviews          // List reviews (admin)
GET /api/reviews/:id      // Get single review
PUT /api/reviews/:id      // Update review (admin)
DELETE /api/reviews/:id   // Delete review (admin)

Response Formats

Product Reviews Response:

{
  "data": [
    {
      "id": 1,
      "rating": 5,
      "title": "Amazing quality",
      "comment": "Best purchase I've made...",
      "verified_purchase": true,
      "reviewer_name": "John D.",
      "response": "Thank you for your review!",
      "response_at": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-10T08:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 25,
      "pageCount": 3
    },
    "averageRating": 4.6,
    "totalReviews": 25
  }
}

Product Stats Response:

{
  "data": {
    "averageRating": 4.6,
    "totalReviews": 25,
    "distribution": {
      "5": 15,
      "4": 6,
      "3": 2,
      "2": 1,
      "1": 1
    }
  }
}

Can Review Response:

// Can review
{ "data": { "canReview": true } }
 
// Cannot review
{
  "data": {
    "canReview": false,
    "reason": "already_reviewed",
    "existingReview": {
      "id": 123,
      "rating": 5,
      "createdAt": "2024-01-10T08:00:00Z"
    }
  }
}

Data Model

Review Fields

Relations

Best Practices

Encouraging Reviews

• Send follow-up emails after order delivery
• Include review links in shipping confirmation emails
• Add review prompts to the order status page
• Thank customers who leave reviews
• Make the review process quick and easy

Responding to Negative Reviews

1. Acknowledge — "We're sorry to hear about your experience"
2. Apologize — Even if you disagree, apologize for their frustration
3. Explain — Briefly explain what may have happened (if known)
4. Offer Resolution — Provide a way to make it right
5. Take Offline — "Please contact us at support@..."
6. Follow Up — Check back after resolving the issue

Using Reviews for Improvement

• Monitor rating trends over time
• Identify common issues or complaints
• Track which products get the best/worst reviews
• Use feedback to improve products and service
• Share positive reviews with your team

Analytics

Track review performance in your dashboard:

Troubleshooting

Customer Can't Leave Review

Check:

• Order status is "Delivered" or completed
• Customer hasn't already reviewed the item
• Customer is logged in (for verified reviews)
• Product is linked to their order

Review Not Showing on Storefront

Check:

• Review status is "Approved"
• Moderation workflow was completed
• Clear any caching if using CDN

Verified Badge Not Appearing

Check:

• Customer actually purchased the product
• Order is linked to their customer profile
• Order contains the product being reviewed

Reviews Not Loading

Check:

• Company ID header is being sent
• Product ID is correct
• API endpoint is accessible
• Check browser console for errors

Security

The review system includes multiple security measures:

• Tenant Isolation — Reviews are scoped to companies; cross-tenant access is blocked
• Server-Side Verification — Verified purchase status is determined server-side
• Duplicate Prevention — One review per customer per product/order
• Input Validation — Rating, comment length, and field validation
• Ownership Verification — Admin actions validate company ownership
• Sanitized Output — Customer data is sanitized before public display