---
title: "ucpify: JSON → Commerce Server in Seconds"
description: "Generate a fully UCP-compliant commerce server from a single JSON config. Stripe, PayPal, SQLite, admin dashboard, all wired."
url: "https://h3manth.com/scribe/ucpify-json-to-commerce-server/"
canonical_url: "https://h3manth.com/scribe/ucpify-json-to-commerce-server/"
markdown_url: "https://h3manth.com/scribe/blog/ucpify-json-to-commerce-server.md"
publishDate: "2026-02-13T00:00:00.000Z"
author: "Hemanth HM"
category: "javascript"
tags: ["javascript","python","ucp","commerce","agentic","ai","opensource"]
word_count: 812
reading_time_minutes: 5
x_markdown_tokens: 1664
content_signal: "ai-train=yes, search=yes, ai-input=yes"
---

# ucpify: JSON → Commerce Server in Seconds

> Generate a fully UCP-compliant commerce server from a single JSON config. Stripe, PayPal, SQLite, admin dashboard, all wired.

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.

![ucpify architecture](../../assets/blog/ucpify-arch.png)

## What is UCP?

The [Universal Commerce Protocol](https://ucp.dev) 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:

![ucpify config](../../assets/blog/ucpify-config.png)

```json
{
  "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:

![ucpify endpoints](../../assets/blog/ucpify-endpoints.png)

**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:

```json
{
  "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:**

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

**Python:**

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

**Docker:**

```bash
docker compose up ucpify-js   # or ucpify-py
```

## CLI

```bash
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](https://www.npmjs.com/package/ucpify)
- **PyPI**: [pypi.org/project/ucpify](https://pypi.org/project/ucpify/)
- **GitHub**: [github.com/hemanth/ucpify](https://github.com/hemanth/ucpify)
- **UCP Spec**: [ucp.dev](https://ucp.dev)

JSON in, commerce out.