Integrating UCP: The Python SDK

Implementing the Universal Commerce Protocol (UCP) directly over raw HTTP/JSON requests can become tedious, particularly when handling complex cart states, tax calculations, and payment intents. To accelerate developer adoption, we created the official UCP Python SDK (ucp-py). The SDK handles all core validation, schema parsing, and connection lifecycle management, allowing you to focus on the reasoning loop of your shopping agent.

In this guide, we will walk through setting up a UCP client in Python, executing a catalog search, managing a remote cart, and completing a secure checkout handshake.

Setting Up the Client

The UCP Python SDK allows you to connect directly to any compliant merchant server. By passing the base URL of the merchant, the SDK will automatically perform dynamic discovery, pulling the profile specifications from the standard /.well-known/ucp endpoint.

from ucp import UCPClient, CartItem, ShippingAddress

# Initialize UCP client for a compliant merchant
client = UCPClient(merchant_url="https://example-merchant.com")

Searching the Product Catalog

UCP standardizes how product specifications, categories, and inventory statuses are structured. AI agents can search the merchant's catalog using keyword queries or filter tags, receiving a parsed list of product objects containing detailed attribute mapping.

# Query products conforming to the UCP catalog schema
products = client.search_catalog(query="hiking backpack")
backpack = products[0]
print(f"Found product: {backpack.title} - Price: {backpack.price} {backpack.currency}")

Managing the Shopping Cart

Rather than orchestrating custom cookies or session tokens, UCP standardizes cart resources. The SDK allows you to create a cart, update items, and recalculate values synchronously or asynchronously.

# Initialize a standard UCP cart session
cart = client.create_cart()

# Add a selected variant to the cart
client.add_to_cart(
    cart_id=cart.id,
    item=CartItem(variant_id=backpack.variants[0].id, quantity=1)
)

Executing the Checkout and Payment Handshake

Once your agent is satisfied with the cart contents, the checkout handshake begins. UCP separates checkout initiation from payment processing, allowing flexible integration with diverse payment protocols like the Agentic Payment Protocol (AP2) or traditional transaction gateways.

# Define delivery destination
address = ShippingAddress(
    name="Akshar Prabhu Desai",
    street="123 Agentic Way",
    city="San Francisco",
    state="CA",
    zip_code="94107"
)

# Initiate standard checkout
checkout = client.initiate_checkout(cart.id, shipping_address=address)

# Complete checkout using secure payment intent
payment_intent = client.create_payment_intent(checkout.id, method="ap2")
result = client.complete_checkout(checkout.id, payment_intent_id=payment_intent.id)

print(f"Order Completed! Status: {result.status}, Order ID: {result.order_id}")

Conclusion

Using the UCP Python SDK, developers can build tools that make websites immediately actionable for AI agents. By abstracting the network calls and schema validations into standard Python classes, the SDK forms the bedrock for building high-reliability agentic shopping solutions.