Architecture Notes
How vendor-scoped extensions layer on top of core UCP to give agents the retail semantics they need before checkout.
ComputedVisibility, ComputedEligibility, ComputedPriceState, and CartValidationResult. Every decision is deterministic and inspectable — see the live Playground to inspect these contracts in real time.The Three-Layer Model
This project operates in three distinct layers. Each builds on the one below it and exposes a clear contract upward — read the stack bottom-up.
Computed Output Contracts — What Agents Consume
The extension layer resolves to four deterministic output shapes. These are what an agent, UI, or downstream system reads to make decisions — not raw merchant config, but computed results with reasons.
Tells an agent whether to surface the item to this buyer. HIDDEN includes the reason why.
Tells an agent whether a purchase is valid. Each reason has a code, message, and blocking flag.
The resolved price with its source. teaser surfaces "add 5 more for 10% off"-style prompts.
Full cart-level validation — each line validated against the live context.
The Agentic Commerce Gap
Without this extension layer, AI shopping agents encounter checkout-time failures that could have been prevented at catalog time. The same buyer journey runs two ways:
Each row below shows a concrete scenario — what fails without the extension, and how the extension resolves it.
| Without Extension | Impact on Agent | With Extension |
|---|---|---|
Wholesale item shown to guest buyer | Agent surfaces a product the buyer cannot purchase — checkout fails with a cryptic error | ext.eligibility returns HIDDEN for guests — agent never surfaces it |
List price shown to wholesale member | Agent quotes wrong price — buyer is surprised at checkout with a different number | ext.member_pricing / ext.bulk_pricing returns correct contextual price before cart |
Cart quantity below MOQ | Agent builds a cart that fails validation at checkout — buyer abandons | ext.bulk_pricing exposes MOQ — agent enforces it during cart construction |
Item ordered for shipping to restricted region | Checkout blocks the item — agent had no way to know it was region-restricted | ext.fulfillment_constraints surfaces restriction at catalog time — agent routes correctly |
Extension Namespace Reference
All vendor-scoped extensions use a namespaced ID to prevent collisions across merchants and protocol versions. Extensions are declared in the merchant's UCP profile and attached to product variants.
Carrier of buyer context: customer type, tier, region, fulfillment mode, tax state. All other extensions consume it.
Structured visibility and eligibility reasoning. Returns VISIBLE/HIDDEN and ELIGIBLE/CONDITIONAL/BLOCKED with machine-readable reason codes.
Member-exclusive pricing, teaser pricing for upsell, and locked price states for unqualified buyers.
Minimum Order Quantities (MOQ), quantity increments, and volume-based price tier selection.
Sale pricing, mix-and-match quantity thresholds, and applied offer state declarations.
Mode and region availability restrictions surfaced at catalog time, not checkout time.
Earn/burn preview mechanics, account-linked state, member benefit summaries. (Future — not yet spec'd)
Non-checkout commerce outcomes: WhatsApp handoff, lead form routing, assisted sales callbacks. (Future — not yet spec'd)
Core UCP vs Vendor Extensions
The Unified Commerce Protocol (UCP) standardizes the core rails of digital commerce. But retail semantics — how things are priced, who can buy them, and under what conditions — are fundamentally specific to each merchant and business model.
This demo applies a clear separation of concerns:
- Core UCP provides discovery, cart lifecycle, and transaction handoff. It defines what can be done.
- Vendor Extensionsprovide the "why" and "under what conditions." They encapsulate the rules for eligibility, dynamic pricing, and fulfillment constraints. They define whether it should be done, and at what terms.
The extension model is deliberately vendor-scoped (namespaced) so that merchants can evolve their own semantics without requiring changes to the core protocol.
Why Pre-Checkout Retail Logic Matters
Historically, complex pricing and eligibility logic is evaluated late in the funnel — at checkout. This leads to poor agent and user experiences: an AI shopping agent that builds a cart using the wrong price, the wrong quantity, or a product the buyer cannot purchase.
By surfacing Eligibility, PricingContext, and BulkPricing extensions early — at catalog browsing and cart stages — agents and UIs can:
- Hide or label products the current buyer context cannot access.
- Show the exact applicable price before adding to cart.
- Provide actionable feedback during discovery: "Add 5 more for a 10% discount."
- Route to intent capture instead of checkout when qualification is missing.
This is a Learning Journey
This project is a demonstration and a learning vehicle — not a production UCP server, not a complete ecommerce platform, not a competing protocol.
It exists to test and validate ideas around agentic commerce and structured retail semantics. The long-term goal is to identify extension patterns that could eventually be proposed upstream into the broader UCP ecosystem.