How to Make Ecommerce Product Data Understandable to AI Agents: A Practical Data Contract

A shopper opens your store's chat late at night and types: "Blue linen shirt, size medium, under $100, and it has to be machine washable."

You sell exactly that shirt. But your catalog calls the color "Ocean." The fabric is mentioned halfway down the description. Care instructions sit in a PDF care guide. Stock for the medium lives in its own variant record, and the $89 price belongs to the US offer only.

Every fact the shopper needs exists somewhere in your systems. None of them are connected in a way a machine can trust. So the AI agent answering that question can guess, hedge, or skip your product. None of those sell a shirt.

This guide shows how to fix that with a product-data contract: a short, written agreement that gives each product fact one meaning, one scope, one source, and one test. We'll follow a single fictional product from messy source data to a verified answer, with mapping rules and acceptance tests you can reuse on your own catalog.

What is a product-data contract?

It answers a question most catalogs never write down: how does the same product fact keep its meaning when it moves from your catalog into other systems?

That question matters more now than when your only audience was a person on a product page. A person sees the swatch, notices it's blue, and fills in the gaps. An AI agent reads literally. It combines facts from your product page, structured data, merchant feed, and on-site assistant, then answers in one confident sentence. If "Ocean" never connects to "blue," or the medium borrows the large's stock status, the agent repeats the error with full confidence.

What a product-data contract is not

It isn't another list of fields to fill in. Deciding which attributes matter is the first step, and our guide to the product data fields that make or break AI visibility covers it. A contract governs how those fields behave once they exist.

It isn't schema markup. JSON-LD is one destination format. The contract sits upstream and decides what "in stock" or "machine washable" actually means before anyone translates it. For the markup itself, see schema markup for AI search and our advanced schema markup guide for GEO.

It isn't a one-time cleanup. Prices, stock, and policies change daily. The contract makes those changes predictable instead of surprising.

As we explain in catalog-first AI, your catalog sets the accuracy ceiling for any AI that reads it. A contract is the practical tool for raising that ceiling.

What should a product-data contract define for each attribute?

Every attribute in the contract gets the same seven definitions. Here they are for one deceptively simple field, machine_washable.

The missing-value rule does the most work. Without it, an empty field drifts into a "no" in one system and a silent omission in another, and the AI agent sees contradictory signals. With it, the agent can say exactly what is confirmed and what isn't.

The source rule does the second most. It stops a sentence like "breezy, easy-care linen" in marketing copy from turning into a care instruction nobody approved.

Separate the product, the variant, and the offer

Product, variant, and offer data answer different questions, so they belong in different records joined by stable identifiers.

• The product (or product family) is the design: Harbor Linen Shirt.
• The variant is one purchasable combination of options: Ocean, size M, regular fit.
• The offer is the commercial terms for that variant in one context: $89.00 USD, in stock, US market.

When these layers blur, predictable errors follow:

• One variant's stock status is copied to the whole family, so an agent says the large is available when only the medium is.
• A promotional price on one colorway appears on every color.
• Every variant shares one URL, so a link from an AI answer lands on the default option instead of the one the shopper asked about.
• A US price appears in an answer for a Canadian shopper, with no currency attached.

Google's own model reflects the same split. Its product variant structured data documentation uses ProductGroup for the family, individual Product entries for variants, and offers attached to each variant. It also describes variant URLs that preselect the correct options.

Your internal model doesn't need to copy any destination's schema. It needs to keep enough detail to map into each one correctly.

Normalize values without flattening them

Normalization makes equivalent values comparable across products, but it should add a layer of meaning, not erase the original one.

Three rules keep it honest:

1. Keep the display value and add a canonical one. "Ocean" stays on the page because it's part of your brand voice. A color family of "blue" sits beside it so filters and AI agents can match a shopper who has never heard of "Ocean."
2. Never store a number without its unit or system. "M" means little without "US sizing, regular fit." "42" could be a chest measurement in inches or a European size.
3. Don't merge claims that only look similar. "Water-resistant" and "waterproof" are different promises. "Fits model A" does not establish "fits model B." Collapsing them turns a careful claim into a false one.

