strands-ucp 0.1.0

Universal Commerce Protocol (UCP) tools for Strands Agents. Enable agentic commerce with discovery, checkout, orders, and payment handling.

Strands UCP

Universal Commerce Protocol (UCP) tools for Strands Agents

Enable agentic commerce experiences with full UCP protocol support: discovery, checkout, orders, payments, and extensions.

🚀 Features

• 🔍 Discovery - Query merchant capabilities, services, and payment handlers
• 🛒 Checkout - Full lifecycle management (create → update → complete)
• 📦 Orders - Get, list, cancel, and update orders
• 💰 Payments - Multi-handler support with automatic header management
• 🔐 Security - Request signature support (parameter + env var)
• 🎟️ Extensions - Discounts, fulfillment, refunds, returns, disputes
• 🔧 Custom - Passthrough for any UCP endpoint

📦 Installation

pip install strands-ucp

🎯 Quick Start

from strands_ucp import ucp_discover, ucp_checkout_session, ucp_apply_discount, ucp_complete_checkout

# 1. Discover merchant capabilities
discovery = ucp_discover("https://shop.example.com")
handlers = discovery["body"]["payment"]["handlers"]

# 2. Create checkout session (with optional signature)
checkout = ucp_checkout_session(
    merchant_url="https://shop.example.com",
    line_items=[
        {"item": {"id": "product_123", "title": "Widget"}, "quantity": 2}
    ],
    currency="USD",
    payment_handlers=handlers,
    buyer={"full_name": "John Doe", "email": "[e-mail]"},
    request_signature="eyJhbGc..."  # Optional: JWT/signed token
)

# 3. Apply discount code
checkout = ucp_apply_discount(
    merchant_url="https://shop.example.com",
    checkout_id=checkout["checkout_id"],
    discount_codes=["SAVE10"],
    current_checkout=checkout["body"]
)

# 4. Complete checkout
order = ucp_complete_checkout(
    merchant_url="https://shop.example.com",
    checkout_id=checkout["checkout_id"],
    payment_instrument={
        "type": "card",
        "handler_id": "mock_payment_handler",
        "credential": {"token": "success_token"}
    }
)

print(f"Order created: {order['order_id']}")

🔐 Security & Signatures

Request Signatures

Production UCP merchants require request signatures for security. Provide them via:

1. Function Parameter (Recommended)

ucp_checkout_session(
    merchant_url="https://shop.example.com",
    request_signature="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    # ... other params
)

2. Environment Variable

export UCP_REQUEST_SIGNATURE="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Signature automatically loaded from env var
ucp_checkout_session(
    merchant_url="https://shop.example.com",
    # ... other params
)

