Official Python library for the Universal Commerce Protocol (UCP).
This repository contains the Python SDK for the Universal Commerce Protocol (UCP). It provides Pydantic models for UCP schemas, making it easy to build UCP-compliant applications in Python.
Each version of the Python SDK is generated against a specific version of the UCP schema:
| SDK Version | UCP Schema Version |
|---|---|
0.4.x | 2026-04-08 |
0.3.x | 2026-01-23 |
0.2.x / 0.1.x | 2026-01-11 |
To use this SDK in your own project, install it from PyPI:
pip install ucp-sdkOr, if you are managing your project with uv:
uv add ucp-sdkThe example below parses a UCP checkout response and reads typed fields:
fromucp_sdk.models.schemas.shopping.checkoutimportCheckout# Parse a UCP checkout responsecheckout=Checkout.model_validate(checkout_data)
# Access typed fieldsprint(checkout.status) # "incomplete" | "ready_for_complete" | ...print(checkout.currency) # ISO 4217 currency codeforitemincheckout.line_items:
print(f"{item.item.title}: {item.quantity}")| Package | Description |
|---|---|
ucp_sdk.models.schemas.shopping | Checkout, cart, catalog, order, payment models |
ucp_sdk.models.schemas.shopping.types | Line items, totals, buyer, fulfillment, signals |
ucp_sdk.models.schemas.transports | REST, MCP, and embedded protocol bindings |
ucp_sdk.models.schemas | Service definitions, capabilities, payment handlers |
All models support Pydantic validation and serialization:
frompydanticimportValidationErrorfromucp_sdk.models.schemas.shopping.checkoutimportCheckout# Validate data against UCP schemastry:
checkout=Checkout.model_validate(checkout_data)
# Serialize to JSON-compatible dictcheckout_dict=checkout.model_dump(exclude_none=True)
exceptValidationErrorase:
print(e.errors())This project uses uv for dependency management.
# Clone the repository
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
cd python-sdk
# Install dependencies
uv syncThe models are automatically generated from the JSON schemas in the UCP Specification.
To regenerate the models:
uv sync
./generate_models.sh <version>Where <version> is the version of the UCP specification to use (for example,
"2026-04-08").
If no version is specified, the main branch of the
UCP repo will be used.
The generated code is automatically formatted using ruff.
Run the schema preprocessing test suite with:
python -m unittest discover -s tests -p "test_*.py"We welcome community contributions. See our Contribution Guide for details.
UCP is an open-source project under the Apache License 2.0.