Product Data for Machines: Structuring a MedusaJS Catalogue for AI Shopping Agents

A shopper who lands on a product page fills the gaps themselves. They read the photograph, infer the material from the brand, assume the delivery estimate applies to their postcode, and ask if they are unsure.

An agent buying on that shopper's behalf does none of this. It reads what you have published in a structured form, and everything absent is — as far as it is concerned — not true. If your material attribute is populated on 40% of SKUs, you are invisible for 60% of material-filtered queries. If delivery windows are prose, they cannot be compared.

For anyone running MedusaJS, this is a favourable position to be in: you control the data model and the API surface directly rather than negotiating with a platform's opinions. Here is what to do with that.

Attributes Are the Product Now

In a Medusa catalogue the temptation is to let the storefront carry meaning that the data does not — a nicely designed spec table assembled from a description blob. That works for humans and fails for machines.

The discipline:

• Model attributes as first-class, typed data, not as free text in a description. Whatever a customer might filter, compare or ask about needs its own field.
• Use a controlled vocabulary. Three thousand distinct free-text colour values group into nothing. Twenty-four defined options group into a usable filter and a comparable attribute.
• Populate identifiers. GTIN, MPN and brand are how your product is matched against the same product elsewhere. Missing identifiers mean an agent cannot confirm it is looking at what it thinks it is.
• Express units explicitly. 2.5 is not a length. 2.5 m is.
• Be honest about variants. If size and colour are genuinely independent, model them independently rather than as a flat list of pre-combined options.

Most of this is the same catalogue work that improves on-site search and faceted navigation, which is the reassuring part — it pays off whether or not agent traffic ever materialises for your category. We describe the enrichment pipeline itself in cleaning a large catalogue with AI; the example platform differs, the method does not.

Availability Has to Be True, Not Optimistic

This is where agent channels punish stores that humans forgive. A person who orders something marked in stock and receives a delay email is mildly annoyed. An agent that transacted on that basis has made a commitment on a customer's behalf using information you published as fact.

• Expose real inventory, per location if you fulfil from more than one — Medusa's inventory module supports this properly, so use it rather than flattening to a single number.
• Publish a delivery expectation you would stand behind, computed from location and stock state rather than a static promise in a CMS block.
• Distinguish out of stock from discontinued. They imply completely different agent behaviour.
• Keep the freshness tight. A cached availability value that is an hour stale is a wrong answer delivered confidently.

Policies Must Be Data, Not PDFs

Returns windows, warranty terms, shipping thresholds and restrictions are usually a page of prose written by someone in legal. An agent asked can my customer return this needs a structured answer.

At minimum, make machine-readable: the returns window in days, who pays return shipping, which categories are excluded, the warranty period, the free-shipping threshold, and any destinations you will not ship to. Publish them as structured fields your API can return, and — separately — as schema.org markup on the storefront, so both channels agree.

The commercial reason is blunt: an agent comparing two products where one publishes a 30-day returns policy and the other publishes nothing will favour the one it can reason about.

The API Surface an Agent Needs

Medusa's Store API is resource-shaped, which is right for a storefront and wrong for an agent. An agent wants task-shaped operations: find me products matching this description, tell me if this is available in this size to this postcode, what is the returns position on this.

Build a thin layer over your Medusa modules that exposes those operations, and treat that layer as its own product with its own design standards. We set out how to design it — including what must never be exposed — in your product needs an MCP server.

Two Medusa-specific notes. First, the module system makes this genuinely pleasant: the agent-facing layer is a consumer of your product, inventory and pricing modules rather than a fork of them. Second, keep it separate from the storefront's API — the access patterns, rate limits and permission model are all different, and merging them makes both worse.

Being Found Versus Being Bought From

These are two different projects and teams routinely conflate them.

• Being found — an assistant recommends your product in an answer. Driven by crawlable, structured storefront data: schema.org markup, clean product pages, real content, and a crawler policy that permits the right agents. Mostly an SEO-adjacent discipline.
• Being bought from — an agent completes a purchase against your systems. Driven by API design, authentication, payment handling and the emerging protocols.

The first is available to every store today and has a clearer near-term return; we cover it in getting your products recommended by ChatGPT and Perplexity. The second is where the standards are still moving. Do the first now regardless.

A Sensible Order of Work

1. Audit attribute completeness across the catalogue and rank attributes by whether search, filtering or comparison actually uses them.
2. Fix the controlled vocabularies before enriching anything — otherwise you are adding rows to an inconsistent taxonomy.
3. Enrich the gaps, sampling the output rather than trusting it wholesale.
4. Structure the policies and publish them both as API fields and as storefront markup.
5. Verify availability accuracy against reality for a month. If it is wrong for humans, it will be wrong for machines faster and more publicly.
6. Then build the agent-facing API layer, and only then worry about which protocol to speak.

Steps one to five are worth doing whether or not agent commerce becomes significant in your category, which is what makes them a safe investment in an area where nothing else is settled.

Our MedusaJS practice and Medusa development team build these catalogues and the interfaces over them, with our AI engineering team on the model-facing side and our broader AI integration work covering where this fits in a commercial strategy.

Start With the Attribute Audit

Send us your Medusa catalogue's attribute fill rates and we will tell you what an agent can and cannot currently see. It is usually less than teams expect. Talk to our team; we reply within a business day.