Reference Architecture for a UCP-Ready E-commerce Stack
A five-layer reference architecture for building an ecommerce stack that AI shopping agents can discover, query, and transact against — from data ingestion to the agent interface.
Building an ecommerce stack that is compatible with AI shopping agents is no longer a theoretical exercise. As protocols like UCP, ACP, and MCP mature, the technical requirements for a merchant's infrastructure are becoming concrete. This reference architecture describes five layers that a UCP-ready ecommerce stack should implement, from data ingestion to the agent interface.
This guide is for engineering leads, solution architects, and technical product managers who need to evaluate their current stack against agentic commerce requirements. It is opinionated: rather than covering every possible configuration, it focuses on the architecture patterns that are most likely to succeed based on current protocol specifications and early adopter implementations.
What Is a UCP-Ready Stack?
A UCP-ready ecommerce stack is one where product data flows from source systems through enrichment and normalization into a structured catalog that AI agents can query, compare, and transact against via standardized APIs and protocols.
Layer 1: Data Ingestion
The ingestion layer is where raw product data enters your commerce system from multiple sources. Most merchants underestimate the complexity here because they think of product data as a single feed. In practice, a mid-market merchant pulls data from:
- PIM systems — Akeneo, Salsify, Syndigo, or native platform fields
- ERP / inventory systems — Real-time stock levels, warehouse locations, fulfillment rules
- Pricing engines — Dynamic pricing, promotional rules, currency conversion
- Supplier feeds — Dropshipping catalogs, manufacturer data sheets
- User-generated content — Reviews, Q&A, customer photos
Architecture Requirements
- Unified product identifier — Every SKU needs a stable internal ID that maps to GTINs, MPNs, and platform-specific IDs. Without this, enrichment and syndication create data conflicts.
- Event-driven updates — Price changes, inventory movements, and content updates should propagate via events (webhooks, message queues) rather than batch jobs. Agents penalize stale data.
- Schema validation at ingestion — Reject incomplete records at the point of entry. A product missing required attributes should not reach the catalog layer.
// Example: Ingestion validation schema (simplified)
{
"required": ["sku", "title", "brand", "price", "currency", "availability"],
"properties": {
"sku": { "type": "string", "minLength": 1 },
"title": { "type": "string", "minLength": 10, "maxLength": 150 },
"brand": { "type": "string" },
"price": { "type": "number", "minimum": 0.01 },
"currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
"availability": { "enum": ["in_stock", "out_of_stock", "preorder"] },
"gtin": { "type": "string", "pattern": "^[0-9]{8,14}$" },
"images": { "type": "array", "minItems": 1 },
"category": { "type": "string" },
"attributes": { "type": "object" }
}
}Layer 2: Structured Catalog
The structured catalog is the canonical representation of your products. This is where raw data becomes agent-readable. The catalog must serve both human-facing storefronts and machine-facing APIs with consistent data.
Key Design Principles
- Separate Products from Offers — Following Klarna's Agentic Product Protocol pattern, products (static identity) and offers (dynamic pricing/availability) should be distinct entities. This allows agents to compare the same product across merchants.
- Category taxonomy must be explicit — Do not rely on breadcrumbs alone. Define a formal taxonomy that maps to Google Product Category, Schema.org types, and industry standards.
- Variant handling must be structured — Color, size, and configuration variants need explicit relationships, not just separate SKUs with similar titles.
Catalog Data Model
// Simplified catalog entity relationships
Product {
id: string // Internal stable ID
gtin: string // Global Trade Item Number
brand: Brand
title: string // Descriptive, keyword-rich
description: string // Substantive, not marketing fluff
category: Category // Formal taxonomy node
attributes: Map // Category-specific attributes
variants: Variant[] // Color, size, configuration
media: Media[] // Images, videos, 3D models
reviews: ReviewAgg // Aggregate rating + count
}
Offer {
product_id: string
seller: Organization
price: Money
availability: Enum
condition: Enum
shipping: ShippingPolicy
returns: ReturnPolicy
fulfillment: FulfillmentOption[]
valid_until: DateTime
}Layer 3: Enrichment
Raw catalog data is rarely sufficient for AI agents. The enrichment layer transforms adequate product data into agent-optimized data by adding context that agents need to make confident recommendations.
Enrichment Functions
| Function | Input | Output | Why Agents Need It |
|---|---|---|---|
| Schema.org generation | Catalog entity | JSON-LD markup | Enables structured parsing of PDPs |
| Attribute normalization | Raw attributes | Standardized key-value pairs | Makes cross-merchant comparison possible |
| Use-case tagging | Product description | Scenario labels ("camping", "office", "gift") | Matches products to intent-based queries |
| Compatibility mapping | Product specs | Compatible product IDs | Answers "will this work with" queries |
| Policy summarization | Legal policy text | Structured policy data | Enables trust assessment without parsing legalese |
| Review synthesis | Individual reviews | Sentiment summary + key themes | Provides quick quality assessment |
For Schema.org generation at scale, Schema App provides automated markup management. For product data enrichment and feed syndication, Feedonomics handles normalization across channels. Discovery and search enrichment can be handled by Bloomreach Discovery or Algolia AI Search.
Schema.org Output Example
The enrichment layer should generate complete Product + Offer JSON-LD for every PDP:
{
"@context": "https://schema.org",
"@type": "Product",
"name": "TrailMaster Pro 65L Hiking Backpack",
"brand": { "@type": "Brand", "name": "SummitGear" },
"description": "65-liter internal frame hiking backpack with rain cover, hydration sleeve, and adjustable torso length. Designed for 3-7 day backcountry trips.",
"sku": "SG-TMP65-GRN",
"gtin13": "0123456789012",
"image": [ "https://example.com/images/trailmaster-pro-65-green.jpg"],
"offers": {
"@type": "Offer",
"price": "249.99",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock",
"seller": { "@type": "Organization", "name": "SummitGear" },
"shippingDetails": {
"@type": "OfferShippingDetails",
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"businessDays": { "@type": "QuantitativeValue", "minValue": 3, "maxValue": 5 }
},
"shippingRate": { "@type": "MonetaryAmount", "value": "0", "currency": "USD" }
},
"hasMerchantReturnPolicy": {
"@type": "MerchantReturnPolicy",
"returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
"merchantReturnDays": 60,
"returnFees": "https://schema.org/FreeReturn"
}
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.7",
"reviewCount": "412"
}
}Layer 4: API Layer
The API layer is how agents interact with your catalog programmatically. Relying on HTML scraping is fragile and limits what agents can do. A well-designed API layer makes your catalog a first-class data source for AI agents.
API Design for Agents
- Product search endpoint — Filterable by category, attributes, price range, availability. Return structured product + offer data.
- Product detail endpoint — Full product entity including variants, reviews, policies, and related products.
- Inventory check endpoint — Real-time availability for specific SKU + location combinations.
- Cart creation endpoint — Programmatic cart assembly with product IDs and quantities. Returns a checkout URL or session.
- Capability descriptor — A machine-readable document (following UCP patterns) describing what your API supports.
Capability Descriptor Example
UCP uses capability descriptors so agents know what a merchant supports before initiating a transaction:
{
"merchant": "SummitGear",
"protocol_version": "ucp-1.0",
"capabilities": {
"product_search": true,
"real_time_inventory": true,
"cart_creation": true,
"express_checkout": [ "shop_pay", "apple_pay", "google_pay"],
"guest_checkout": true,
"return_policy_structured": true
},
"payment_handlers": [ "stripe", "shop_pay"],
"supported_currencies": [ "USD", "EUR", "GBP"],
"endpoints": {
"catalog": "https://api.summitgear.com/v1/products",
"inventory": "https://api.summitgear.com/v1/inventory",
"cart": "https://api.summitgear.com/v1/cart"
}
}Merchants already on Shopify can leverage the Shopify Commerce for Agents toolkit, which is building native UCP compatibility into the platform.
Layer 5: Agent Interface
The agent interface is the outermost layer — the surface that AI shopping agents actually interact with. It sits on top of the API layer and handles protocol negotiation, authentication, and response formatting.
Interface Components
- Protocol negotiation — Determine which protocol the incoming agent speaks (UCP, ACP, MCP) and respond accordingly.
- Agent authentication — Verify the agent's identity and permissions. Early implementations use API keys; UCP defines richer authentication patterns.
- Response formatting — Return data in the format the agent expects — JSON-LD for web crawlers, structured API responses for direct integrations, or protocol-specific payloads for UCP/ACP.
- Rate limiting and monitoring — Distinguish between authorized agents, web crawlers, and malicious bots. Apply appropriate limits.
- Analytics and attribution — Track which agents are querying your catalog, what they're searching for, and conversion rates from agent-referred traffic.
Integration Decision Matrix
| Merchant Size | Recommended Approach | Timeline |
|---|---|---|
| Small (< 500 SKUs) | Platform-native tools (Shopify/WooCommerce plugins) + Google Merchant Center + clean schema | 2–4 weeks |
| Mid-market (500–10K SKUs) | Feed management tool + headless API + schema automation | 1–3 months |
| Enterprise (10K+ SKUs) | Full reference architecture with PIM, enrichment pipeline, and dedicated API layer | 3–6 months |
Implementation Priorities
You do not need to build all five layers simultaneously. The priority order for most merchants:
- Structured Catalog + Enrichment — Get your product data clean, complete, and marked up with Schema.org. This delivers value today for both search engines and AI agents.
- Ingestion layer improvements — Move from batch to event-driven updates. Ensure inventory and pricing are fresh.
- API Layer — Expose a product search and inventory API. Start with read-only endpoints; add cart creation as protocols mature.
- Agent Interface — Implement protocol support as UCP and ACP standards stabilize. This layer will evolve rapidly through 2026–2027.
Frequently Asked Questions
Do I need to build a custom API for AI agents?
Not necessarily. For most small and mid-market merchants, a combination of clean structured data, active Merchant Center feeds, and platform-native APIs (like Shopify's Storefront API) provides sufficient machine readability. Custom APIs become valuable at enterprise scale or when targeting direct agent integrations.
Which protocol should I build for — UCP or ACP?
Build for data quality first, protocol compatibility second. Clean product data, valid Schema.org markup, and accessible APIs are compatible with both UCP and ACP. Protocol-specific integration can come later as standards stabilize.
How does this architecture handle multiple storefronts or marketplaces?
The Offer entity is designed to support multi-seller scenarios. A single Product can have multiple Offers from different sellers, each with independent pricing, availability, and policies. This mirrors how agents compare offers across merchants.
What about security? How do I prevent unauthorized agents from accessing my API?
Start with API key authentication and rate limiting. UCP defines richer agent authentication patterns that will mature through 2026. Monitor unusual query patterns and implement progressive access — read-only catalog access for unverified agents, cart creation for authenticated ones.
How does this relate to headless commerce?
Headless architecture aligns naturally with this reference architecture because it already separates the data layer from the presentation layer. If you're already headless, you likely have most of the API layer in place — the work is in enrichment, protocol support, and agent interface.