> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ecomelixir.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Product ratings
> Show real star ratings from your review app instead of placeholder numbers
Elixir displays star ratings on product cards, product pages, and cart upsells. Those stars can come from two places: a number you type in yourself, or the real rating stored on the product by your review app.
Out of the box, several rating elements show **placeholder values** like 4.7 out of 5 with 137 reviews. These are design defaults, not your data. Connect a review app or replace them with your real numbers before you launch. Displaying invented ratings is misleading advertising in most markets.
## How ratings reach the theme
Review apps write a product's average rating into Shopify **metafields**. Elixir reads them automatically, so no code or app block is needed to show stars.
| Metafield | What it holds |
| ---------------------- | ---------------------------------------------------------- |
| `reviews.rating` | Average rating and the scale, for example 4.6 out of 5 |
| `reviews.rating_count` | Number of reviews |
| `custom.rating` | Average rating, used by the product page rating text block |
| `custom.rating_count` | Number of reviews for the same block |
The `reviews` namespace is Shopify's standard. Judge.me, Loox, Okendo, Yotpo, Stamped, and Shopify's own Product Reviews all write to it.
## Step 1: Install and sync a review app
1. Install your review app from the Shopify App Store.
2. Import or collect your reviews.
3. In the app's settings, make sure the option to **publish ratings to Shopify product metafields** is enabled. App wording varies: "Shopify product rating metafield", "sync ratings to Shopify", or "star ratings in search and collections".
To confirm it worked, open any product in Shopify admin and scroll to **Metafields** at the bottom. You should see a rating value.
Metafields only populate for products that actually have reviews. A product with zero reviews has no rating, and the theme falls back to the static value you configured.
## Step 2: Turn on metafield ratings in the theme
### Collection and product cards
Open the **Collection Grid** section in the theme editor:
| Setting | What to do |
| -------------------------------- | ------------------------------------------------------------------------------- |
| **Show product rating** | On |
| **Use product metafield rating** | On, so cards read the real rating |
| **Static rating value** | Only used when the metafield toggle is off, or the product has no reviews |
| **Show rating number** | Displays the numeric value next to the stars |
| **Rating text format** | Use `{rating}` as the placeholder, for example `Rated {rating}` or `{rating}/5` |
With **Use product metafield rating** off, every product shows the same static number. That's fine for a pre-launch demo and misleading on a live store.
### Cart upsells
Upsell blocks in the cart drawer have their own **Rating Source** setting:
| Option | Behavior |
| --------------------- | ------------------------------------------------------ |
| **Product Metafield** | Reads the real rating from the upsell product |
| **Custom Text** | Uses the rating value and text you type into the block |
It defaults to **Custom Text**, so switch it to **Product Metafield** once your app is syncing.
### Product page rating blocks
The product page rating blocks read `custom.rating` and `custom.rating_count`. If those aren't set, the block falls back to **4.7** and **137** reviews.
You have two ways to make this honest:
* **Type your real numbers** into the block's text field, which overrides the metafield entirely.
* **Populate the `custom.rating` metafield** on each product, either by hand or through your review app if it lets you choose the namespace.
To set it by hand: **Settings → Custom data → Products → Add definition**, namespace and key `custom.rating`, type Decimal. Then fill it in per product. Repeat with `custom.rating_count` as an Integer.
## Where ratings appear
| Location | Reads |
| ------------------------------ | --------------------------------------------------------------- |
| Collection and product cards | `reviews.rating`, `reviews.rating_count` |
| Cart drawer upsells | `reviews.rating` when Rating Source is set to Product Metafield |
| Sticky add to cart | `reviews.rating` |
| Product page rating text block | `custom.rating`, `custom.rating_count` |
## Review sections are separate
Star ratings and review content are different things. The metafields above drive the **stars**. To display the review text itself, use one of the review sections (Customer Reviews, Reviews Carousel, Amazon Reviews, and so on) and enter the reviews manually, or place your review app's own block.
See the [social proof guide](/guides/social-proof) for choosing between the review sections.
## Troubleshooting
**Use product metafield rating** is off, so every card is showing the static value. Turn it on in the Collection Grid section.
Cards only render stars when the product actually has a rating metafield. Products with no reviews yet show nothing. Check a product in Shopify admin under **Metafields** to confirm the value exists.
That block reads `custom.rating` and `custom.rating_count`, not the `reviews` namespace your app writes to. Either type your real numbers into the block or create those custom metafields.
The app is rendering its own widget without syncing to Shopify metafields. Find the metafield or "star ratings in collections" option in the app settings and enable it, then let it backfill.
The theme reads the scale from the metafield itself, so a rating stored out of 10 displays out of 10. Check what scale your app writes.