The Problem
Commerce platforms must integrate with many merchants, PSPs, and credential providers, each exposing bespoke APIs. The resulting point‑to‑point effort is costly, error‑prone, and hard to maintain, especially for AI‑driven agents that need to discover capabilities and act on a shopper’s behalf.
What This Does
The Universal Commerce Protocol (UCP) defines a JSON‑schema‑driven, transport‑agnostic contract for core commerce capabilities (checkout, identity linking, order, etc.). The repository stores the canonical schemas under source/schemas/… (e.g., source/schemas/shopping/checkout.json, source/schemas/shopping/cart.json).
Documentation lives in docs/ and is rendered with MkDocs (mkdocs.yml). A small Python entry point (main.py) and a handful of helper scripts (scripts/buildlocal.sh, scripts/checklinks.py) provide utilities for validation and local generation of the spec. The package.json together with the React assets in docs/assets/ support a browsable web UI for the spec.
How To Use It
Setup
Install Python dependencies (project uses pyproject.toml → Poetry or pip) pip install . # or: poetry install
Install documentation tooling
npm ci # installs React dev dependencies from package-lock.json
Configuration
No runtime secrets are required for the core spec. The MkDocs site reads mkdocs.yml for theme and navigation; customizing the site can be done by editing that file. If you intend to generate a profile for a merchant, edit the JSON files under source/discovery/profileschema.json to list supported capabilities.
Running it
Validate schemas – the helper script scripts/checklinks.py walks the source/ tree and validates $ref links. python scripts/checklinks.py
Serve documentation locally – MkDocs provides a live preview: npx mkdocs serve
Package the spec – scripts/buildlocal.sh runs the docs build and copies the generated site to site/.
The repository does not include a ready‑made server implementation; UCP is a specification, not a service. Consumers are expected to implement the defined endpoints in their own stack.
Real‑World Use
An AI‑shopping assistant can query a merchant’s capability profile (source/discovery/profile_schema.json) to discover that the merchant supports the checkout capability. It then constructs a request conforming to source/schemas/shopping/checkout.json, posts it to the merchant’s REST endpoint, and follows the checkout flow defined in docs/specification/checkout.md. The standardized JSON payloads guarantee the assistant can work with any UCP‑compliant merchant without custom adapters.
import json, requests
with open('source/schemas/shopping/checkout.json') as f: payload = json.load(f)
resp = requests.post('https://merchant.example.com/ucp/checkout', json=payload) print(resp.json())
Code Health & Issues
Low – Missing runtime examples – No reference implementation (e.g., server stub) is provided; users must build their own service. (README.md does not list a server start command.) Low – No explicit Python test directory – Tests are reported (33 files) but their location is not obvious; CI may fail to locate them without a proper pytest configuration. Medium – License file present but no SPDX header in source files – Could cause compliance tooling warnings. Low – Dependency hygiene – package-lock.json pins npm packages, but no npm audit results are shown; periodic audit is advisable. Low – No Dockerfile – Container builds must be authored externally if deployment in containers is required.
Overall, the repository passes basic health checks: CI workflows exist (.github/workflows/*.yml), linting is configured (.github/linters/), and the spec files are well‑structured.
The Bottom Line
UCP supplies a clear, schema‑first contract for commerce interactions, backed by thorough documentation and CI. It is suitable for teams that need a common language to build interoperable merchant APIs or AI agents, provided they are comfortable implementing the actual service layer themselves. The main gaps are the lack of a reference server and limited guidance on testing the Python utilities.