The short answer is that an AI shopping agent needs a traceable product-data contract, not a longer marketing description. The contract should connect product identity, variant options, price, currency, market, availability, and freshness. It should also say what the agent must do when one of those fields is missing or contradictory. This guide is for Shopify merchants, product and data teams, cross-border operators, and QA owners who must approve an agent's inputs. It is not a marketing playbook and it is not a Storefront MCP endpoint implementation. Time-sensitive statements below are marked last verified 2026-08-30; re-test current documentation and the merchant's store configuration before publishing.
Executive answer: treat the agent as a constrained data reader
An agent should answer three separate questions before it gives a concrete recommendation: What product is this? Which purchasable variant matches the shopper's constraints? What price and availability apply to this market at the recorded time? If the feed cannot prove one of those links, the safe behavior is to lower the answer's certainty, ask a clarifying question, show the product page, or route the case to a human.
That design is more important than conversational polish. AI output may be wrong and requires merchant review. Before publishing or releasing a workflow, the merchant should review the inputs, generated answers, and downgrade logs; this rule applies to every example on this page. A complete feed does not turn an AI response into an automatically correct product fact.
Who should use this guide
Use this guide if you own a product catalog, normalize data for an agent, approve cross-border market behavior, or need to prove that a recommendation can be replayed. The minimum useful deliverable is a field dictionary, a source and freshness policy, a missing-data downgrade matrix, and a repeatable failure rehearsal.
Non-goals and prohibited assumptions
This page does not promise search ranking, AI-search citations, conversion improvement, or permanently accurate inventory. It does not define automatic payment, refund, procurement, or order cancellation. It does not claim that every AI can pay directly through a store. It also does not implement a Storefront MCP endpoint. The Storefront MCP overview is relevant only as a downstream boundary: it connects an agent to a specific Shopify store's catalog, cart, and policies, while the data contract described here is the upstream input layer. The current connection and commerce behavior must be tested against Storefront MCP overview, last verified 2026-08-30.
Scope: define “feed” before defining fields
Feed means a normalized, read-only contract here
In this article, a feed means a normalized record prepared for an AI shopping agent. It may combine Shopify product, variant, inventory, price, market, and policy references, but it is not a claim that Shopify exposes one universal AI-feed schema. The adapter should attach a source, synchronization time, market scope, schema version, and field-level handling rule. It should not expose every back-office field by default.
Product facts are not transaction actions
Product title, description, options, media, price, market, and availability help the agent explain a product before a transaction. Cart changes, checkout, payment authorization, refunds, and order changes are separate controlled actions. A feed can support an answer such as “the store record for the blue, medium variant is currently marked available,” but it cannot turn that statement into “payment will succeed” or “shipping is guaranteed.”
Separate facts, derived values, and copy
Use three explicit classes in the normalized record. fact is a value copied from a merchant-controlled source; derived is a value computed by a disclosed rule, such as a freshness class; and copy is explanatory language. The agent should prefer facts, explain the time and rule behind derived values, and never treat copy such as “great for travel” or “low stock” as proof unless the merchant has defined and approved the underlying field.
The minimum product-data contract
Shopify's product documentation identifies real product data such as price, media, variants, inventory, tags, and metafields. The exact fields available to a store and the way they are exposed still need to be confirmed in the current documentation and merchant configuration; last verified 2026-08-30. Start with Products, Product details, and Variants.
Stable identity and visibility fields
At minimum, a record should carry store_id, product_id, variant_id when applicable, product and variant display names, product status, a product-page reference, and updated_at. A title alone cannot distinguish two similarly named products or invalidate a stale answer. A stable store identifier prevents a service that serves multiple merchants from mixing catalogs.
Field metadata is part of the contract
Every value that can change the answer should carry source, last_synced_at, market_scope, schema_version, and a handling status such as verified, stale, unknown, or conflict. confidence should describe the merchant's verification state, not pretend to be an unexplained model probability. Internal notes, supplier costs, and customer data should be explicitly filtered from the agent-facing record.
Field dictionary: product, variant, inventory, price, and market
The following is a proposed normalized contract for this page. It is not a Shopify API schema. Field names, permissions, and synchronization behavior must be re-tested in a development environment.
| Domain | Suggested fields | What the agent may answer | Missing or untrusted behavior | Acceptance check |
|---|---|---|---|---|
| Product | store_id, product_id, title, status, page reference | Identify the product and point to its page | Do not make a definite recommendation | IDs are stable and scoped to one store |
| Product facts | description, type, tags, approved metafields | Explain approved use, material, or specification facts | Use only traceable facts; do not infer properties from tags | Each important field has a defined owner/source |
| Media | media reference and approved alt text | Say that approved media is available | Do not infer color, size, or performance from an image | Product and variant media associations match |
| Variant | variant_id, option names, option values | Match color, size, capacity, or package | Ask for the missing option; stop at product level | Each candidate option set resolves to one variant |
| Price | amount, currency, price type, price update time | Show a market-scoped, time-bounded price | Block a definite amount without currency or market | Amount, currency, market, and time travel together |
| Inventory | controlled availability status or quantity, location scope, freshness | State the recorded availability condition | Use unknown/stale downgrade; do not guarantee stock | Status, scope, and synchronization time are traceable |
| Market | market ID, country/region, locale, domain or path | Explain which market and language context applies | Ask for the market before quoting localized price | Language is not silently treated as market |
| Policy reference | shipping and returns policy references and versions | Point to the applicable visible policy | Route to human or policy page when version is unclear | Reference and visible policy agree |
| Quality metadata | source, sync time, schema version, redaction state | Control freshness and replay | Lower answer level if metadata is absent | Input snapshot can be reconstructed |
Product-level data: identify what is being sold
The product layer gives the agent a semantic candidate set. It does not prove that every color, size, or package is available. A description that says “multiple colors” is not evidence that every color has current stock, and an unqualified phrase such as “ideal for travel” does not prove a weight or compatibility requirement.
Identity and status must filter the candidate set
Use product_id for internal linkage, title for display, and status for public visibility rules. A product-page reference alone is not enough to establish that an item can be recommended in the current market. If the agent cannot confirm the store, product identity, or public status, it should hide the record, offer a safe page-level path, or create a review item.
Descriptions, tags, and metafields need definitions
Descriptions, types, tags, and metafields can carry material, size, compatibility, care, or other merchant-defined facts. The adapter should document what each field means. A material metafield and a care_instruction metafield are both text, but they must not be treated as interchangeable. If two sources conflict, preserve the conflict and its timestamps; do not let the model vote between them.
Media is not an automatic measurement source
Media and alt text can explain what the merchant has approved for display. They should not become an excuse for the model to infer exact color, dimensions, composition, or performance. Keep media associations explicit and test the relationship between the displayed image, the variant option, and the product record.
Variant-level data: make a recommendation purchasable
The common failure is a persuasive product answer that cannot resolve to a purchasable variant. If a product has size, color, capacity, package, or other choices, the recommendation must either resolve to one verified variant_id or clearly remain at product level while asking the shopper to choose.
Preserve option names and values as pairs
Do not flatten a choice into an opaque string such as “blue / M / 500 ml.” Preserve the relationship between option names and values. A record may represent it as an ordered list of name/value pairs; the exact serialization is an implementation choice that must be re-tested. Empty, duplicated, or mismatched option names should force a clarification rather than a guessed SKU.
Keep variant identity separate from customer language
variant_id is the system link. A SKU may be useful for internal review, but whether it should be shown to customers is a merchant decision. The agent should speak in approved option values, not expose internal codes as product names. Price and availability must be stored and evaluated at variant level when they differ by variant.
Treat documented limits as changeable constraints
The research pack records that Shopify's current documentation describes up to three variant options and up to 2,048 variants for one product. This is a time-sensitive product limitation, last verified 2026-08-30, and must be re-tested against the current Variants documentation and the merchant's configuration. Do not present it as an eternal guarantee. When a catalog is too complex to keep verified, limit the agent to approved combinations and provide the product-page path rather than inventing combinations.
Inventory and price: freshness must be explicit
“Real-time inventory” has no safe meaning without a source, scope, and synchronization time. Inventory may be represented by a controlled status or a quantity with a defined location scope. Prices likewise need a market, currency, price type, and timestamp. The merchant defines its acceptable freshness threshold; the threshold is not a universal Shopify guarantee.
Availability status is safer than unexplained quantity
Use controlled states such as in_stock, out_of_stock, preorder, backorder, or unknown only if the merchant defines what each state means. If a quantity is shown, record its scope and time. A low-stock threshold is a merchant rule, not a universal platform rule in this article. If freshness is unknown, use unknown; do not turn uncertainty into availability.
Freshness participates in answer selection
Carry source_updated_at, last_synced_at, and a merchant-defined freshness class. A store may define a stale threshold for its workflow, but that threshold must be confirmed and tested. When a record is stale or freshness_unknown, the agent can say that availability needs confirmation, offer the product page, or route to a human. It should not keep quoting an old snapshot as current stock.
Price requires a market and currency
The minimum price context is amount, currency, market ID, price type, and update time. A number without a currency and market is not an executable customer answer. Do not guess USD, CNY, or another currency. Do not calculate a current promotion or exchange rate from model knowledge unless the merchant supplies an approved source and validity window.
Current stock cannot be replaced by another metric
An agent answering “can I buy this now?” must use a current, traceable availability state, scope, and synchronization time. Historical records, estimates, or model-generated judgments cannot replace the current inventory field, and they must not be presented as a real-time stock guarantee or an automatic procurement trigger. When the current state is missing, stale, or conflicting, use the downgrade matrix below.
Inventory and price decision table
| Situation | Minimum input | Safe answer | Do not say | Failure signal and response |
|---|---|---|---|---|
| Variant is available and fresh | Unique variant, market, currency, status, sync time | State the matched options and recorded availability | “Stock cannot change” or “shipping is guaranteed” | Re-check if the state changes before a controlled transaction |
| Variant is known but market is missing | Variant identity and availability, no market | Ask for country/region; provide the product page | Apply a default market price silently | Block a localized price assertion |
| Inventory is stale | Variant identity and stale freshness state | Say availability needs confirmation | Continue using an old quantity | Downgrade to unknown and refresh or escalate |
| Amount has no currency | Amount only | Do not quote a definite price; request context | Guess a currency or exchange rate | Block price output until currency is bound |
| Multiple variants have no option mapping | Product and several variant IDs | Describe the product and ask the shopper to choose | Select the first variant | Record variant_not_unique |
| Variant is explicitly unavailable | Unique variant, status, time | State the recorded unavailable status and offer an approved alternative | Promise a restock date | Create review event if page and feed disagree |
Market context: one product is not one global offer
Cross-border data needs separate fields for language, market, domain or path, currency, tax notice, shipping, and returns policy. Language describes how the shopper reads; market selects the relevant offer and policy context. The research pack records that Shopify documentation describes different URLs for languages and that multi-currency payment-processor conditions may depend on options such as Shopify Payments or Adyen; these statements are last verified 2026-08-30. Review Markets, Localization and translation, International SEO for Markets, and Currencies for Markets before release.
Confirm the market before selecting a price
If a shopper asks “How much is this?” without a market context, ask for the country or region before quoting localized price, tax notice, delivery, or returns. Do not silently derive market from interface language. A language can be reused across markets, and a market can support more than one language. Keep locale and market_id separate.
Translation does not create a new variant
Localized display values may change how an option is written, but they do not create another variant_id. Preserve the original value and its approved display value. If a translation is missing, use the merchant-approved fallback language and flag the content for review; do not invent a specification, safety property, or care instruction.
Policy references must be traceable
Shipping and returns references should include the applicable market and a policy version or update time. If the link or version cannot be confirmed, direct the shopper to the visible policy page or a human. This guide does not provide regional legal advice. The store owner must validate tax, shipping, returns, and any market-specific policy language.
Missing fields: downgrade from a precise recommendation to a safe answer
The downgrade rules should be deterministic and written into the adapter or orchestration layer. Do not ask the model to improvise a policy every time a field is absent. A practical scale is L0 verified variant recommendation, L1 verified product-level candidate, L2 bounded clarification, and L3 human or official-page handoff. The level describes what the input proves, not how confident the model sounds.
Missing product identity or status
Without a stable product identity or a confirmed public status, do not recommend the record. If identity is valid but descriptive content is missing, the agent may state only the approved fields and say that more detail needs merchant confirmation. It must not fill the gap from a similar product's copy, image, or tag.
Missing variant mapping
Without variant_id, option names, option values, or a unique option-to-variant mapping, stop at product level. Ask for color, size, capacity, or package, or direct the shopper to the product page. Never choose the first variant as a default merely because it is first in the payload.
Missing or stale inventory
No inventory field or no synchronization time means availability=unknown. Zero is a defined unavailable state; unknown is not an available state. The agent may say that the store page or human team must confirm availability, but it must not say “in stock,” “ready to ship,” or “only X left” without the required evidence.
Missing price context
Without amount, currency, market, or a valid update time, block a definite price. Ask for the market or direct the shopper to the product page. If a normal price exists but a promotion is missing, show only the merchant-approved normal price if that behavior is defined; do not infer a discount or expiration.
Conflicting records
When the product page, variant field, and inventory or price sources disagree, mark the field conflict, preserve both values and timestamps, and stop the definite assertion. The human review should resolve the field and source priority; it should not require rewriting the whole product. Keep the input snapshot, rule version, response ID, and final decision for replay.
Missing-data downgrade matrix
| Missing or conflicting condition | Maximum answer level | Customer-facing direction | System or human action | Hard boundary |
|---|---|---|---|---|
| Product identity missing or status unknown | L3 | Do not confirm the item; offer a safe entry point | Isolate the record and inspect the catalog sync | No recommendation or guessed URL |
| Description missing, purchase fields complete | L1 | State only approved identity, option, price, and recorded status | Open a content-completion task | No invented material, use, or compatibility |
| Option mapping missing or non-unique | L2 | Ask the shopper to select a specification | Record the clarification reason | No default SKU or merged variant |
| Inventory unknown, stale, or location unclear | L2 | Availability needs confirmation | Refresh or route to human | No stock or dispatch guarantee |
| Currency, market, or price time missing | L2 | Ask for market context or open product page | Rebind a market price | No guessed currency or promotion |
| Policy reference missing or conflicting | L3 | Use the visible policy entry or human route | Lock the old answer and update reference | No regional legal conclusion |
| Sources disagree | L3 | Pause the definite claim | Create a conflict event with evidence | No model vote to erase conflict |
A repeatable request-to-answer workflow
Step 1: establish request context
Record store, market, locale, shopper constraints, and request time before selecting products. If country or region is absent, set market to unknown; do not silently reuse a previous session's market unless the merchant has defined that behavior and its consent and retention controls.
Step 2: select products, then expand variants
Filter by public product status and explicit shopper requirements first. Expand each candidate into its option mapping and variants. Preserve exclusion reasons such as market mismatch, missing size, stale inventory, or missing price context. This allows a reviewer to explain why a candidate was removed rather than seeing only an opaque final answer.
Step 3: bind market price and inventory
For every candidate variant, bind a price with currency and market, an availability state, a scope, and synchronization time. A failed binding lowers the answer level. “Real-time” is a merchant-defined freshness claim that must be measured; the agent should say “the store record at [time] shows…” rather than guarantee stock at checkout.
Step 4: run hard checks before generation
Check that the variant is unique, price has currency, market is explicit, freshness is acceptable, policy references are applicable, and internal or customer-sensitive fields have been redacted. If a check fails, give the shopper a next action: choose a market, select an option, open the product page, or contact a human.
Step 5: re-check at the transaction handoff
If the flow proceeds to a cart or checkout action, re-read key product, variant, price, and availability fields within that controlled flow. Do not reuse the first conversation snapshot. This is a data handoff principle, not an MCP implementation. Endpoint, tool, authentication, and checkout behavior belong to the separate implementation scope and must be re-tested against current documentation.
Failure rehearsal and rollback runbook
The following is a reproducible runbook/test scenario, not a customer case study. It tests stale inventory and a non-unique variant mapping in a development store or offline fixture.
Scenario A: stale inventory is incorrectly answered as available
Create a fixture with one product and two variants. Make blue/M exceed the merchant-defined freshness threshold, while black/M has a fresh availability record. Give both records a market and currency. Send the request: “I need size M; which color can I buy now?” Expected behavior: blue/M is stale or unknown; black/M may be recommended only if its recorded status is available. The response must include the data-time qualification and must not guarantee stock, dispatch, or checkout.
Scenario B: missing option mapping produces a guessed SKU
Remove option_names and option_values while retaining the product title, two variant IDs, price, and market. Ask for the blue version. Expected behavior: the agent does not return an arbitrary variant; it asks for clarification or opens the product page and logs variant_not_unique. If the agent returns one variant anyway, the test fails and the rule layer must block the response.
Rollback and re-test sequence
- Mark the affected field
unknownorconflictand stop definite answers. Preserve the raw fixture, timestamps, schema version, rule version, and response ID. - Inspect the development catalog, variant mapping, inventory source, price context, and market mapping in read-only mode. Do not patch an unreviewed production environment during the test.
- Correct the upstream fixture or synchronization input, then run both scenarios plus one complete-data positive sample. Release the downgrade only after hard checks, human sample review, and log replay pass.
- If stock or price cannot be confirmed, keep the lower answer level and provide the product-page or human route. Do not restore a definite answer just to pass a demo.
Acceptance and monitoring
Contract completeness
For each feed build, count missing required fields, duplicate IDs, broken product-to-variant links, missing currency, missing market mapping, stale inventory, missing policy references, and unredacted internal fields. Report counts and failed samples; do not replace them with an unsupported growth or conversion percentage.
Semantic and factual sampling
Sample different markets, locales, product types, option combinations, and availability states. A reviewer should compare the product page, variant selector, displayed price, market context, and recorded availability. Store the reviewer, time, input snapshot, and decision. A passing sample does not make AI output self-auditing; it only shows that the chosen sample passed the current contract.
Freshness and conflict monitoring
Track synchronization time distribution, records beyond the merchant threshold, conflicts per variant, requests downgraded for unknown state, handoffs to humans, and repeated market or option clarification. These are operational indicators, not ranking or revenue guarantees. If stale inventory rises, pause definite availability answers, diagnose the data path, and keep the downgrade in place until re-tested.
Visible content and structured-data consistency
If the published page or product page uses Product or Article structured data, it must describe content that is visible and supported. Do not invent an “AI/GEO schema,” hide unshown inventory quantities in structured data, or expose model confidence as a product fact. There is no extra GEO-specific schema that replaces basic crawlable, indexable, human-useful content. The structured-data assertion must match the visible content, and the lead reviewer must compare the visible fields with the markup before release. This page makes no AI-search citation guarantee.
Where this page fits in the Shopify AI hub
This page owns the upstream product-data contract and safe downgrades. Link to the neighboring intents without collapsing them:
- Storefront MCP search, cart, and checkout boundaries: downstream tools, permissions, and transaction handoff; this page supplies the input contract only.
- Shopify AI localization, currency, and market-policy QA: locale, market, URL, currency, tax notice, and returns validation; this page defines the market fields the agent must receive.
- Hydrogen AI shopping-agent architecture: Liquid versus Hydrogen, rendering, caching, and architecture; this page does not prescribe a frontend stack.
These links are complementary, not canonical consolidation. Data readiness, MCP implementation, market QA, and headless architecture are distinct search intents.
Frequently asked questions
1. What fields are required before an AI shopping agent can recommend a specific variant?
Use stable store and product identity, a unique variant ID, option names and values, market context, currency, price, availability, and synchronization time. Source and schema metadata are also needed for replay and downgrade decisions. If the agent cannot bind one option combination to one variant, it should stay at product level or ask for clarification. These field names are a proposed contract, not a universal Shopify AI-feed schema.
2. Can a Shopify inventory field be described to shoppers as real-time stock?
Not without a merchant-defined freshness policy. The agent can report what a specific source recorded at a specific synchronization time. When the record is stale or its time is unknown, it should say that availability needs confirmation and provide a page or human route. It should not guarantee stock, dispatch, or checkout success.
3. May the agent choose the first variant when option mapping is missing?
No. It may recommend the product as a candidate, but it should not select an arbitrary variant. Missing option mapping means the system cannot prove that the shopper's requested color, size, or capacity resolves to that SKU. Ask for the missing choice or direct the shopper to the product page, and log variant_not_unique.
4. Does a translated product title represent a different market offer?
No. Translation changes the display value; it does not create a new variant or market price. Keep locale and market_id separate, then bind price, currency, URL or path, shipping, and returns context to the market. If the translation is missing, use an approved fallback and flag it for review rather than inventing specifications or policy language.
5. Is this article a Storefront MCP shopping-agent implementation guide?
No. It defines the upstream product, variant, inventory, price, and market contract plus missing-data behavior. It does not implement an endpoint, tool call, authentication flow, or checkout. Those capabilities must be tested separately against the current Storefront MCP documentation and the merchant's development environment.
Sources and freshness boundary
This draft uses only the first-party sources listed in the supplied research card. Volatile limits, market behavior, currency conditions, and downstream MCP boundaries are marked last verified 2026-08-30 and must be checked again before publication. If a field, limit, permission, or availability cannot be confirmed, say “re-test the current official documentation / confirm with the merchant” rather than inventing a fixed answer. AI output still requires merchant review, and this page makes no legal, transaction-security, ranking, or growth guarantee.