Get Customer Reviews

About

The customerReviews query retrieves a paginated list of product reviews submitted by the authenticated customer. This is a read-only, customer-scoped resource — customers can only see their own reviews. Use this query to:

• Display the customer's review history in their account dashboard
• Show pending reviews awaiting approval
• Filter reviews by status or star rating
• Build review management UI for customers
• Implement pagination for customers with many reviews

This query uses cursor-based pagination and returns reviews with their associated product and customer data.

Authentication

This query requires customer authentication:

• Authenticated customers: Provide a valid customer authentication token in the Authorization header. Obtain this token via the Customer Login API.

Authorization: Bearer <accessToken>
X-STOREFRONT-KEY: <storefrontKey>

Arguments

Argument	Type	Required	Description
first	Int	❌ No	Number of items to return (forward pagination). Max: 100.
after	String	❌ No	Cursor for forward pagination. Use endCursor from previous response.
last	Int	❌ No	Number of items for backward pagination. Max: 100.
before	String	❌ No	Cursor for backward pagination. Use startCursor from previous response.
status	String	❌ No	Filter by review status: pending, approved, or rejected.
rating	Int	❌ No	Filter by star rating (1–5).

Possible Returns

Field	Type	Description
edges	[CustomerReviewEdge!]	Array of review edges with cursor and node.
edges.cursor	String!	Cursor for this edge, used in pagination.
edges.node	CustomerReview!	The customer review object.
edges.node.id	ID!	IRI identifier (e.g. /api/shop/customer-reviews/1).
edges.node._id	Int!	Numeric database ID.
edges.node.title	String!	Review title.
edges.node.comment	String!	Review body text.
edges.node.rating	Int!	Star rating (1–5).
edges.node.status	String!	Review status: pending, approved, or rejected.
edges.node.name	String!	Reviewer display name.
edges.node.product	Product!	Associated product with id, _id, sku, type.
edges.node.customer	Customer!	Customer who wrote the review with id, _id.
edges.node.createdAt	DateTime!	ISO 8601 creation timestamp.
edges.node.updatedAt	DateTime!	ISO 8601 last update timestamp.
pageInfo	PageInfo!	Pagination metadata.
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.

Filter Parameters

Parameter	Type	Values	Description
status	String	pending, approved, rejected	Filter by review approval status
rating	Int	1–5	Filter by star rating

Pagination Parameters

Parameter	Type	Description
first	Int	Return the first N items
last	Int	Return the last N items
after	String	Cursor — return items after this cursor
before	String	Cursor — return items before this cursor

Use Cases

1. Customer Review History

Fetch all reviews a customer has submitted to display in their account dashboard.

2. Pending Reviews

Filter by status: "pending" to show the customer which reviews are still awaiting approval.

3. Top-Rated Reviews

Filter by rating: 5 to highlight the customer's highest-rated reviews.

4. Review Status Tracking

Combine status and rating filters to help customers manage and track their reviews.

Best Practices

1. Use Pagination — Always implement pagination for better performance, especially for active reviewers
2. Show Status — Display the review status so customers know which reviews are live
3. Cache Results — Cache review lists as they change infrequently
4. Handle Empty States — Provide helpful UI when the customer has no reviews
5. Filter by Status — Allow customers to filter by pending/approved/rejected for easy management

Related Resources

• Get Single Customer Review — Query individual customer review details
• Get Product Reviews — Query all product reviews
• Create Product Review — Submit a new product review
• Pagination Guide — Cursor pagination documentation