Product Reviews Block

Overview

A container block that displays approved product reviews synced from BigCommerce. Shows aggregate star ratings, individual customer reviews, and includes child blocks for review submission and pagination. This block automatically reads the product ID from its parent Single Product template context.

Requirements

• Parent block: Must be inside a Single Product template to access product context
• BigCommerce data: Approved product reviews, aggregate ratings
• Related feature: Product Reviews feature must be enabled in BigCommerce

Configuration

Attributes

• Product Context - Automatically reads product ID from parent template (no manual configuration needed)
• Display Settings - Sort order, reviews per page (configurable in settings panel)
• Pagination - Controlled by child “Load More Reviews” block

Block Support

• HTML editing: Not supported
• Alignment: Full width supported
• Nested blocks: Contains child blocks (Write a Review, Load More Reviews)

Usage

Placement

The Product Reviews block is typically placed in the Single Product template, below product details:

[Single Product Template]
  Product Images
  Product Title
  Product Pricing
  Product Description
  Product Buy Button
  → Product Reviews ← (container block)
    - Write a Review (child block)
    - Load More Reviews (child block)

How It Works

The Product Reviews block:

1. Reads product context - Gets product ID from parent Single Product template
2. Fetches approved reviews - Queries BigCommerce API for reviews with “Approved” status
3. Displays aggregate rating - Shows overall star rating and total review count (e.g., “4.6 ★★★★★ (26 reviews)”)
4. Lists individual reviews - Displays each review with author, date, rating, title, and text
5. Handles pagination - Shows “Load More Reviews” button if multiple pages exist

Data source: All review data is stored in BigCommerce and synced to WordPress® as read-only. Customers submit reviews via the Write a Review block, which sends data to BigCommerce for moderation.

Settings Panel

When selected in the Site Editor, the Product Reviews block shows:

General Tab:

• Sort Order - Default: “Newest first” (dropdown with options)
• Reviews Per Page - How many reviews to display before pagination (default: 10)
• Show Aggregate Rating - Toggle overall star rating display (default: on)
• Show Review Count - Toggle total review count (default: on)

Style Tab:

• Review Card Spacing - Gap between individual reviews (small/medium/large)
• Typography - Font size and style for review text
• Colors - Star color, review card background

Child Blocks

Write a Review Block

Purpose: Form for customers to submit new product reviews

Key features:

• Requires customer authentication (sign-in)
• Automatically reads product ID from parent context
• Submits reviews to BigCommerce as “Pending” status
• Shows “Please sign in to write a review” message for unauthenticated users

Form fields:

• Star rating selector (1-5 stars, required)
• Review title (text input, required)
• Review text (textarea, required)
• Author name (auto-filled from customer account)

Behavior:

1. Customer selects star rating
2. Customer enters title and review text
3. Customer clicks “Submit Review” button
4. Review sent to BigCommerce with “Pending” status
5. Confirmation message shown to customer
6. Review awaits admin approval in BigCommerce moderation queue

See Product Reviews feature documentation for submission workflow details.

Load More Reviews Block

Purpose: Pagination button to fetch additional reviews

Key features:

• Only visible when product has multiple pages of reviews
• Fetches next page of reviews via AJAX (no page reload)
• Updates review list dynamically when clicked
• Hides automatically when all reviews are displayed

Configuration:

• Reviews per page controlled by parent Product Reviews block settings
• Button text customizable in block settings (default: “Load more reviews”)
• Can be styled via CSS to match site theme

Data Flow

Parent Context Relationship

The Product Reviews block relies on parent context to know which product’s reviews to display:

Single Product Template (provides product ID context)
  ↓
Product Reviews Block (reads product ID from context)
  ↓
Queries BigCommerce API (fetch reviews for this product ID)
  ↓
Displays approved reviews

What this means:

• Block automatically knows which product it’s displaying reviews for
• No manual configuration of product ID needed
• Block won’t work outside a Single Product template context
• Product ID can also be passed via URI parameter (for custom implementations)

Review Sync Behavior

Reviews sync from BigCommerce to WordPress®:

What syncs:

• Review title, text, rating (1-5 stars)
• Author name, submission date
• Approval status (Approved/Pending/Disapproved)

What doesn’t sync:

• Pending reviews (awaiting moderation)
• Disapproved reviews (hidden by admin)
• Deleted reviews

Sync timing:

