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. Want the reference architecture instead of the raw RFCs? Start at /adopt.
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 |
Foundation
Required at every tier — the spine everything else depends on.
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
Tier 0 · Discoverable
An agent can find and correctly read my catalog.
Discovery & Catalog Semantics
Merchant-declared discoverability: keywords, intent tags, substitution/alternates, bundle/kit schemas, and attribute normalization so agents match across merchants.
com.os.retailagent.shopping.discovery
Tier 1 · Qualified
No dead-end carts.
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.tax / …restricted
Tier 2 · Priced
The right price per buyer, 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
Tier 3 · Member-aware
Supports member/loyalty-aware pricing and earn preview.
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
Tier 4 · Assisted
Full commerce: handoff, intent, returns.
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
Intent Capture & Assisted Commerce
Intent capture routing (notify-me, B2B quote request) for items that can't resolve to an immediate price or cart line. Builds on the Decision Trace substrate shipped in Foundation (0013 pt 1).
com.os.retailagent.shopping.intent_capture
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