Parameter takes precedence over env var. If neither is provided, the request-signature header is omitted (discovery endpoints typically don't require signatures).

Generating Signatures

Request signatures are typically JWT tokens signed with your merchant credentials:

import jwt
import time

def generate_request_signature(merchant_secret: str, request_data: dict) -> str:
    payload = {
        "iat": int(time.time()),
        "exp": int(time.time()) + 300,  # 5 min expiry
        "data": request_data
    }
    return jwt.encode(payload, merchant_secret, algorithm="HS256")

# Use in request
signature = generate_request_signature("your-secret-key", {"merchant_id": "123"})
ucp_checkout_session(..., request_signature=signature)

📚 Available Functions

Core Function

ucp(action, merchant_url, **kwargs)

Generic UCP client supporting all operations.

Actions:

• discovery - Get merchant capabilities
• checkout_create - Create checkout session
• checkout_get - Get checkout session
• checkout_update - Update checkout
• checkout_complete - Complete checkout with payment
• order_get - Get order details
• order_list - List orders
• order_cancel - Cancel order
• order_update - Update order
• refund_create - Create refund
• return_create - Create return
• dispute_create - Create dispute
• custom - Custom endpoint access

Parameters:

• action (str) - UCP action to perform
• merchant_url (str) - Merchant base URL
• method (str) - HTTP method (auto-set for standard actions)
• endpoint (str) - Custom endpoint path
• headers (dict) - Additional headers
• body (dict) - Request body
• checkout_id (str) - Checkout session ID
• order_id (str) - Order ID
• request_signature (str) - Request signature (JWT/token)
• auto_headers (bool) - Auto-add UCP headers (default: True)
• timeout (int) - Request timeout in seconds
• follow_redirects (bool) - Follow redirects (default: True)

Helper Functions

ucp_discover(merchant_url)

Discover merchant capabilities and services.

ucp_checkout_session(merchant_url, line_items, currency, payment_handlers, buyer=None, request_signature=None)

Create a new checkout session with optional buyer info and signature.

ucp_apply_discount(merchant_url, checkout_id, discount_codes, current_checkout, request_signature=None)

Apply discount codes to checkout with optional signature.

ucp_complete_checkout(merchant_url, checkout_id, payment_instrument, risk_signals=None, request_signature=None)

Complete checkout with payment and optional signature.

🔧 Advanced Usage

Custom Requests

from strands_ucp import ucp

# Custom endpoint with signature
result = ucp(
    action="custom",
    merchant_url="https://shop.example.com",
    method="POST",
    endpoint="/api/custom-action",
    body={"custom_field": "value"},
    request_signature="eyJhbGc..."
)

Manual Header Control

from strands_ucp import ucp

result = ucp(
    action="checkout_create",
    merchant_url="https://shop.example.com",
    body={...},
    auto_headers=False,  # Disable automatic headers
    headers={
        "UCP-Agent": 'profile="https://my-agent/profile"',
        "request-id": "custom-request-id",
        "request-signature": "signed-jwt-token",
        "idempotency-key": "custom-idempotency-key"
    }
)

Order Management

from strands_ucp import ucp

# Get order
order = ucp(
    action="order_get",
    merchant_url="https://shop.example.com",
    order_id="order_abc123"
)

# Cancel order
ucp(
    action="order_cancel",
    merchant_url="https://shop.example.com",
    order_id="order_abc123",
    body={"reason": "Customer request"},
    request_signature="eyJhbGc..."
)

# Create refund
ucp(
    action="refund_create",
    merchant_url="https://shop.example.com",
    order_id="order_abc123",
    body={"amount": 2500, "reason": "Defective product"},
    request_signature="eyJhbGc..."
)

Environment-Based Configuration

# Set signature once for all requests
export UCP_REQUEST_SIGNATURE="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Optional: Set custom agent profile
export UCP_AGENT_PROFILE="https://my-company.com/agent-profile"

# Signature automatically loaded from env
from strands_ucp import ucp_checkout_session

checkout = ucp_checkout_session(
    merchant_url="https://shop.example.com",
    line_items=[...],
    currency="USD",
    payment_handlers=[...]
    # request_signature loaded from UCP_REQUEST_SIGNATURE env var
)

📖 Response Format

All functions return a dictionary with:

{
    "status": "success" | "error",
    "status_code": 200,
    "headers": {...},
    "body": {...},  # Parsed JSON response
    "ucp_metadata": {...},  # UCP metadata (when available)
    "capabilities": [...],   # Capabilities (when available)
    "checkout_id": "...",    # Checkout ID (when available)
    "order_id": "...",       # Order ID (when available)
    "request": {
        "method": "POST",
        "url": "...",
        "headers": {...},  # Note: request-signature excluded from logs
        "body": {...}
    }
}

Security Note: The request-signature header is excluded from response logs for security.

🧪 Testing

Test with the official UCP sample server:

# Clone samples
git clone https://github.com/Universal-Commerce-Protocol/samples.git
cd samples/rest/python/server

# Install and run
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py --port 8182

Then test:

from strands_ucp import ucp_discover

result = ucp_discover("http://localhost:8182")
print(result)

Testing with Signatures

The sample server may accept test signatures:

from strands_ucp import ucp_checkout_session

checkout = ucp_checkout_session(
    merchant_url="http://localhost:8182",
    line_items=[{"item": {"id": "test_item"}, "quantity": 1}],
    currency="USD",
    payment_handlers=[...],
    request_signature="test"  # Test servers may accept this
)

Production: Always use properly signed JWT tokens in production.

🔗 Protocol Details

Required Headers

Automatically added by the tool (when auto_headers=True):

• UCP-Agent - Agent profile identifier
• request-id - Unique request ID (UUID)
• idempotency-key - For safe retries (POST/PUT/PATCH)
• request-signature - Request signature (if provided via parameter or env var)

Discovery Endpoint

GET /.well-known/ucp returns:

• UCP version
• Supported services
• Capabilities (checkout, order, discounts, etc.)
• Payment handlers
• Transport bindings (REST, MCP, A2A)

Standard Endpoints

• Checkout: /checkout-sessions, /checkout-sessions/{id}, /checkout-sessions/{id}/complete
• Orders: /orders, /orders/{id}, /orders/{id}/cancel
• Extensions: /orders/{id}/refunds, /orders/{id}/returns, /orders/{id}/disputes

🌐 Resources

• UCP Specification: https://ucp.dev
• Python SDK: https://github.com/Universal-Commerce-Protocol/python-sdk
• Samples: https://github.com/Universal-Commerce-Protocol/samples
• Google Integration: https://developers.google.com/merchant/ucp
• Blog Post: https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

Apache License 2.0 - See LICENSE file for details.

🙏 Acknowledgments

• Built on Strands Agents
• Implements Universal Commerce Protocol (UCP)