From 189ae0d1f3271d13289198955486bd55170389c1 Mon Sep 17 00:00:00 2001 From: akhyatelachl Date: Wed, 23 Sep 2026 13:20:18 +0200 Subject: [PATCH 1/3] ACCS-1510: Document the reviews(sku) GraphQL query Add a query reference page for the standalone Query.reviews(sku) field provided by the storefront compatibility layer (SaaS only), and list it in the product queries index and the site navigation. --- src/pages/config.md | 1 + .../graphql/schema/products/queries/index.md | 1 + .../schema/products/queries/reviews.md | 116 ++++++++++++++++++ 3 files changed, 118 insertions(+) create mode 100644 src/pages/graphql/schema/products/queries/reviews.md 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..ec7fa9899 --- /dev/null +++ b/src/pages/graphql/schema/products/queries/reviews.md @@ -0,0 +1,116 @@ +--- +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. + +## Syntax + +`reviews(sku: String!, pageSize: Int = 20, currentPage: Int = 1): ProductReviews` + +## Input attributes + +The `reviews` query accepts the following attributes. + +Attribute | Data Type | Description +--- | --- | --- +`sku` | String! | The SKU of the product to return reviews for +`pageSize` | Int | The maximum number of results to return at once. The default value is 20 +`currentPage` | Int | The page of results to return. The default value is 1 + +## Output attributes + +The query returns a `ProductReviews` object. + +Attribute | Data Type | Description +--- | --- | --- +`items` | [ProductReview] | An array of product reviews +`page_info` | SearchResultPageInfo | Metadata that describes the returned page of results + +Each `ProductReview` object contains the following commonly requested fields. See the [`createProductReview` mutation](../mutations/create-review.md) for the full type. + +Attribute | Data Type | Description +--- | --- | --- +`average_rating` | Float! | The average rating for the product review +`created_at` | String! | The date the review was created +`nickname` | String! | The customer's nickname +`ratings_breakdown` | [ProductReviewRating] | An array of ratings by rating category, such as quality, price, and value +`summary` | String! | The summary (title) of the review +`text` | String! | The review text + + + +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). + +## 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 + } + } + } +} +``` From c28a0095085e63dfd00a5c691108d2d81c5e5b3c Mon Sep 17 00:00:00 2001 From: akhyatelachl Date: Fri, 25 Sep 2026 06:09:02 +0200 Subject: [PATCH 2/3] use scp-query.md --- src/pages/graphql/schema/products/queries/reviews.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/graphql/schema/products/queries/reviews.md b/src/pages/graphql/schema/products/queries/reviews.md index ec7fa9899..b7380b750 100644 --- a/src/pages/graphql/schema/products/queries/reviews.md +++ b/src/pages/graphql/schema/products/queries/reviews.md @@ -3,10 +3,10 @@ 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. From 8fc9125b30c129f0dda896db86dfc969fb58fc9f Mon Sep 17 00:00:00 2001 From: akhyatelachl Date: Fri, 25 Sep 2026 06:17:24 +0200 Subject: [PATCH 3/3] Add commented-out Reference section --- .../schema/products/queries/reviews.md | 40 ++++--------------- 1 file changed, 7 insertions(+), 33 deletions(-) diff --git a/src/pages/graphql/schema/products/queries/reviews.md b/src/pages/graphql/schema/products/queries/reviews.md index b7380b750..5da58a8c8 100644 --- a/src/pages/graphql/schema/products/queries/reviews.md +++ b/src/pages/graphql/schema/products/queries/reviews.md @@ -13,43 +13,17 @@ Unlike the native `reviews` field on `ProductInterface`, which requires querying 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. -## Syntax - -`reviews(sku: String!, pageSize: Int = 20, currentPage: Int = 1): ProductReviews` - -## Input attributes - -The `reviews` query accepts the following attributes. - -Attribute | Data Type | Description ---- | --- | --- -`sku` | String! | The SKU of the product to return reviews for -`pageSize` | Int | The maximum number of results to return at once. The default value is 20 -`currentPage` | Int | The page of results to return. The default value is 1 - -## Output attributes - -The query returns a `ProductReviews` object. - -Attribute | Data Type | Description ---- | --- | --- -`items` | [ProductReview] | An array of product reviews -`page_info` | SearchResultPageInfo | Metadata that describes the returned page of results + -Each `ProductReview` object contains the following commonly requested fields. See the [`createProductReview` mutation](../mutations/create-review.md) for the full type. +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). -Attribute | Data Type | Description ---- | --- | --- -`average_rating` | Float! | The average rating for the product review -`created_at` | String! | The date the review was created -`nickname` | String! | The customer's nickname -`ratings_breakdown` | [ProductReviewRating] | An array of ratings by rating category, such as quality, price, and value -`summary` | String! | The summary (title) of the review -`text` | String! | The review text +## Syntax - +`reviews(sku: String!, pageSize: Int = 20, currentPage: Int = 1): ProductReviews` -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). +[//]: # (## Reference) +[//]: # () +[//]: # (The [`reviews`](/reference/graphql/saas/index.md#reviews) reference provides detailed information about the types and fields defined in this query.) ## Example usage