Open Specs
RetailAgentOS Spec Series
UCP gives commerce the rails — discovery, catalog, cart, checkout handoff. These specs move a merchant's reasoning (who may see this, who may buy it, at what price, with what fulfillment) from checkout-time to catalog-time, with machine-readable reasons attached — so AI shopping agents can act correctly and explain themselves.
Every spec is backed by a runnable reference implementation in the Playground. If the Playground runs it, the spec is real.
Why specs first
A small retailer can't build a bespoke AI-commerce integration. But if the semantics exist as an open spec, the platform they already use can implement it once — and every merchant on that platform inherits agent-readiness for free. The spec is the leverage. The goal is to prove patterns on real merchant archetypes and propose the durable ones upstream into UCP.
Conformance tiers
A conformance tier describes a merchant's implementation maturity — what their catalog can do for an agent. It is separate from a buyer's loyalty tier (gold / silver / guest), which travels as a buyer-context claim (RAOS-0009). Tier 3 Member-aware means the merchant supports member-aware pricing and earn preview — not that the shopper is a member. A guest can shop a Member-aware merchant.
| Tier | Name |
|---|---|
| 0 | Discoverable |
| 1 | Qualified |
| 2 | Priced |
| 3 | Member-aware |
| 4 | Assisted |
Plane 0 · Foundation
The spine — everything depends on it.
Privacy, Consent & Identity
Buyer context is PII. Consent model, PII minimization, account-linking trust (how a loyalty/member claim is verified), and GDPR/CCPA-aware data-retention signals.
com.os.retailagent.shopping.identity
Plane 1 · Discovery & Truth
Getting found. Never selling what isn't there.
Discovery, Catalog Semantics & Match
Merchant-declared discoverability: keywords, intent tags, substitution/alternates, bundle/kit schemas, and attribute normalization so agents match across merchants.
com.os.retailagent.shopping.discovery
Plane 2 · Reasoning
Who may see this, who may buy it, and why.
Tax & Restricted / Regulated Goods
Age-restricted goods (alcohol, cannabis, tobacco, pharmacy), regional legality, purchase limits, and tax-treatment signals — surfaced at catalog time so agents never route buyers into a restricted-goods dead end.
com.os.retailagent.shopping.restricted
Plane 3 · Price & Value
The right price, the right offer, honored at checkout.
Promotional Pricing & Stacking
Sale/markdown, BOGO, mix-and-match, coupons, and a deterministic stacking model (stackable/exclusive flags + priority ladder) with reason codes for every applied or suppressed offer.
com.os.retailagent.shopping.promo_pricing
Loyalty & Rewards
Browse-time earn preview per line item, burn/redeem eligibility, member benefit summaries, tier-progress signals, and account-linked state — so agents can surface loyalty value before checkout, not after. Owns the buyer loyalty tier (gold/silver/guest) as a BuyerContext claim — orthogonal to a merchant's conformance tier.
com.os.retailagent.shopping.loyalty
Subscriptions & Recurring
Subscribe-and-save pricing, first-order discount, cadence semantics, skip/pause/cancel, and recurring eligibility. Essential for grocery and DTC agent shopping.
com.os.retailagent.shopping.subscription
Plane 4 · Fulfillment
Can you actually get it to this buyer, this way?
Fulfillment Feasibility
Ship / pickup / local-delivery / BOPIS modes, delivery windows, lead times, hazmat/oversize restrictions, and split-shipment signaling — surfaced before cart, not at checkout.
com.os.retailagent.shopping.fulfillment_constraints
Plane 5 · Outcomes & Handoff
Cart, checkout, intent capture, post-purchase.
Cart Bridge & Checkout Handoff
Serialize the agent-built cart and hand off to real checkout with all quote tokens intact. Idempotent, quote-expiry-aware, and handles partial-cart scenarios.
com.os.retailagent.shopping.cart_bridge
Returns & Post-Purchase Policy
Return window, final-sale flags, restocking fees, who pays return shipping, warranty terms — machine-readable at catalog time so agents communicate policy before the buyer commits.
com.os.retailagent.shopping.returns
How to contribute
These drafts exist to be argued with. Each spec ends with an open questions section — genuine design forks, not rhetorical ones. If you run a real catalog, build on a commerce platform, or work on agents, your disagreement is the most valuable input there is.
rikbanerjee007@gmail.com