A monetization protocol for AI-assisted shopping. Handles attribution, settlement, conversion verification, and checkout discount offers for sponsored products in agentic commerce.
See docs/architecture.md for full visual diagrams (Mermaid, rendered by GitHub). Covers:
- System architecture (apps → MCP server → merchants → settlement)
- Full attribution flow (product recommendation → entitlement)
- Checkout discount flow (discount code lifecycle)
- Conversion verification methods (conversion tag, PSP-verified, agent-observed)
- Settlement adapters (invoice, MPP split, x402 split)
- Protocol object relationships (ER diagram)
- Entitlement state machine
- MCP server in the LLM tool ecosystem
| Document | Description |
|---|---|
| Architecture & Flow Diagrams | Visual overview — system architecture, attribution flow, discount flow, settlement, state machines |
| Protocol Spec | Canonical specification — attribution, fee models, settlement, conversion verification, discount offers. The source of truth. |
| Product Build Brief | Product requirements, MVP scope, sprint plan, success metrics |
| Implementation Checklist | 5-milestone build plan — MCP server (done), Shopify app, demo UI, backend, ads layer |
| Repo Layout | Separate repos: protocol spec, MCP server, Shopify app, demo app, backend |
| File | Description |
|---|---|
| OpenAPI Spec | HTTP API contract — endpoints for contracts, attributions, clicks, conversions, entitlements, invoices |
| Attribution Schema | JSON Schema for AttributionContext |
| Sponsored Product Schema | JSON Schema for SponsoredProductContext |
| Order Source Schema | JSON Schema for OrderSource |
| Payment Reference Schema | JSON Schema for PaymentReference |
| Merchant Contract Schema | JSON Schema for MerchantContract |
| Settlement Schema | JSON Schema for SettlementEntitlement |
| Product Sponsorship Schema | JSON Schema for ProductSponsorship — UCP extension for per-product sponsorship terms, targeting, bidding |
| File | Description |
|---|---|
| Cursor Prompt | Starter prompt for implementing in Cursor IDE |
| Codex Prompt | Starter prompt for implementing with Claude Codex |
Protocol Objects (spec section 5)
AttributionContext— binds a commerce opportunity to a source platform. Signed (HMAC-SHA256), time-bounded.SponsoredProductContext— monetization metadata on a sponsored product. Travels from API → app → checkout.OrderSource— how a merchant order is commercially interpreted.PaymentReference— normalizes payment correlation across rails (PSP, MPP, x402).MerchantContract— commercial rules: fee model, verification method, settlement method, offers.SettlementEntitlement— fee owed to source platform, with offer/platform split.
- Checkout discounts, not post-purchase cashback. Offers are discount codes submitted via UCP's discount extension at checkout. Fees computed on pre-discount amount.
- Three conversion verification methods (no merchant self-reporting): conversion tag (like Meta CAPI), PSP-verified (OAuth read on Stripe), agent-observed (AI agent witnesses the purchase).
- Settlement adapters: invoice (default), MPP split (instant via Stripe), x402 split (atomic onchain).
- Distribution Network (optional) — an intermediary that aggregates sponsored products and serves them to AI apps. One implementation pattern, not a protocol requirement.
- App-level attribution via
app_id— tracks which app drove conversions when a distribution network is present. - Open vs walled garden — UCP is open attribution (end-to-end). ACP is a self-attributing network (OpenAI = Meta model). Our protocol handles both: full attribution for the open ecosystem, merchant-side verification for walled gardens.
The demo/ directory contains a proof-of-concept MCP server that serves sponsored products with offers. It demonstrates the protocol in action but is not the architecture — the canonical flow is merchants publishing ProductSponsorship on their UCP endpoints, crawlable by any AI consumer.
See demo/README.md for setup instructions.
Older drafts are preserved under docs/archive/. Ignore unless you need historical context.