Universal Commerce Protocol gateway — connect any e-commerce store to any AI agent.
UCP Gateway (formerly ucp-gateway) is an ELv2-licensed server implementing the Universal Commerce Protocol. It translates between e-commerce platforms and AI agents via a standardised checkout API. Paid platform adapters (Magento, Shopware) live in private @omnixhq packages.
| Problem | Solution |
|---|---|
| Every shop has a different API | One UCP adapter per platform |
| AI agents need structured data | UCP normalises products, carts, checkout |
| N x M integration hell | N adapters + 1 UCP contract |
- UCP spec compliant — 148/148 SDK schemas covered (
@omnixhq/ucp-js-sdkv2.0.0) - MockAdapter built-in — Magento 2.x and Shopware 6.x available as private
@omnixhqpackages - Full checkout flow — discovery, search, create/update/complete/cancel sessions
- Catalog & cart — product search with categories/filters, cart CRUD, SDK-shaped responses
- Order lifecycle — line items, fulfillment events, adjustments, fulfilled tracking
- Multi-tenant — Host-based routing with Redis-cached tenant resolution
- Payment instruments — 4 handler types (card, wallet, redirect, offline) with instruments in responses
- Fulfillment — destination-aware shipping (US/intl), free thresholds, pickup,
line_item_ids - Escalation flow —
requires_escalation+continue_url+ embedded checkout config - Extensions — buyer consent, signals, identity linking, AP2 mandates, version negotiation
- Structured errors — UCP
messages[]with type, code, content, severity
git clone git@github.com:OmnixHQ/omnix-gateway.git
cd omnix-gateway
npm install
docker compose -f docker-compose.dev.yml up -d
cp .env.example .env
npm run devcurl http://localhost:3000/.well-known/ucp | jq
curl -H "UCP-Agent: my-agent/1.0" 'http://localhost:3000/ucp/products?q=shoes' | jq| Method | Path | Description |
|---|---|---|
GET |
/.well-known/ucp |
UCP profile (capabilities, payment handlers, signing keys) |
| Method | Path | Description |
|---|---|---|
POST |
/ucp/catalog/search |
Catalog search with UCP envelope + pagination |
POST |
/ucp/catalog/product |
Single product lookup in UCP envelope |
GET |
/ucp/products?q=... |
Product search (legacy) |
GET |
/ucp/products/{id} |
Product detail (legacy) |
| Method | Path | Description |
|---|---|---|
POST |
/ucp/cart |
Create cart with line items, buyer, context |
GET |
/ucp/cart/{id} |
Get cart |
PUT |
/ucp/cart/{id} |
Update cart items |
DELETE |
/ucp/cart/{cartId}/items/{index} |
Remove item from cart |
| Method | Path | Description |
|---|---|---|
POST |
/checkout-sessions |
Create checkout session |
GET |
/checkout-sessions/{id} |
Get checkout session |
PUT |
/checkout-sessions/{id} |
Update checkout (buyer, fulfillment, discounts, consent, signals) |
POST |
/checkout-sessions/{id}/complete |
Place order (payment instruments or AP2 mandate) |
POST |
/checkout-sessions/{id}/cancel |
Cancel checkout |
| Method | Path | Description |
|---|---|---|
GET |
/orders/{id} |
Get order with line items, fulfillment, adjustments |
PUT |
/orders/{id} |
Update order (fulfillment events, adjustments) |
| Method | Path | Description |
|---|---|---|
GET |
/ucp/identity/config |
Get identity linking mechanisms |
POST |
/ucp/identity/link |
Create identity link |
GET |
/ucp/identity/link/{externalId} |
Look up linked account |
DELETE |
/ucp/identity/link/{id} |
Remove identity link |
| Adapter | Catalog | Cart | Checkout | Order Lifecycle | Package |
|---|---|---|---|---|---|
| MockAdapter | Search, get, categories, ratings | Create, get, add, remove | Totals, fulfillment (US/intl/pickup), discounts | Events, adjustments | Built-in |
| Magento 2.x | REST API | Guest cart, get | Shipping, totals, order | Read | @omnixhq/adapter-magento |
| Shopware 6.x | Store API | Store API, get | Context, totals, order | Read | @omnixhq/adapter-shopware |
| Shopify | Planned | — | — | — | — |
npm run validate:ucp # Automated spec checksSDK: @omnixhq/ucp-js-sdk v2.0.0 — 148/148 schemas covered.
See UCP_SPEC.md for specification links.
npm run build # Build all packages (core → adapters → server)
npm test # 222 unit + integration tests
npm run validate:ucp # UCP spec compliance checks
npm run lint # ESLint
npm run typecheck # TypeScriptSee CONTRIBUTING.md. All contributors must sign the CLA.
Elastic License 2.0 (ELv2) — free to use, modify, and self-host. Cannot be offered as a hosted service.
For commercial licensing, contact Momentum Group s. r. o. (momentum.group139@gmail.com)