Product structured data: offers, ratings, common errors

What product markup does

Product structured data describes a product in a form that programs can read: its name, image, price, currency, availability and ratings. The vocabulary comes from schema.org, and a common format is JSON-LD, a block of data inside the page that visitors do not see. Google can use this data to show product information in search results, for example a price or star ratings. Google also makes clear that structured data is no promise of a rich result.

Two kinds of product pages

Google distinguishes two cases. Merchant listings are for pages where a shopper can buy the product from you. Product snippets are for other product pages, such as reviews, tests and comparison pages. The requirements differ, so first decide which case your page is.

According to Google, product rich results only support pages that focus on a single product, or on several variants of the same product. Google recommends adding the markup to product pages, not to category pages or lists of products.

The building blocks

• Product: the item itself, with name, image, description, brand, sku and, where you have one, a GTIN.
• Offer: the conditions of sale, with price, priceCurrency, availability, the url of the offer and, if the price ends, priceValidUntil.
• AggregateRating: the average of many ratings, with ratingValue and either ratingCount or reviewCount.
• Review: a single review. Google requires that the name of the author is a valid name of a person or a team.

A minimal example

This block describes a mug that is for sale. It belongs in the HTML of the product page, usually in the head or at the end of the body.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Blue ceramic mug, 0.3 l",
  "image": "https://example.com/img/mug-blue.jpg",
  "sku": "MUG-BL-03",
  "brand": { "@type": "Brand", "name": "Example Pottery" },
  "offers": {
    "@type": "Offer",
    "price": "12.90",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/mug-blue"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.6",
    "reviewCount": "38"
  }
}
</script>

Three details cause many errors. schema.org asks for a point as the decimal sign and no currency symbol in the price, so write 12.90, not 12,90 or €12.90. The currency goes into priceCurrency as an ISO 4217 code, such as EUR or PLN. The availability is a value from schema.org, such as InStock or OutOfStock.

Ratings and reviews

An AggregateRating needs ratingValue and at least one of ratingCount or reviewCount. Inside a product, itemReviewed is not needed. If you leave out bestRating and worstRating, Google assumes a scale from 1 to 5. If your shop uses another scale, for example 1 to 10, state it.

Price, availability and keeping it current

• Mark up only what visitors can see. Google writes that the structured data must be a true representation of the page content.
• Change the markup when the price or the stock changes. A good shop system does this automatically, a block typed by hand does not.
• Set priceValidUntil only if the price really ends. According to Google, a date in the past may stop the product snippet from being shown.
• Use one currency per address. Google asks for a separate URL for each currency.
• Describe shipping and returns once for the whole shop. Google recommends a global return policy and shipping policy under the Organization markup.

Typical errors

• The price is written with a comma, with a currency symbol, or as 0 on a page where the product is sold.
• priceCurrency contains € or $ instead of a code such as EUR or USD.
• The image is missing, although merchant listings require it.
• A shop page uses AggregateOffer. Merchant listings require an Offer, because the merchant has to be the seller.
• The name or the price in the markup differs from the page, often after a price change.
• Two blocks describe the same product with different values, for example one from the theme and one from a plugin.

How to check your markup

Google names the Rich Results Test and the URL Inspection tool, which catch most technical errors. Some problems remain invisible to such tests, for example a rating that is not on the page. Google can also take a manual action for structured data that breaks its rules. The page then loses eligibility for rich results, and the structured data is ignored.

Work with Do4U

The Structured data check reads a page from its address, or the HTML or JSON-LD block that you paste. It reads all JSON-LD blocks, also @graph and nested items, as well as microdata and RDFa. The code finds syntax errors with line and column, unknown or misspelled types and the properties Google requires or recommends for product snippets, merchant listings, offers and ratings. It checks the form of prices, currencies, dates and ratings and warns when a name or price in the markup does not appear in the visible text. You get a tree of the items with errors, warnings and the source of each rule. The page is read as the server delivers it, without JavaScript. No AI is used, and the check is free, with a daily limit.

Do4U finds hints, you check and decide. Whether a rich result appears is decided by Google, and only you know whether a price, a stock level or a rating is correct.