• Status changes (Approved → Disapproved) sync during regular product sync cycle
• Reviews sync from BigCommerce typically 5-15 minutes after approval
• Webhook-triggered sync ensures near real-time updates

See Product Reviews feature documentation for detailed sync behavior.

Examples

Example 1: Default Product Reviews Configuration

Settings:

• Sort: Newest first
• Reviews per page: 10
• Show aggregate rating: Yes
• Show review count: Yes
• Pagination: Load More button

Result:

★★★★★ 4.6 (26 reviews)

Sort by: [Newest first ▼]

┌─────────────────────────────────────┐
│ ★★★★★ John Smith - May 15, 2026    │
│ "Excellent product"                 │
│ Works perfectly, exactly as          │
│ described. Highly recommend!        │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ ★★★★☆ Jane Doe - May 12, 2026      │
│ "Good but could be better"          │
│ Quality is good, but shipping took  │
│ longer than expected.               │
└─────────────────────────────────────┘

[... 8 more reviews ...]

[Load more reviews]

─────────────────────────────────────

Write a Review
Please sign in to write a review
[Sign In]

Example 2: Customized Review Display

Settings:

• Sort: Highest rating first
• Reviews per page: 5
• Show aggregate rating: Yes
• Review card spacing: Large
• Custom star color: Brand purple

Result: High-rated reviews appear first, larger gaps between review cards, purple stars matching brand color scheme. Pagination appears sooner (after 5 reviews instead of 10).

Example 3: Authenticated User View

When customer is signed in, the Write a Review block shows the full form:

Write a Review

Rating: ☆☆☆☆☆ (select stars)

Review Title:
┌─────────────────────────────────────┐
│                                     │
└─────────────────────────────────────┘

Your Review:
┌─────────────────────────────────────┐
│                                     │
│                                     │
│                                     │
└─────────────────────────────────────┘

[Submit Review]

After submission, customer sees confirmation message and review enters BigCommerce moderation queue as “Pending” status.

Customization

Via Block Settings

1. Select Product Reviews block in Site Editor
2. Open Settings panel (right sidebar)
3. Adjust sort order, reviews per page, display options
4. Style in Style tab (spacing, colors, typography)

Via Custom CSS

/* Customize aggregate rating display */
.wp-block-commerce-connect-product-reviews .aggregate-rating {
  font-size: 24px;
  font-weight: 700;
  color: #1f2937;
}

/* Customize star color */
.wp-block-commerce-connect-product-reviews .star-filled {
  color: #8b5cf6; /* Brand purple */
}

/* Style individual review cards */
.wp-block-commerce-connect-product-reviews .review-card {
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  padding: 20px;
  margin-bottom: 16px;
  background: #ffffff;
}

/* Hover effect on review cards */
.wp-block-commerce-connect-product-reviews .review-card:hover {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
}

/* Customize review author name */
.wp-block-commerce-connect-product-reviews .review-author {
  font-weight: 600;
  color: #374151;
}

/* Customize review date */
.wp-block-commerce-connect-product-reviews .review-date {
  font-size: 14px;
  color: #6b7280;
}

/* Style "Load More" button */
.wp-block-commerce-connect-product-reviews .load-more-button {
  background: #8b5cf6;
  color: white;
  border: none;
  border-radius: 6px;
  padding: 12px 24px;
  font-weight: 600;
  cursor: pointer;
}

.wp-block-commerce-connect-product-reviews .load-more-button:hover {
  background: #7c3aed;
}

Via Hooks/Filters

// Customize reviews per page globally
add_filter('commerce_connect_reviews_per_page', function($per_page) {
  return 15; // Override default to 15 reviews per page
});

// Customize review sort order
add_filter('commerce_connect_reviews_sort_order', function($order) {
  return 'highest_rating'; // Default to highest rating first
});

// Customize review display HTML
add_filter('commerce_connect_review_card_html', function($html, $review_data) {
  // Add verified purchaser badge
  if ($review_data['verified_purchaser']) {
    $html = '<span class="badge verified">Verified Purchase</span>' . $html;
  }
  return $html;
}, 10, 2);

// Filter which reviews display (e.g., hide reviews below 3 stars)
add_filter('commerce_connect_reviews_query', function($reviews) {
  return array_filter($reviews, function($review) {
    return $review['rating'] >= 3;
  });
});

Accessibility

• ARIA labels: Review list has role="list", cards have role="listitem"
• Keyboard navigation:
  • Tab navigates through review cards and submit form
  • Enter/Space activates “Load More” button
  • Star rating selector is keyboard-accessible (arrow keys to select stars)
