onX Integration Kit

End-to-end testing environment and reference implementation for onX (Order Network Exchange) — the open standard linking agentic commerce selling channels to the world of fulfillment.

This kit demonstrates how onX normalizes orders from both OpenAI's ACP (Agentic Commerce Protocol) and Google's UCP (Universal Commerce Protocol) into a single canonical format that any fulfillment system can consume.

┌─────────────────┐     webhook      ┌──────────────┐    fulfillment    ┌─────────────────┐
│   Mock ACP      │─────────────────▶│              │──────────────────▶│                 │
│   Merchant      │                  │   onX Hub    │                   │  Mock 3PL/WMS   │
│   (port 3001)   │                  │  (port 3000) │◀──────────────────│   (port 3003)   │
└─────────────────┘                  │              │   status update   └─────────────────┘
                                     │              │
┌─────────────────┐   notification   │              │
│   Mock UCP      │─────────────────▶│              │
│   Merchant      │                  │              │
│   (port 3002)   │                  └──────┬───────┘
└─────────────────┘                         │
                                            ▼
                                     MCP Tool API
                                    (for AI agents)

What each service does:

docker-compose up --build

All four services start automatically with correct inter-service networking.

Prerequisites: Node.js 20+, pnpm 8+

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start all services (uses concurrently)
pnpm dev

This starts all four services with color-coded log output.

Once services are running:

# Run all scenarios
pnpm test:scenarios

# Run a specific scenario
npx tsx scenarios/run-all.ts acp-buy
npx tsx scenarios/run-all.ts ucp-buy
npx tsx scenarios/run-all.ts acp-cancel
npx tsx scenarios/run-all.ts mcp-tools

The kit includes four end-to-end scenarios that exercise the full order lifecycle:

Demonstrates the happy path through ACP: product search → cart → checkout → onX normalization → fulfillment pick/pack/ship → delivery confirmation.

Exercises UCP's capability negotiation, offer-based checkout, AP2 payment tokens, and the return flow — showing how onX handles UCP's distinct data model.

Tests order cancellation propagation: ACP cancel → onX status update → event recording.

Verifies the onX hub's MCP-compatible tool interface: tool discovery, direct order creation, order retrieval, and event listing — the interface AI agents use to interact with onX.

The core insight: ACP and UCP have fundamentally different data models.

The onX hub translates both into one canonical format (OnxOrder) that fulfillment systems consume. This means a 3PL only needs one integration — with onX — instead of separate integrations for every selling channel.

The onX hub exposes MCP-compatible tools that AI agents can use:

• onx_create_order — Ingest an order from any channel
• onx_get_order — Retrieve a normalized order
• onx_update_shipment — Update tracking/shipping info
• onx_request_return — Initiate a return
• onx_cancel_order — Cancel an order
• onx_list_events — View the order's lifecycle event trail

onx-integration-kit/
├── packages/
│   ├── shared/              # Shared TypeScript types (onX, ACP, UCP)
│   │   └── src/
│   │       ├── onx-types.ts    # Canonical onX order model
│   │       ├── acp-types.ts    # ACP data structures
│   │       └── ucp-types.ts    # UCP data structures
│   ├── onx-hub/             # onX translation hub
│   │   └── src/
│   │       ├── index.ts        # Express server, webhook receivers, MCP API
│   │       └── translators/
│   │           ├── acp-translator.ts  # ACP → onX conversion
│   │           └── ucp-translator.ts  # UCP → onX conversion
│   ├── mock-acp/            # Mock ACP merchant
│   │   └── src/
│   │       ├── index.ts        # Express server with ACP endpoints
│   │       └── seed-data.ts    # Product catalog
│   ├── mock-ucp/            # Mock UCP merchant
│   │   └── src/
│   │       ├── index.ts        # Express server with UCP endpoints
│   │       └── seed-data.ts    # Product & offer catalog
│   └── mock-fulfillment/    # Mock 3PL service
│       └── src/
│           └── index.ts        # Receives onX orders, simulates fulfillment
├── scenarios/
│   └── run-all.ts           # End-to-end test scenarios
├── docker-compose.yml       # One-command startup
├── package.json             # Workspace root
└── pnpm-workspace.yaml

This kit is designed as a starting point. Here's how to use it:

1. Study packages/shared/src/onx-types.ts for the canonical order model
2. Look at the ACP and UCP translators to understand the mapping
3. Build your own translator in packages/onx-hub/src/translators/

1. Study packages/mock-fulfillment/src/index.ts for the expected interface
2. The onX hub sends you OnxOrder objects — that's your contract
3. Send shipment updates back via the MCP tool API

1. Query GET /mcp/tools to discover available onX capabilities
2. Use POST /mcp/tools/:name to invoke tools
3. All order data is in the canonical onX format regardless of origin

This is a Commerce Operations Foundation project. We welcome contributions from members and the broader community.

Apache 2.0 — see LICENSE.

• onX Specification
• Commerce Operations Foundation
• ACP Specification
• UCP Specification