Say you’re a small business. You have a product catalog, maybe as a spreadsheet or a JSON file. You want to sell online. But building a commerce backend means dealing with payment APIs, database schemas, input validation, webhook handlers. That’s a lot of engineering for “I just want to sell t-shirts.”

ucpify takes a single JSON file with your products, shipping options, and payment config and gives you a fully working commerce server. UCP-compliant, Stripe and PayPal ready, SQLite persistence, admin dashboard. Node.js and Python.

What is UCP?

The Universal Commerce Protocol is an open standard for agentic commerce. It lets AI agents discover, browse, and complete purchases programmatically. Think of it as what OpenAPI did for REST, but for shopping flows.

A UCP server exposes /.well-known/ucp for discovery, declares capabilities, and provides a structured checkout flow that any UCP-compatible agent can follow.

One JSON. Full Commerce.

Here’s all you need:

{
  "name": "My Store",
  "domain": "https://my-store.com",
  "currency": "USD",
  "tax_rate": 0.08,
  "items": [
    { "id": "tshirt", "title": "Classic Tee", "price": 2500 },
    { "id": "hoodie", "title": "Premium Hoodie", "price": 5999 }
  ],
  "shipping_options": [
    { "id": "standard", "title": "Standard Shipping", "price": 500 },
    { "id": "express", "title": "Express Shipping", "price": 1500 }
  ],
  "payment_handlers": [
    { "namespace": "com.stripe", "id": "stripe_handler" },
    { "namespace": "com.paypal", "id": "paypal_handler" }
  ]
}

Products, shipping, tax, payment providers. All declarative. No code.

What You Get

Run ucpify serve merchant-config.json and you have a full server:

9 REST endpoints covering the entire checkout lifecycle:

Endpoint	Purpose
GET /.well-known/ucp	UCP discovery profile
POST /ucp/v1/checkout-sessions	Create checkout
GET /ucp/v1/checkout-sessions/:id	Get session
PUT /ucp/v1/checkout-sessions/:id	Update (buyer, fulfillment)
POST .../complete	Complete checkout
POST .../cancel	Cancel checkout
GET /ucp/v1/orders	List orders
GET /ucp/v1/orders/:id	Get order
GET /ucp/v1/items	Product catalog

Plus /health and /admin for monitoring.

Batteries Included

This isn’t a skeleton. It ships with real infrastructure.

Payment Processing. Stripe and PayPal are wired in. Set your API keys in .env, and completeCheckout() creates a Stripe PaymentIntent or PayPal Order automatically. Webhook endpoints handle payment confirmations.

SQLite Persistence. Everything is persisted with WAL mode for concurrent access. Checkouts, line items, orders, inventory. Proper schemas, foreign keys, indexes.

Input Validation. Every request goes through Zod schemas. Quantity capped at 100, line items at 50, emails validated, addresses checked.

Rate Limiting. 100 requests/min on API routes, 20/min on checkout creation.

Structured Logging. Pino logger with request timing, payment events, error tracking.

The Checkout Flow

The UCP checkout flow is a state machine:

incomplete → ready_for_complete → completed
                                → canceled

1. Create - POST line items, get back a session with totals and validation messages
2. Update - Add buyer info and shipping address, session transitions to ready_for_complete
3. Complete - Payment is processed, order is created
4. Cancel - Session is marked canceled

Each step returns the full session state with validation messages. The client (or AI agent) always knows what’s missing.

Identity Linking

UCP handles identity through OAuth 2.0. A platform (say, an AI agent service) can obtain authorization to act on behalf of a user at a business’s site. The business exposes /.well-known/oauth-authorization-server with standard OAuth metadata:

{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/oauth2/authorize",
  "token_endpoint": "https://example.com/oauth2/token",
  "revocation_endpoint": "https://example.com/oauth2/revoke",
  "scopes_supported": [
    "ucp:scopes:checkout_session"
  ],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}

This is foundational to how agentic commerce works. The agent doesn’t share the user’s credentials with the merchant. Instead, OAuth gives it scoped access to perform specific actions like creating a checkout session. The user stays in control, the agent gets just enough permission, and no passwords are exchanged.

This also unlocks personalized experiences. Loyalty benefits, saved addresses, wishlists, authenticated pricing. All through standard OAuth scopes, no proprietary auth schemes.

Quick Start

Node.js:

npm install ucpify
npx ucpify init
npx ucpify serve merchant-config.json

Python:

pip install ucpify
ucpify init
ucpify serve merchant-config.json

Docker:

docker compose up ucpify-js   # or ucpify-py

CLI

ucpify init                       # Generate sample config
ucpify validate config.json       # Validate config
ucpify serve config.json          # Start server (SQLite default)
ucpify serve config.json --no-db  # In-memory mode

Why I Built This

The UCP spec is powerful but implementing it from scratch is tedious. ucpify closes the gap between “I have products” and “I have a UCP-compliant commerce API” to about 30 seconds.

Useful for:

• AI agent developers testing commerce integrations
• Merchants who want UCP compliance without building from scratch
• Prototyping checkout flows before committing to a full platform
• Learning the UCP spec hands-on

Links

• npm: npmjs.com/package/ucpify
• PyPI: pypi.org/project/ucpify
• GitHub: github.com/hemanth/ucpify
• UCP Spec: ucp.dev

JSON in, commerce out.