Every controlled vocabulary (color families, fit types, material names) also needs an owner who approves new values. Otherwise "navy," "dark blue," and "midnight" quietly become three families within a quarter. How these vocabularies shape filters and collections is a merchandising question, covered in our guide to attribute merchandising.

A worked record

Here is the fictional shirt's medium variant after normalization:

{
  "contract_version": "1.2",
  "product_id": "harbor-linen-shirt",
  "variant_id": "harbor-linen-shirt-ocean-m",
  "variant_url": "https://example.com/products/harbor-linen-shirt?color=ocean&size=m",
  "color": { "display_name": "Ocean", "family": "blue" },
  "size": { "label": "M", "system": "US", "fit": "regular" },
  "material": {
    "composition": [{ "fiber": "linen", "percent": 100 }],
    "source": "supplier-spec-sheet-v4"
  },
  "care": {
    "machine_washable": true,
    "tumble_dry": null,
    "source": "approved-care-sheet-v3"
  },
  "offer": {
    "market": "US",
    "currency": "USD",
    "price": "89.00",
    "availability": "in_stock",
    "source": "inventory-service",
    "observed_at": "2026-10-13T09:15:00Z"
  }
}

Three details are worth noticing:

• display_name and family live side by side, so nothing customer-facing is lost.
• tumble_dry is null, which this contract defines as "unknown," not "no."
• Material and care each name their source, and the offer carries an observed_at timestamp. When an answer goes wrong, you can tell a stale value from a bad mapping.

This is an illustrative merchant record, not a universal feed format or an Alhena API specification. Use whatever structure your PIM or commerce platform supports, as long as these distinctions survive.

Map each fact to every destination without changing its meaning

The same approved fact reaches several destinations, each with its own field names and formats, so you need a written mapping that preserves meaning on every hop.

Most catalogs feed four destinations:

• Product pages show the selected variant's attributes and the offer that actually applies. For page-level improvements beyond data, see our PDP optimization checklist.
• Structured data expresses supported facts in schema.org properties that match what the page visibly shows.
• Merchant feeds translate values into each channel's required fields and formats.
• AI shopping assistants and connected agents receive the product facts, plus live lookups for things that change, like price and stock.

Here is how five contract values for the Harbor Linen Shirt travel:

Keep a mapping document beside the contract. For every field it records the source field, the destination field, the transformation, the values the destination can't represent, and who owns the rule.

Most destinations can't express "unknown" at all. When that happens, decide deliberately whether to omit the fact, generalize it, or carry it in page text, and write that decision down. A silent default is how meaning gets lost.

What Google says about AI features

For Google Search's AI features, Google's guidance on AI features and your website points back to fundamentals: important content available as text, structured data that matches the visible page, and current Merchant Center information. It states that no special AI markup or AI text files are needed.

That guidance is Google-specific. Other AI platforms publish their own requirements, so check each destination against its own documentation rather than assuming one rulebook covers them all.

Make "unknown" and "conflicting" explicit

A missing fact and a negative fact are different answers, and your data has to keep them apart all the way to the shopper.

Back to the shirt. The care sheet confirms machine washing but says nothing about tumble drying. If that silence becomes false, an assistant tells shoppers not to tumble dry, a claim nobody made. If it becomes true, the assistant invents a care instruction. Kept as unknown, it can confirm machine washing and say plainly that tumble drying isn't specified, which is exactly what a careful sales associate would say.

Name one authority per field

Conflicts are inevitable when facts arrive from several systems. Settle them in advance by naming the source that wins for each kind of fact:

That last row deserves emphasis. Reviews are useful evidence of how a product performs, and an assistant can draw on them, but as attributed customer feedback. A review should never quietly become an official specification.

