Product Reviews

About

The productReviews query retrieves a collection of product reviews with filtering and pagination support. Use this query to:

• Display product reviews on product detail pages
• Show review statistics and ratings
• Filter reviews by product, status, and rating
• Build review listing pages with pagination
• Display customer feedback and testimonials
• Calculate average ratings and review counts
• Show pending reviews in admin dashboard
• Implement review sorting and filtering

This query supports full pagination with cursor-based navigation and flexible filtering options for various use cases.

Note: This query only returns reviews that have been approved by an admin. Reviews submitted by customers are set to pending by default and will not appear in the results until an admin approves them from the admin panel. pending and rejected reviews are never visible to storefront users.

Arguments

Argument	Type	Required	Description
status	String	❌ No	Filter by review status ("pending", "approved", "rejected").
rating	Int	❌ No	Filter by rating value (1-5 stars).
first	Int	❌ No	Number of results to return (forward pagination). Max: 100.
after	String	❌ No	Pagination cursor for forward navigation. Use with first.
last	Int	❌ No	Number of results for backward pagination. Max: 100.
before	String	❌ No	Pagination cursor for backward navigation. Use with last.

Possible Returns

Field	Type	Description
id	ID!	Unique review API identifier.
_id	Int!	Numeric review ID.
name	String!	Customer name who wrote the review.
title	String!	Review title/headline.
rating	Int!	Star rating (1-5).
comment	String!	Review comment/text.
status	String!	Review approval status ("pending", "approved", "rejected").
createdAt	DateTime!	Review creation timestamp.
updatedAt	DateTime!	Last update timestamp.
pageInfo	PageInfo!	Pagination information.
pageInfo.hasNextPage	Boolean!	Whether more pages exist forward.
pageInfo.hasPreviousPage	Boolean!	Whether more pages exist backward.
pageInfo.startCursor	String	Cursor for first item in page.
pageInfo.endCursor	String	Cursor for last item in page.
totalCount	Int!	Total reviews matching filters.

Review Status

Status	Description
"pending"	Awaiting moderation approval
"approved"	Published and visible on the storefront
"rejected"	Declined and not published

Use Cases

1. Product Reviews Page

Use the "By Product ID" example to display all approved reviews for a specific product.

2. Admin Review Management

Use the "Filtered by Status" example with status: "pending" to show reviews awaiting moderation.

3. High-Rated Reviews

Use the "Filtered by Rating" example with rating: 5 to highlight 5-star reviews.

4. Customer Testimonials

Filter by approved status and high rating to display customer testimonials.

5. Review Analytics

Use pagination to fetch all reviews for a product and calculate statistics.

Best Practices

1. Filter by Status - Always filter by status: "approved" to show only approved reviews to customers
2. Show Ratings - Display the rating prominently alongside the review
3. Use Pagination - Always implement pagination for better performance
4. Cache Results - Cache reviews for better performance as they change infrequently
5. Sort Reviews - Display most recent or highest-rated reviews first
6. Prevent Spam - Only show approved reviews to maintain quality
7. Display Author Info - Show customer name to build trust and authenticity

Related Resources

• Get Single Product Review - Query individual review details
• Create Product Review - Submit new product review
• Get Product - Query product details
• Pagination Guide - Cursor pagination documentation
• Shop API Overview - Overview of Shop API resources