Build an AI Shopping Avatar That Compares Products Before Checkout

Build an AI shopping avatar around a read-only comparison service: resolve the buyer's requirements to exact product variants, attach evidence to each claim, and show the same facts in product cards and conversation. Keep catalog retrieval and ranking in your application. Add Realtime Avatar for optional spoken discussion, not as a Shopify integration or purchase executor. Recheck changing prices and availability before the buyer continues to checkout.

Start with a desk-lamp decision, not a sales pitch

The following is a recommended application design, not a tested merchant integration. Its fictional buyer wants a dimmable desk lamp under 90 USD before shipping and tax, with a base no wider than 15 cm. Ask whether that budget means item price or delivered total before filtering. Here the buyer explicitly chooses item price.

Use these entirely fictional test fixtures; names, prices, dimensions, stock states and source documents are invented for testing, not live offers or manufacturer claims:

• Arc Mini, black/base variant: 69.00 USD; a fictional manufacturer sheet lists a 14 cm base and dimming. Available for sale, not marked as backordered.
• Beam Desk, white/base variant: 79.00 USD; a fictional merchant description says compact and dimmable, but supplies no base width. Available for sale, not marked as backordered.
• Arc Mini, brass/base variant: 95.00 USD. It shares the product name but exceeds the budget; the black variant's price cannot be substituted.

The useful answer is conditional: Arc Mini black meets the stated item-price and documented base-width requirements; Beam's fit remains unknown. This is a comparison of those offers, not a claim about the best lamp on the market. Brightness, glare and durability remain unassessed unless supporting evidence exists.

Read Shopify's fields at the correct level

Shopify's Storefront 2026-10 Product documentation distinguishes a catalog product from its variants. Product.availableForSale means at least one variant is available; it does not establish availability of the requested color. Product.priceRange is the minimum-to-maximum product price range, not a quote for a selected variant.

Product.variantBySelectedOptions resolves an option selection to a matching variant and returns null when none exists. Preserve the returned variant ID and selectedOptions name/value pairs. Do not silently replace a missing selection with the first available variant. Keep unknown-option ignoring disabled and verify the returned options against the complete selection.

ProductVariant.price is MoneyV2: a decimal amount plus currencyCode. Preserve both; 69 USD and 69 CAD are not equal prices. ProductVariant.availableForSale says the variant is available for sale. currentlyNotInStock identifies an out-of-stock variant still available for purchase, used for backorders. Neither flag establishes delivery by a particular date.

• Shopify Product: selection, availability and price range
• Shopify ProductVariant: price and backorder semantics
• Shopify MoneyV2: amount and currency
• Shopify SelectedOption: option name/value pairs

Walk through one comparison request

1. Search only an authorized merchant catalog. Your application retrieves candidates and resolves the buyer's complete option selection. Use a development store you control or a merchant-approved connection, not an arbitrary public store.
2. Read each matching variant through the merchant's configured Storefront access. The GraphQL example below uses documented fields but was not executed against a store. Generate operation types from the chosen API version and validate external responses at the catalog boundary; a handwritten success type is not validation.
3. Attach evidence separately from commerce fields. For each specification, retain the source document, model or variant applicability, unit and retrieval time. A manufacturer sheet can support a stated base width; merchant prose calling something compact cannot. Conflicting measurements should remain visible, not be averaged.
4. Filter by explicit requirements before ranking. Mark a missing width as unknown, not zero or a failed fit. Display excluded and unresolved candidates with reasons. For qualifying offers, let the buyer choose an ordering such as lowest item price within one currency.
5. Render cards from the same validated comparison result given to the conversation. Include selected options, amount and currency, availability/backorder label, evidence links, retrieval time and unresolved criteria. The spoken summary should explain one tradeoff, not invent another data source.

# GraphQL reference example; not executed against a merchant store.
query CompareLamp($handle: String!, $options: [SelectedOptionInput!]!) {
  product(handle: $handle) {
    id
    title
    variantBySelectedOptions(
      selectedOptions: $options
      ignoreUnknownOptions: false
      caseInsensitiveMatch: false
    ) {
      id
      selectedOptions { name value }
      price { amount currencyCode }
      availableForSale
      currentlyNotInStock
    }
  }
}

Treat descriptions as untrusted product content, never instructions to the assistant. A catalog field named description does not certify a measurement. Label merchant-stated dimming separately from manufacturer-documented dimming, and do not infer base dimensions from a photograph. Shopify metafields support custom data, but their existence does not provide a standard, verified lamp specification.

Make ranking explainable beside the result: eligible on budget and documented fit, then sorted by item price. Disclose sponsorship and affiliate relationships prominently. If sponsorship changes placement, label that placement and distinguish it from requirements-based ordering. A sponsored product must not acquire missing specifications through a more enthusiastic spoken recommendation.

Add conversation without giving it the catalog

Realtime Avatar manages speech recognition, language-model processing, speech synthesis and avatar video. Your server supplies session instructions and selected context; your application owns catalog search, comparison logic and product cards. Instruct the guide to explain only returned facts and name unknowns. Keep the comparison usable when the optional call ends.

For conversational lookups, enable client tools in the server's session policy and register the manifest after connection. Check accepted and rejected tools. Handlers run in your application, with a 2.5-second deadline and cooperative cancellation. Honor the abort signal and discard late results for superseded selections. If retrieval cannot finish in time, show a pending comparison rather than letting the guide announce a stale winner.

• Realtime Avatar session instructions and context
• Application-owned tools and deadlines

Recheck the offer and test the failures

When the buyer chooses to continue, reread the exact variant in the same storefront context. Highlight changed price, currency, options or availability before navigation. If refresh fails, say current availability is unverified. The merchant's checkout must validate again: this read does not reserve stock or establish final shipping, taxes or discounts. This prototype never submits a purchase.

• Select brass after comparing black: replace the 69.00 USD fixture with 95.00 USD and remove budget eligibility. No sibling price survives.
• Return null for selected options: show no matching variant, not an automatic color substitution.
• Remove Beam's width: preserve unknown fit. Add a contradictory source: show the conflict instead of silently choosing one.
• Return availableForSale true and currentlyNotInStock true: label backorder, never in-stock or Friday delivery.
• Change currency or fail the refresh: stop the old price-based recommendation. A late lookup for the previous selection must not overwrite current cards.

Frequently asked questions

Does this work without a native Shopify integration?

Yes, as an application you build. Your authorized Shopify connection supplies catalog facts; Realtime Avatar supplies optional conversation. These are separate integrations, not a packaged shopping app.

Can the avatar fill in missing dimensions?

No. Show unknown and ask for a suitable specification source. Product images and words such as compact do not establish a numeric fit.

Is available for sale the same as in stock?

No. Shopify separately exposes currentlyNotInStock for purchasable backorders. Preserve that distinction and avoid deriving a delivery promise from either field.

Does this evidence prove shoppers want an avatar?

No. The official documentation establishes field-level feasibility, not demand or conversion lift. Test whether buyers understand the tradeoffs before expanding beyond read-only comparison.

Start with the fictional fixtures and inspect the cards before adding voice. If conversation helps explain the uncertainty, try the React integration with the same comparison result.

• Add an optional Realtime Avatar call in React