Skip to content
UCP
Menu

Resources · Essay

Catalog as API

Treating the product catalog as a deliberate API surface — versioned, typed, documented. The mindset shift, the operational implications.

Published : ·10 min read ·Primary : product catalog api

Most merchants treat their product catalog as data — a body of records stored in a PIM, synced to a storefront, exported as a feed. That framing is no longer sufficient. An agent does not consume your data as data; it consumes your catalog as if it were an API. Once you see the shift, operational practice changes accordingly.

The framing

APIs have four properties that catalogs usually do not: contract, versioning, documentation, and reliability guarantees. Agents exploit all four. If your catalog lacks them, the agent compensates through guesswork, scraping, and reduced confidence — all of which penalize your visibility.

Contract

An API contract defines what fields exist, what types they hold, what ranges they accept. A catalog contract means:

  • Every product has identifier fields (GTIN, MPN+Brand).
  • Price fields are typed (number + currency), not strings.
  • Availability is enumerated (in_stock / out_of_stock / pre_order / back_order).
  • Policies are structured objects, not prose.
  • Custom attributes have declared types and units.

The contract can live in multiple places: the JSON-LD on your PDPs, your feed schema, and — ideally — a machine-readable schema published at a stable URL. Treat it as source of truth.

Versioning

APIs version. Catalogs rarely do. The result: when a merchant changes an attribute meaning ("Shipping time" used to mean handling + transit, now just transit), every downstream consumer silently breaks. Agents that have cached older interpretations are wrong.

A catalog contract should carry a version number. Breaking changes should bump it. Non-breaking additions should be clear. Deprecations should be announced. The discipline costs little and prevents the most common silent failure mode in feed operations.

Documentation

Documentation for a catalog means:

  • A public description of every attribute you expose.
  • Unit conventions (cm vs inches, grams vs oz).
  • Enumerated values and their meanings (availability states).
  • Freshness SLAs ("inventory updated every 10 minutes").
  • Policy schemas (what fields your returns structure carries).

Most merchants write none of this. The leading ones publish it. Doing so aligns marketplaces, affiliate partners, agents — and your own internal teams.

Reliability

APIs commit to reliability. Catalogs should, too. The two measurable commitments:

  • Parity between surfaces (feed, PDP, checkout). Inconsistency is treated by agents as unreliability.
  • Freshness: a stated refresh cadence you meet.

"Our feed is updated every 15 minutes" is a commitment. "We update the feed when we remember" is a failure mode that agents measure.

Implications for operations

  1. Own a catalog change-log. Publish it where partners and agents can find it. Even a simple dated Markdown file at /catalog/changelog is better than silence.
  2. Align sources. PIM is source of truth. Feed and PDP render from it. Any divergence is a bug.
  3. Type your custom attributes. If you have "Warranty_Length" as a freeform string, convert to an integer with units.
  4. Expose a read endpoint. If agent orchestrators want to call you directly (via MCP, for example), publish a simple catalog endpoint.
  5. Measure parity. Nightly job: sample 100 SKUs, diff feed vs PDP vs checkout, alert on deltas >1%.

The mindset shift

"Catalog" sounds like a static artifact. "API" sounds like a live system with users. Once you see your catalog as a live system with external users — users who will cite you, compare you, and transact with you — the ambient discipline level rises. Fields get named better. Units get stated explicitly. Deprecations get announced. Parity gets measured. That is the whole point of the framing.

Where to go next

← All resources