• Screen reader support:
  • Aggregate rating announced (“4.6 out of 5 stars, based on 26 reviews”)
  • Individual ratings announced for each review (“5 out of 5 stars”)
  • Review submission confirmation announced
  • “Load More” button announces review count (“Load 10 more reviews”)
• Focus management: Focus returns to review list after “Load More” click

Troubleshooting

Reviews not appearing on WordPress®

Symptoms: Product page shows “No reviews yet” despite reviews existing in BigCommerce

Cause: Reviews are Pending/Disapproved, or sync hasn’t completed

Solution:

1. Verify reviews are “Approved” in BigCommerce → Products → Reviews
2. Wait for sync cycle (typically 5-15 minutes after approval)
3. Trigger manual sync: Settings → Commerce Connect → Sync Products Now
4. Clear WordPress® cache if using caching plugin
5. Verify Product Reviews block is in Single Product template

Write a Review block not showing

Symptoms: Review submission form doesn’t appear on product page

Cause: Block not in template, or product reviews not enabled in BigCommerce

Solution:

1. Check BigCommerce → Settings → Comments → “Product reviews” is checked
2. Verify Write a Review child block exists inside Product Reviews block
3. Edit Single Product template in Site Editor and confirm block placement
4. Clear browser cache and reload page

”Please sign in to write a review” shows for signed-in users

Symptoms: Authenticated customers still see sign-in prompt instead of review form

Cause: Customer session not recognized, or authentication token expired

Solution:

1. Have customer sign out and sign back in
2. Clear browser cookies and cache
3. Verify Account Login block is working correctly
4. Check browser console for authentication errors
5. Test with different browser to rule out browser-specific issue

Aggregate rating doesn’t match BigCommerce

Symptoms: Star rating on WordPress® differs from BigCommerce admin

Cause: WordPress® shows only approved reviews; BigCommerce shows all reviews

Solution:

1. Compare count of approved reviews in BigCommerce to reviews showing on WordPress®
2. Verify pending/disapproved reviews exist in BigCommerce (these don’t sync)
3. Wait for sync cycle after approving/disapproving reviews
4. Aggregate rating updates automatically when sync completes

Load More button not working

Symptoms: Clicking “Load More Reviews” doesn’t fetch additional reviews

Cause: JavaScript error, AJAX conflict, or no additional reviews to load

Solution:

1. Check browser console for JavaScript errors
2. Verify product has more reviews than current page shows
3. Test with browser dev tools network tab (verify AJAX request succeeds)
4. Clear browser cache and reload
5. Check for plugin conflicts (deactivate other plugins temporarily)

CSS Hooks

Selector	Purpose
.wp-block-commerce-connect-product-reviews	Root container
.product-reviews__aggregate	Aggregate rating area
.product-reviews__sort	Sort dropdown control
.product-reviews__list	Review list container
.review-card	Individual review wrapper
.review-card__header	Author name and date
.review-card__rating	Star rating display
.review-card__title	Review headline
.review-card__text	Review body text
.review-card__verified	Verified purchaser badge
.product-reviews__load-more	Load More button
.product-reviews__write-form	Write a Review form
.review-form__rating-selector	Star rating input
.review-form__submit	Submit Review button

Performance Optimization

Lazy Load Reviews

For products with many reviews, consider lazy loading reviews below the fold:

// Load first page immediately, defer additional pages
add_filter('commerce_connect_reviews_lazy_load', '__return_true');

Cache Review Data

Use object cache to reduce API calls for frequently-viewed products:

// Cache review data for 1 hour
add_filter('commerce_connect_reviews_cache_ttl', function() {
  return 3600; // 1 hour in seconds
});

Optimize Review Pagination

Reduce reviews per page for faster initial load:

add_filter('commerce_connect_reviews_per_page', function() {
  return 5; // Show 5 reviews initially, use "Load More" for rest
});

Related Blocks

• Single Product Template - Parent template that provides product context
• Account Login Block - Required for review submission authentication
• Product Buy Button - Often placed near Product Reviews block
• Product Description - Typically appears above Product Reviews

Related Documentation

• Product Reviews Feature - Complete review workflow, BigCommerce moderation, enabling reviews
• Product Sync - How review data syncs from BigCommerce to WordPress®
• Account Login Block - Customer authentication for review submission
• Single Product Template - Template structure where Product Reviews block lives