Product schema: the complete markup for a product page, with price, stock, shipping and returns

Product schema is the markup that hands Google and other systems the data on a product page so they do not have to infer it: name, brand, price, currency, availability, ratings, shipping and returns. Google only requires a name, an image and an offer with price and currency, but markup that contradicts the page works against you: mark up less, and mark it up right.

To check it on your own site: Online shops

This guide goes deep on the markup; the rest of the work on a shop (product pages, categories, filters, speed and AI assistants) is in the guide to e-commerce SEO for AI search. A declaration of interest: this blog belongs to SmoothSeen, a web audit tool that measures visibility in search engines and AI assistants.

What is Product schema and what is it for?

Product schema is a block of structured data, usually JSON-LD, that uses the schema.org vocabulary to declare which product a page sells. Schema.org defines Product as any offered product or service1, and the sales offer sits inside it, in an Offer. What structured data is in general, and which other types Google uses, is covered in the guide to structured data.

Google uses this markup for two kinds of result2:

• Product snippets, for pages where people cannot buy the product directly, such as a review.
• Merchant listings, for pages where customers can buy the product from you. They can show price, availability, shipping and returns.

If you run a shop, the second one is yours. Google is explicit: only pages where a shopper can buy the product are eligible for merchant listings, not pages that link to another site that sells it3. It adds that search result enhancements are shown at the discretion of each experience2: correct markup makes you eligible, it guarantees nothing.

Which fields are required and which are recommended?

This table summarises Google's documentation for merchant listings3:

Three details that prevent mistakes. The price must be greater than zero: unlike product snippets, merchant listings do not accept a price of 03. For barcodes, Google recommends the most specific GTIN property that applies (gtin8, gtin12, gtin13, gtin14) over the generic gtin3. And Google may try to verify product data before showing it3, so what you mark up has to be what shoppers see.

A commented JSON-LD example

This example is for a fictional shop: example.com is a domain reserved for examples, and the product, price and ratings are made up.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example Moka stovetop espresso maker, 6 cups",
  "image": [
    "https://www.example.com/img/moka-6-front.jpg",
    "https://www.example.com/img/moka-6-open.jpg"
  ],
  "description": "Aluminium stovetop espresso maker for 6 cups, suitable for gas and ceramic hobs; not suitable for induction.",
  "sku": "MOKA-6-AL",
  "gtin13": "0000000000000",
  "brand": { "@type": "Brand", "name": "Example Kitchen" },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.4,
    "reviewCount": 27
  },
  "offers": {
    "@type": "Offer",
    "url": "https://www.example.com/espresso-makers/moka-6",
    "price": "29.99",
    "priceCurrency": "GBP",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingRate": { "@type": "MonetaryAmount", "value": 3.95, "currency": "GBP" },
      "shippingDestination": { "@type": "DefinedRegion", "addressCountry": "GB" },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "handlingTime": { "@type": "QuantitativeValue", "minValue": 0, "maxValue": 1, "unitCode": "DAY" },
        "transitTime": { "@type": "QuantitativeValue", "minValue": 1, "maxValue": 3, "unitCode": "DAY" }
      }
    }
  }
}

What to look at in each part:

1. price uses a full stop as the decimal separator and no currency symbol, and priceCurrency is an ISO 4217 code: GBP. The page can show "£29.99"; the markup cannot.
2. availability and itemCondition use schema.org URLs (https://schema.org/InStock), not free text such as "in stock".
3. gtin13 carries the product's real barcode number. The one in the example is a placeholder: if your product has no GTIN, leave the property out rather than invent one.
4. deliveryTime splits two periods: the warehouse handling time (handlingTime) and the carrier's transit time (transitTime), each with its minimum, maximum and the unit DAY3.
5. Ratings are the ones shown on the page: the same average and the same number of reviews.

One last practical point: generate the markup from your platform, using catalogue data, not by hand. Hand-written JSON goes stale with the first price change, and markup that says one thing while the page says another is exactly what to avoid. Put it in the initial HTML, too: Google warns that Product markup generated with JavaScript can make Shopping crawls less frequent and less reliable, a problem for data that changes as fast as price and stock4.

How do you mark up product variants?

Sizes, colours or materials of the same product are grouped with the ProductGroup type. The only property Google lists as required is the name, but its guidelines say the group must have a unique ID, usually productGroupID (the parent SKU), and each variant its own, with sku or gtin4. Google also recommends stating what the variants differ by with variesBy and linking them with hasVariant4. Each variant is a full Product.

variesBy only accepts six values, each written as its schema.org URL4:

• https://schema.org/color
• https://schema.org/size
• https://schema.org/suggestedAge
• https://schema.org/suggestedGender
• https://schema.org/material
• https://schema.org/pattern

Google supports two designs4. If every variant lives on one page, that page has a single canonical URL for the whole group, normally the one with no variant preselected. If each variant has its own page, each page carries full, self-contained markup, with the whole ProductGroup repeated. In both designs the variants can be nested in hasVariant or kept separate, pointing back to their group with isVariantOf.

One requirement often fails: the site must be able to preselect each variant with a distinct URL, for example with a parameter (?colour=blue)4. Preselecting means showing that variant's image, price and availability and letting the shopper add it to the basket. If the colour only changes with a JavaScript click and the URL stays the same, Google has nowhere to send someone searching for the blue one.

How do you mark up shipping and returns?

The cleanest way is to declare them once for the whole shop, in your Organization markup, and repeat them on a product only when that product has different terms. Google recommends this for both3: the returns policy with hasMerchantReturnPolicy and the shipping policy with hasShippingService, both under Organization.

Returns: MerchantReturnPolicy

For a returns policy, Google requires the country it applies to (applicableCountry, a two-letter ISO 3166-1 code such as GB) and the type of policy (returnPolicyCategory)5. If the return window is limited, add the number of days (merchantReturnDays). The minimal alternative is to link to the policy page with merchantReturnLink.

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Kitchen",
  "url": "https://www.example.com/",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": "GB",
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 30,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn"
  }
}

