diff --git a/src/pages/config.md b/src/pages/config.md index dbff60d6e..3c3dff4f4 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -384,6 +384,7 @@ - [isSubscribedProductAlertStock](/graphql/schema/products/queries/is-subscribed-product-alert-stock.md) - [products](/graphql/schema/products/queries/products.md) - [productReviewRatingsMetadata](/graphql/schema/products/queries/product-review-ratings-metadata.md) + - [reviews](/graphql/schema/products/queries/reviews.md) - [route](/graphql/schema/products/queries/route.md) - [sourceAvailability](/graphql/schema/products/queries/source-availability.md) - [urlResolver](/graphql/schema/products/queries/url-resolver.md) diff --git a/src/pages/graphql/schema/products/queries/index.md b/src/pages/graphql/schema/products/queries/index.md index e03a1bb45..546285eec 100644 --- a/src/pages/graphql/schema/products/queries/index.md +++ b/src/pages/graphql/schema/products/queries/index.md @@ -15,6 +15,7 @@ This section describes the following queries: * [`isSubscribedProductAlertStock`](is-subscribed-product-alert-stock.md) * [`productReviewRatingsMetadata`](product-review-ratings-metadata.md) * [`products`](products.md) +* [`reviews`](reviews.md) * [`route`](route.md) * [`sourceAvailability`](source-availability.md) * [`urlResolver`](url-resolver.md) diff --git a/src/pages/graphql/schema/products/queries/reviews.md b/src/pages/graphql/schema/products/queries/reviews.md new file mode 100644 index 000000000..5da58a8c8 --- /dev/null +++ b/src/pages/graphql/schema/products/queries/reviews.md @@ -0,0 +1,90 @@ +--- +title: reviews query +description: The reviews query returns the approved reviews for a product specified by SKU. It is a standalone root query for the storefront compatibility layer. +--- + +# reviews query + + + +The `reviews` query returns the approved reviews for the product specified by its SKU, along with pagination metadata. + +Unlike the native `reviews` field on `ProductInterface`, which requires querying a product first, this is a standalone root query. It allows the storefront to retrieve product reviews directly by SKU without a preceding product lookup. + +Use the [`createProductReview` mutation](../mutations/create-review.md) to add a product review, and the [`productReviewRatingsMetadata` query](product-review-ratings-metadata.md) to return the list of rating categories and possible values. + + + +Review text fields (`nickname`, `summary`, and `text`) are stored as untrusted plain text and are not sanitized on write. Clients must render these fields as text or apply context-appropriate output encoding to prevent cross-site scripting (XSS). + +## Syntax + +`reviews(sku: String!, pageSize: Int = 20, currentPage: Int = 1): ProductReviews` + +[//]: # (## Reference) +[//]: # () +[//]: # (The [`reviews`](/reference/graphql/saas/index.md#reviews) reference provides detailed information about the types and fields defined in this query.) + +## Example usage + +The following query returns the approved reviews for the product with the SKU `24-MB01`. + +**Request:** + +```graphql +query { + reviews(sku: "24-MB01", pageSize: 20, currentPage: 1) { + items { + nickname + summary + text + average_rating + created_at + ratings_breakdown { + name + value + } + } + page_info { + current_page + page_size + total_pages + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "reviews": { + "items": [ + { + "nickname": "Bailey", + "summary": "Comfortable and durable", + "text": "I use this bag every day and it has held up well.", + "average_rating": 80, + "created_at": "2026-09-17 12:12:00", + "ratings_breakdown": [ + { + "name": "Quality", + "value": "4" + }, + { + "name": "Value", + "value": "4" + } + ] + } + ], + "page_info": { + "current_page": 1, + "page_size": 20, + "total_pages": 1 + } + } + } +} +```