Record when, not just what

Store two timestamps on any fact that changes: when the source last updated it and when your pipeline ingested it. When an answer is wrong, those two dates tell you whether you're looking at stale data or a broken mapping. Those are different fixes, usually owned by different teams.

For keeping fast-moving facts fresh after launch, see our guides to AI knowledge base operations and quote lag between your systems and AI answers.

Test with record, relationship, and shopper-question checks

A record can pass every format check and still describe the wrong item, so test at three levels and treat shopper questions as the final exam.

Record checks confirm each value is well formed. Required identifiers exist, measurements carry units, values come from the approved vocabulary, and unknowns are stored as explicit nulls rather than blanks.

Relationship checks confirm the records connect correctly. Each variant belongs to the right product, its URL preselects that variant, and its price, currency, and availability all come from the same offer.

Question checks ask what shoppers actually ask and compare the answer with the approved facts. For the Harbor Linen Shirt:

Rerun these tests whenever source data, mappings, or the contract version changes. Log each failure against the specific record and field, so the owning team gets a fixable ticket instead of a vague "the AI got it wrong."

Give every part of the contract an owner, and version it

A contract without owners decays within months, so assign each layer to the team closest to the truth and name one catalog owner accountable for the whole.

Customer experience is the team most often left out, and it holds the best signal. Every question your data can't answer cleanly is a candidate for a new attribute, a sharper definition, or a new test.

Version the contract when a field's meaning changes, not when a value changes. Redefining availability to include backorders is a new version. Restocking a size is not. Before any new version rolls out, review every mapping that depends on the changed field.

Where Alhena fits: from AI discovery to accurate answers in your store

A product-data contract is a merchant practice, not a product you buy, but it strengthens both places where AI meets your catalog: how shoppers find you, and how they get answers once they arrive.

Off-site discovery. AI search engines and assistants decide whether to mention your brand and products. Alhena AI Visibility measures how your brand appears across tracked prompts and AI engines, giving you an outside view to set beside your internal data checks. Our AI Visibility methodology explains how prompts are sampled and what the scores can and can't tell you.

On-site answers. Alhena's AI Shopping Assistant uses your product catalog and knowledge sources to guide discovery and answer shopper questions. The more consistent those facts are, the stronger its foundation, especially for variant-specific questions about size, stock, and care.

Track the outcomes separately, because each tells you something different:

• Data quality: whether catalog records and mappings pass validation
• Answer accuracy: whether answers identify the right variant and respect known gaps
• External visibility: whether your brand and products appear in AI answers for relevant prompts
• Commercial results: whether shoppers engage and buy

Keep attribution honest. Better data makes accurate answers possible, but a later lift in AI visibility or conversion can have several causes. Measure each layer on its own terms before crediting the contract alone.

Where to start this week

Don't try to write a contract for your whole catalog at once. Prove the method on one category, then expand.

1. Pick one category with real variant complexity and at least one product shoppers often misunderstand, such as one that drives confused support tickets or returns.
2. Choose the 10 to 15 attributes shoppers ask about most in that category.
3. Write the seven definitions for each attribute, using the machine_washable table above as your template.
4. Trace one product through every destination: page, JSON-LD, feed, and assistant. Note every place where meaning changes.
5. Run the five shopper-question tests, plus five more pulled from your own support conversations.
6. Fix what fails, update the contract, and only then roll it out to the next category.

Include a few incomplete or messy records in the pilot on purpose. A contract that only works on your best-maintained products hasn't really been tested.

Frequently asked questions

The bottom line

AI agents don't need more product data so much as product data that means one thing everywhere it goes.

Pick your most misunderstood product. Write down what its facts mean, where they come from, and what "unknown" looks like. Then follow those facts into every system that publishes them, and ask the questions your shoppers actually ask. The first product takes the longest. The method you build along the way is what scales to the rest of your catalog.