The possible values, according to Google5:

Shipping: shippingDetails or ShippingService

On a product page, shipping goes in shippingDetails, as in the example above. For the whole shop, Google documents hasShippingService under Organization, with a ShippingService that groups conditions (shippingConditions): cost and delivery times by destination, order value, weight or number of items6.

Which source wins when data lives in several places

Google applies an order of precedence, strongest first, and it is the same for shipping and returns65:

1. Settings sent through the Content API for Shopping.
2. Settings in Merchant Center or Search Console.
3. Markup on the product page (shippingDetails, hasMerchantReturnPolicy on the offer).
4. Markup on Organization.

The upshot: if you already have shipping and returns set up in Merchant Center, Google will use those. For shipping, Google says it outright: if you provide the policy both in your markup and in Search Console, it will only use the Search Console settings6. Markup is still useful if you do not use those tools, but every source should say the same thing.

Ratings: only real ones

The aggregateRating block is the one that can bring stars to a result, and also the one most often marked up badly. Google requires the average rating (ratingValue) and at least the number of ratings (ratingCount) or reviews (reviewCount)7. If your scale does not run from 1 to 5, declare bestRating and worstRating as well.

Google's guidelines that matter most to a shop7:

• Marked-up reviews must be readily available to users on the marked-up page.
• Do not aggregate reviews or ratings from other websites. Reviews of your shop on a marketplace or a review platform do not belong in your product markup.
• Ratings must come directly from users, with no fake or undisclosed incentivised reviews.
• Each rating is about one specific item, not a category or a list of items.

A few real, visible reviews are worth more than a rounded average nobody can check. If a product has no reviews yet, leave aggregateRating out: it is not required.

How do you validate the markup?

With three free Google tools, in this order:

1. Rich Results Test. Google asks you to validate the code with it and fix any critical errors3. It tells you whether the page is eligible for merchant listings and which properties are missing.
2. URL Inspection in Search Console. It shows how Google sees the live page. Google reminds you that the page must not be blocked by robots.txt, a noindex tag or a login3.
3. The Merchant listings report in Search Console, under Shopping. It shows whether Google has found valid items of that markup on your site8, and is worth checking after every template change.

Run them on the template, not on a single product: a fault in the product template is on every product page, and fixing it once fixes them all. How fast that same template loads is a separate matter, with its own metrics, covered in the guide to Core Web Vitals for e-commerce.

Markup does not replace the text

Markup repeats what the page says; it does not stand in for it. For its AI features, Google asks that structured data matches the visible text and that important content is available in textual form9. Price, delivery time and returns policy have to be written on the product page, not only in the JSON. How to write those facts so an assistant can quote them is covered in the guide on how to get cited by AI.

SmoothSeen checks, on every product page it analyses, whether the product markup declares price, availability, brand and description, whether it includes shipping, returns, ratings and specifications, and whether the page has an original description and an FAQ. It does not connect to Merchant Center or Search Console: it reads the live page, as a search engine does.

Frequently asked questions

Which fields are required in Product schema?

For merchant listings, Google requires the name, the image and the offer (offers) on the Product, and on the offer a price above zero and its currency. Everything else is recommended: availability, condition, shipping, returns, brand, identifiers such as the GTIN, description and ratings. Recommended does not mean optional in practice: these are the facts that decide whether a result can show more than a price.

Can I mark up ratings from another website?

No. Google's review snippet guidelines say explicitly not to aggregate reviews or ratings from other websites, that ratings must come directly from users and that marked-up reviews must be available on the page. If your reviews live on an external platform, link to it; in the product markup, only include the reviews published on that page.

How do I mark up a returns policy?

If it is the same across the shop, declare it once with hasMerchantReturnPolicy in your Organization markup: country, policy type and, for a limited window, the number of days. You only need it on a product's offer when that product has different terms. If you have already set returns up in Merchant Center or Search Console, Google gives those settings precedence over the markup.

Does Product schema get my products into ChatGPT?

OpenAI says ChatGPT considers structured metadata from first-party and third-party providers, such as price and product description10, but it does not say it reads the markup on your page. What is documented is that Google asks for structured data that matches the visible text for its AI features. Complete, consistent markup is the groundwork for both.

What to do next

Run one product page from each template through the Rich Results Test and compare the result with the field table in this guide. If shipping or returns are missing, start with the Organization markup, which you only do once. For the rest of the shop, go back to the guide to e-commerce SEO for AI search.