Design, Implementation and Production Deployment of the Protocol for Agentic Commerce
Part I - Foundations
Chapter 1: Why Agentic Commerce Needs a Protocol
- The Rise of AI-Driven Buying
- The Fragmentation Problem
- What a Commerce Protocol Must Do
- Scope and Organization
Chapter 2: From EDI to Agents - The Historical Arc of Machine Commerce
- EDI: The First Machine Commerce Protocol
- XML, SOAP and the REST API Era
- Buy Buttons, One-Click and Platform APIs
- The Agent Moment
Chapter 3: Design Goals, Principles and Specification Shape
- Stated Design Goals
- Guiding Architectural Principles
- Specification Document Structure
- Versioning Model
- Terminology
Chapter 4: The UCP Ecosystem and Governance
- Origins and Founding Participants
- Governance Model
- SDKs, Reference Implementations and Tooling
- Adoption Status (as of 2026-11-21)
- Release History
- Relationship to Related Projects
Part II - Protocol Deep Dive
Chapter 5: Architecture Overview
- Actors and Roles
- Trust Boundaries
- High-Level Interaction Model
- Deployment Topologies
- Integration Patterns
Chapter 6: Discovery, Registration and Capability Negotiation
- The Discovery Document
- Platform Profiles
- The
UCP-AgentHeader - Capability Negotiation Algorithm
- Negotiation Example
- Negotiation Errors
- Discovery Errors and Edge Cases
Chapter 7: The Data Model
- Schema Design Approach
- Namespace and Authority Binding
- Core Shared Types
- Entity and Resource Taxonomy
- Extensibility Mechanisms
- Conformance and Validation
Chapter 8: Catalog and Product Discovery Operations
- Catalog Capabilities
- Product Search Operation
- Product Lookup Operation
- Filtering and Faceting
- Pagination
- Pricing and Availability
- Media
- Error Handling
- Caching Considerations
Chapter 9: Cart and Checkout Operations
- Cart Capability
- Checkout Capability
- Address Handling
- Shipping and Fulfillment
- Tax Handling
- Payment Integration
- Idempotency
- Error Handling
Chapter 10: Orders, Fulfillment and the Post-Purchase Lifecycle
- Order Capability
- Order State Machine
- Fulfillment Events
- Returns and Refunds
- Webhook Notifications
- Order Permalinks
Chapter 11: Messaging, Transport and Asynchronous Patterns
- Transport Bindings
- HTTP Conventions
- Headers
- Request/Response Structure
- Asynchronous Patterns
- Concurrency and Race Conditions
- Error Model
Chapter 12: State, Consistency, Idempotency and Failure Handling
- State Management
- Consistency Model
- Idempotency
- Failure Handling
- Recovery
Chapter 13: Security Architecture
- Security Principles
- Transport Security
- HTTP Message Signatures
- Authentication
- Authorization
- Payment Security
- Identity Linking
- Privacy and Data Minimization
- Threat Model
- Key Management
- Security Best Practices
Part III - Building with UCP
Chapter 14: The Developer Toolkit
- Official SDKs
- The
ucp-schemaTool - Local Development Environment
- Validation and Contract Testing
- Debugging and Developer Experience
Chapter 15: Reference Implementation I - The Merchant Server
- Project Layout
- Dependency Manifest
- Environment Configuration
- Database Setup
- Pydantic Models
- Key Management
- Discovery Profile Endpoint
- Catalog Operations
- Checkout Operations
- Order Operations
- Request Signature Verification
- Application Wiring
- Data Import Script
- Sample Product Data
- Starting the Server
- Verifying the Server
Chapter 16: Reference Implementation II - The Buyer Agent and End-to-End Flow
- Agent Project Layout
- Agent Dependencies
- UCP Client Wrapper
- End-to-End Happy Path Client
- Running the End-to-End Flow
- Verification Steps
- Extending the Reference Implementation
Chapter 17: Production Engineering
- Observability
- Resilience
- Caching and Scaling
- Deployment Models
- CI/CD and Backward Compatibility
- Operational Processes
Part IV - Context and Future
Chapter 18: UCP in the Broader Protocol Landscape
- UCP vs. Model Context Protocol (MCP)
- UCP vs. A2A (Agent-to-Agent Protocol)
- UCP vs. AP2 (Agent Payments Protocol)
- UCP vs. Platform-Native Commerce APIs
- UCP vs. Legacy EDI/xAPI
- UCP vs. Payment Processor APIs
- UCP vs. OpenAPI/GraphQL
- GS1 and Product Identification
- FAPI and Financial Security
- Adoption Scenarios
Chapter 19: Patterns, Pitfalls and Evolution
- Architectural Patterns
- Common Implementation Pitfalls
- Unresolved Challenges
- Specification Evolution
- Future Directions
Conclusion: The Protocol That Bought It
Bibliography
Primary Sources (Specification & Official Documentation)
- [S1] UCP Specification Overview
- [S2] UCP Core Concepts
- [S3] UCP GitHub Repository
- [S4] Google Developer Blog: “Under the Hood: Universal Commerce Protocol (UCP)”
- [S5] UCP Checkout Specification (REST Binding)
- [S6] UCP Checkout Capability Overview
- [S7] UCP Checkout MCP Binding
- [S8] UCP Order Specification
- [S9] UCP Order REST Binding
- [S10] UCP Message Signatures Specification
- [S11] UCP Payment Tokenization Guide
- [S12] UCP Python SDK
- [S13] UCP JavaScript SDK
- [S14] UCP Samples Repository
- [S15] Flower Shop Client (Reference Implementation)
- [S16] Shopify News: “The agentic commerce platform”
- [S17] Shopify: Agents Documentation
- [S18] Google Merchant Center: UCP Guide
- [S19] Google Shopping
- [S20] Stripe: Agentic Commerce Documentation
- [S21] AP2 Protocol
- [S22] UCP Documentation Root
- [S23] UCP Identity Linking Specification
- [S24] UCP Payment Handler Guide
Reference Sources (Related Standards & Protocols)
- [R1] RFC 9421: HTTP Message Signatures
- [R2] RFC 7517: JSON Web Key (JWK)
- [R3] RFC 3339: Date and Time on the Internet
- [R4] JSON Schema 2020-12
- [R5] OpenAPI Specification 3.1.0
- [R6] OpenRPC Specification
- [R7] OAuth 2.0: The OAuth 2.0 Authorization Framework
- [R8] PCI DSS: Payment Card Industry Data Security Standard
- [R9] GS1 Standards
- [R10] UN/CEFACT Rec 20 - Common Codes for Units of Measure