> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

> Whether AI shopping answers show your products, which sellers they name and how ready your product pages are.

**Products** is in the Insights menu of a brand with **Ecommerce** on. A brand with it off has no Products page. To turn it on, see [Sells to and ecommerce](https://docs.heralded.ai/concepts/workspaces-and-brands.md#sells-to-and-ecommerce). A saved link to Products on a brand with Ecommerce off says so and, if you can change settings, links to them.

ChatGPT, AI Mode and AI Overviews can answer a shopping question with product cards: a product's image, title, price, seller and rating. Products counts those cards. Gemini and Claude answers are read as text only, so they have no product card figures.

The headline gives the share of answers with product cards that showed one of your products, and your place among you and your tracked competitors. It says **No product cards appeared in the questions checked.** when no answer whose cards were read showed one. When the engine you filter to is read as text only, it says **Product cards aren’t read for these answers.** and the figures show a dash, not a zero. The freshness line names the update shown.

For a card to count as yours, your catalogue must list the product or the card must identify your brand through its title, a product line or your own shop. A shopping answer's attribution alone is not enough. A product with unknown ownership belongs to no brand.

## Filters

**Period** stays visible. Open **Filters** for **Market**, **Engine** and **Topic**. For **Your products**, **Shown** lists only products shown in organic product cards, or only those not shown. **Clear** resets every filter. Market, Engine and Topic apply to the figures, your products and the sellers. Google Shopping and Readiness follow the period alone.

## Figures

* **In product cards** is the share of answers with organic product cards that showed at least one of your products. It works even when your catalogue cannot be read. The note gives the counts.
* **Avg. position** is your best product’s place in each answer that showed one, averaged across those answers.
* **Complete product data** counts the checked product pages that state every field Google and OpenAI require: title, image, price and currency, availability and brand. It reads "of N checked" because only a sample of your product pages is checked. A dash means your catalogue could not be read.

Product-card percentages divide the printed numerator by the printed denominator. Their 95% ranges use the same pooled answer counts. Each brand counts once per answer, even when several of its products or maker spellings appear. Questions naming your brand or its products stay outside these figures.

A card whose maker is unknown counts toward **Answers with product cards**, but it counts for no brand.

When your catalogue cannot be read, products with the same maker and title count together across brand prefixes, gender words and singular or plural names. Pack sizes and model numbers stay separate. A product shown twice in one answer counts once. Merging products updates their figures; issued reports and alerts keep their original content. Saved product links open the merged product.

**Avg. position** takes the best organic place in each answer that showed your products, then averages those places. The API also serves `best_position`, the lowest place across those answers.

Each figure has an information button with its definition.

## Revenue from AI

With Google Analytics connected and purchases tracked, **Revenue from AI** shows visits, orders, revenue and conversion rate for each AI assistant. It is a minimum, for the reasons [Google Analytics](https://docs.heralded.ai/concepts/connections.md#google-analytics) gives. Where your property splits item revenue by source, your products also get an **AI revenue** column. Without a connection or a purchase in the window, Products shows no revenue rather than zero.

## Questions

**Questions** groups the tracked questions by whether their answers showed your products, only other products, no product cards, or were not read. Select a question to open its pane. More than 30 questions appear as a proportional bar. The engine row shows how many questions each engine showed your products on, out of the questions where it showed product cards. Engines whose captures failed say **Not read**. Engines that do not capture cards say **Not measured**.

## Product lists and views

**Your products** and **Competitors’ products** have separate search, sort and paging controls. Each list opens with the most shown products first and pages 25 at a time. Brand marks identify the maker. Competitors’ rows also name the brand. The columns are **Answers**, **Questions**, **Best card**, **Price shown** and **Seller**. Answers count answers with product cards that showed that product. Questions count distinct questions where it appeared. Best card is its lowest organic place. Price and seller come from its newest card. **Product data** appears for your products when product pages were read.

The tabs below the lists keep their selected view, sort and page in the address.

* **Sellers** lists the sellers the cards named, with the products they were shown selling and how many were yours.
* **Google Shopping** lists the Google Shopping searches the newest report read, with your best product's position, or **Not in the top 40**, and the search's first product.
* **Readiness** lists each check against Google's and OpenAI's product data standards, with the products passing out of those it applied to. Product codes count variants. When your product pages could not be read, the view says why.

On a phone, rows show the price shown under the product name, and a **Sort** menu keeps the orders for hidden columns.

## A product's pane

Select a product to open its pane. It follows the page's period, market, engine and topic. Where the answers those filters select have no product cards read, the pane says so and shows no figures.

The pane heading shows the newest card's price and seller, such as "€119 at your shop".

* **Answers** and **Avg. position** sum it up. The Answers note gives the total answers with product cards.
* **Next step** opens the work Heralded suggests first for the product's page.
* The weekly trend of **In product cards** for your own products, and the figure for each engine. An engine with no cards on its topics says **No product cards**.
* **Questions** lists each question with the marks of the engines that showed this product, its place and seller, **Answers** and **Best card**. Questions where other products were shown and yours was not can also appear when its catalogue coverage was checked.
* **Shown beside it** lists products shown in the same filtered answer population, with brand marks, **Answers** and **Best card**. Your products say **You**. Each opens its own pane. Questions called missed and product-movement alerts still require a topic that covers your product. When no catalogue was read, those opportunities are not checked.
* **Facts AI states** lists what answers say about the product, with the answers that say it.
* **Sources** lists the pages cited in answers that showed it.
* **Revenue from AI** shows its revenue by assistant, where your property splits item revenue by source.
* **Work on this** lists the work on the product's page, and the retailer work filed for it. For your own products the footer offers the kinds of work that fit: a page rewrite for a product AI states a wrong price for or never shows, product markup for a field the catalogue knows, and a retailer to be listed with for a product AI never shows. Once any of that work is filed, its stage takes the button's place and opens it. Viewers see the work, but not the offer.

## Read through the API or an assistant

`GET /v1/brands/{brand_id}/products` returns your products by default. Set `view=competitors` for tracked competitors' products, or `view=all` for all observed products. `maker` selects a canonical maker key, `competitor` selects a tracked competitor key and `prompt` selects a question. `limit`, `offset` and `next_cursor` page the filtered list, and `total` counts it before paging. MCP `get_products` uses `product_scope` for the same selection while `view=products`.

Product rows use the tracked competitor's name when the maker matches that competitor or one of its aliases. Other makers use their most common spelling in the selected answers. The API and MCP maker and competitor filters also accept those aliases. Shared Snapshots use the names of the competitors their report identifies.

Set `with_makers=true` to include `maker_options`, the canonical keys and names of makers observed in organic cards under the selected view and figure filters. Each option has `value` and `label`. `makers_limit` and `makers_offset` page these options independently of products; `maker_options_total` counts them before paging. The selected `maker` does not narrow its own options.

The product-card figures follow `period`, `market`, `engine`, `topic`, `audience`, `intent`, `type`, `prompt` and `country`. `product_card_weeks` counts the period's weekly reports with Ecommerce on, so a period crossing a change of that setting can include fewer product weeks.

Every products list view also returns `question_strip`, `engines` and `rank` through the API and the `get_products` MCP tool. The strip counts tracked questions under the figure filters, excluding questions naming your brand. Its groups are `yours`, `others`, `none` and `not_read`. A question belongs to `yours` if any read answer showed one of your products, to `others` if read answers showed only other products, and to `none` if cards were read but no organic cards appeared. With no read answers, it belongs to `not_read`, including before your first Ecommerce report. When the total is at most 30, `questions` lists each question's `id`, `text` and `group` in that group order. Above 30, `questions` is null.

The `engines` list follows your brand's engine order. Each entry gives `with_cards` and `yours` as question counts, plus its read state. `rank` gives your `position` out of `of` brands by **In product cards**, among you and your tracked competitors. A selected question or topic limits the ranked competitors to those named in its answers, as on Competitors. Ties share a place and skip the following places. Rank is null when no answer showed organic product cards. The competitors read accepts `sort=product_cards`, with unmeasured brands last in either direction.

Each product row, including a product's detail and MCP reads, gives `questions_shown`, the distinct questions whose read answers showed that product. These fields are null for brands with Ecommerce off. Product list view, maker and competitor selectors choose the rows; the summary follows the figure filters across every view.

In a product's questions, each engine gives `seller_is_your_shop` alongside `seller` and `position` from the same best organic card. It is true for your shop, false for another seller and null when the card has no classification. Older saved reports without this field also return null.

The prompts list and a question's read return `product_cards` with `products`, the number of distinct organic products across its read answers, `yours`, how many are yours, and `best`, your lowest card place. A product with unknown ownership belongs to no brand. Question counts use the products the cards identified. The competitors list and a competitor's read return `product_cards` with `in_product_cards`, `average_position` and `best_position`, using the definitions above. Each field includes `weeks`, the Ecommerce weeks counted, and `state`. `read` means at least one answer's cards were read. `not_read` means no answers yet or every capture failed. `not_measured` means the engine does not capture cards. Product-card fields are null for brands with Ecommerce off and on the competitors' Google search view.

A shared Snapshot's shopping section includes its questions, per-brand figures, question groups and counts by engine. It identifies only your products and products of the report's named competitors. Other products are omitted or read **Another brand's product**, without a maker, image or link. `more_brands` counts additional makers before the product lists are capped. `brand_keys` gives the key of your brand and of each competitor the report names, which indexes `brands` and filters the complete [shared product lists](https://docs.heralded.ai/figures.md#scans).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.