UCP Python SDK

Official Python library for the Universal Commerce Protocol (UCP).

Overview

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.

UCP Version Compatibility

Each version of the Python SDK is generated against a specific version of the UCP schema:

SDK Version	UCP Schema Version
`0.5.x`	`2026-08-25`
`0.4.x`	`2026-04-08`
`0.3.x`	`2026-01-23`
`0.2.x` / `0.1.x`	`2026-01-11`

Installation

To use this SDK in your own project, install it from PyPI:

pip install ucp-sdk

Or, if you are managing your project with uv:

uv add ucp-sdk

Usage

The example below parses a UCP checkout response and reads typed fields:

from ucp_sdk.models.schemas.shopping.checkout import Checkout

# Parse a UCP checkout response
checkout = Checkout.model_validate(checkout_data)

# Access typed fields
print(checkout.status)       # "incomplete" | "ready_for_complete" | ...
print(checkout.currency)     # ISO 4217 currency code
for item in checkout.line_items:
    print(f"{item.item.title}: {item.quantity}")

Available model packages

Package	Description
`ucp_sdk.models.schemas.common`	Location search/lookup, identity linking, loyalty, payment terms
`ucp_sdk.models.schemas.common.types`	Shared primitives (amounts, prices, totals, postal address, etc.)
`ucp_sdk.models.schemas.shopping`	Checkout, cart, catalog, order, buyer consent, permalink models
`ucp_sdk.models.schemas.shopping.types`	Line items, adjustments, fulfillments, destinations, attribution
`ucp_sdk.models.schemas.transports`	REST, MCP, and embedded protocol bindings
`ucp_sdk.models.schemas`	Service definitions, capabilities, profile, payment handlers

Validation

All models support Pydantic validation and serialization:

from pydantic import ValidationError
from ucp_sdk.models.schemas.shopping.checkout import Checkout

# Validate data against UCP schemas
try:
    checkout = Checkout.model_validate(checkout_data)
    # Serialize to JSON-compatible dict
    checkout_dict = checkout.model_dump(exclude_none=True)
except ValidationError as e:
    print(e.errors())

Development

Prerequisites

This project uses uv for dependency management.

Setup

# Clone the repository
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git
cd python-sdk

# Install dependencies
uv sync

Generating Pydantic Models

The 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-08-25").

If no version is specified, the main branch of the UCP repo will be used.

The generated code is automatically formatted using ruff.

Running Tests

Run the schema preprocessing test suite with:

uv run python -m unittest discover -s tests -p "test_*.py"

Contributing

We welcome community contributions. See our Contribution Guide for details.

License

UCP is an open-source project under the Apache License 2.0.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ucp_sdk-0.5.0.tar.gz (106.5 kB view details)

Uploaded Aug 27, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ucp_sdk-0.5.0-py3-none-any.whl (281.4 kB view details)

Uploaded Aug 27, 2026 Python 3

File details

Details for the file ucp_sdk-0.5.0.tar.gz.

File metadata

Download URL: ucp_sdk-0.5.0.tar.gz
Upload date: Aug 27, 2026
Size: 106.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ucp_sdk-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`1a47eedf044240d0b3c6e8453f3e9ed08fd6a3bc920bb56f294ccf13d27fe6e9`
MD5	`733020c49d8968d0e400fcb219822eb5`
BLAKE2b-256	`6ce8238360ba5b4a14dbab2e0b87cb602523a3ed2929bd7d22bb91f86cad4796`

See more details on using hashes here.

Provenance

The following attestation bundles were made for ucp_sdk-0.5.0.tar.gz:

Publisher: release.yml on Universal-Commerce-Protocol/python-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: ucp_sdk-0.5.0.tar.gz
- Subject digest: 1a47eedf044240d0b3c6e8453f3e9ed08fd6a3bc920bb56f294ccf13d27fe6e9
- Sigstore transparency entry: 2617876744
- Sigstore integration time: Aug 27, 2026
Source repository:
- Permalink: Universal-Commerce-Protocol/python-sdk@b6f9b91c018f748a92166266004c8b625142cdfb
- Branch / Tag: refs/tags/v2026-08-25
- Owner: https://github.com/Universal-Commerce-Protocol
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@b6f9b91c018f748a92166266004c8b625142cdfb
- Trigger Event: release