Ratings and Reviews

The Ratings and Reviews drop-in shows approved shopper reviews on your product pages. Each review shows the reviewer’s name, star rating, title, text, and date. Long review lists split into pages. Shoppers can also write reviews, which appear after you approve them.

Average star ratings also appear outside the review list: below the product name on the product details page (PDP), on product listing page (PLP) and search result cards, and on recommendation cards. These ratings come from your catalog, so they load with the product data and need no extra requests.

What shoppers see

Review list: Approved reviews for the current product, 20 per page by default, in the order Commerce returns them.
Page controls: Previous, next, and page-number buttons when a product has more than one page of reviews.
Review form: A star rating for each rating category, plus Title, Description, and Name fields. After submission, shoppers see a message that the review is pending moderation.
Average rating on the product page: Stars and the approved review count below the product name.
Ratings on product cards: Stars, the average value, and the review count on listing and search cards. Recommendation cards show stars and the review count.

Products without approved reviews show no average rating on product pages or recommendation cards. When product reviews are turned off for the store, the review list and its page controls do not appear.

How it works

For a shopper’s own approved review history in My Account, use the User Account ProductReviews container or Commerce Customer Reviews block. Account history is separate from the public product review list and submission form. It does not require the Ratings and Reviews drop-in.

Ratings and reviews come from two data sources. Knowing which source feeds each part of the page helps you find the cause when a rating or review does not appear.

Storefront element	Data source	Rendered by
Review list and page controls	Commerce GraphQL `reviews` query, which returns the approved reviews for one SKU	Ratings and Reviews drop-in: `Review` and `Pagination` containers
Review settings	Commerce GraphQL `storeConfig` query: `product_reviews_enabled` and `allow_guests_to_write_product_reviews`	Ratings and Reviews drop-in initializer
Review form	Commerce GraphQL `productReviewRatingsMetadata` query for rating categories and `createProductReview` mutation for submission	Ratings and Reviews drop-in: `WriteReview` container
Average rating and review count	Catalog Service product attributes `ac_rating_summary` and `ac_review_count`	Product Details `ProductRating` container, product listing cards, and recommendation cards

The two catalog attributes carry the review summary for each product:

ac_rating_summary: The average rating as a percentage from 0 to 100. Storefronts divide it by 20 to get a 0–5 star value. For example, 90 displays as 4.5 stars.
ac_review_count: The number of approved reviews.

Commerce manages these attributes for you. The SaaS Data Export extension adds them to the product feed and updates the feed when a product’s review summary changes. Only approved reviews count toward the summary. Changes reach the storefront after the next product feed synchronization, not immediately. See the SaaS Data Export release notes (version 103.6.0).

Before you begin

Ratings and reviews need setup in three places: the Commerce backend, the catalog attributes, and your storefront code. Complete the backend steps first so that the storefront has data to show.

Commerce backend

Reviews API: Your Commerce GraphQL endpoint must provide the reviews query. This query is part of the Storefront Compatibility Package. See the reviews query reference for availability and the full schema.
Product reviews turned on: In the Admin, go to Stores > Settings > Configuration > Catalog > Catalog > Product Reviews and set Enabled to Yes.
Approved reviews: Shoppers see only approved reviews. Moderate reviews in Marketing > User Content > All Reviews or Pending Reviews. Approved reviews also update the average rating and review count.
Rating categories: Review ratings use the rating categories in Stores > Attributes > Rating. A rating is used only when it is active and assigned to the store view. The review form shows one star row for each of these categories. A review with no rating votes shows Not rated in the review list.
Guest reviews: In the same Product Reviews settings, set Allow Guests to Write Reviews. When it is No, signed-out shoppers see a sign-in prompt instead of the review form.
reCAPTCHA (optional): To protect the review form, enable Product Review in the Google reCAPTCHA Storefront settings. See reCAPTCHA.

Catalog attributes

Catalog Service returns each product attribute with storefront roles, such as visible_in_pdp for the product page and visible_in_plp for product listings.

Product page: The Product Details drop-in keeps only attributes with the visible_in_pdp role. The exporter always turns on this role for both attributes.
Product listing and search results: The product listing setting is off by default for both attributes. If listing and search result cards show no ratings, enable the product listing setting for both attributes on their Storefront Properties tabs in Stores > Attributes > Product.

Storefront

Drop-in and block: Install the drop-in and add the Product Reviews block. See the Ratings and Reviews quick start.
Review form: Add a Write review button that opens the form. See Add a Write review button.
Ratings on other pages: Add average ratings to the product page, product listing cards, and recommendation cards.

Supported Commerce features

The following table lists the Commerce review features that the storefront supports:

Feature	Status
Approved review list for a product	Supported
Review pagination	Supported
Review submission with a rating for each rating category	Supported
Guest review setting (`allow_guests_to_write_product_reviews`)	Supported
Pending-moderation message after submission	Supported
reCAPTCHA for the review form	Supported
Store-level review enablement (`product_reviews_enabled`)	Supported
Average rating and review count on product pages	Supported
Average rating and review count on product listing and search result cards	Supported
Average rating and review count on recommendation cards	Supported
Multiple independent review lists on one page	Supported
Localized labels and review dates	Supported

Section topics

Quick start: Install the drop-in and show reviews on product pages.
Initialization: Configure the endpoint, labels, and data models.
Containers: Configure the Review, Pagination, and WriteReview containers.
Functions: Load reviews and review settings, and submit reviews, with API functions.
Events: Respond to review loading, results, errors, and submissions.
Slots: Replace or extend parts of the review list, page controls, and review form.
Styles: Customize the review layout with CSS.
Dictionary: Change labels and localize text.
Product Reviews block: Place reviews on pages without code.