Exploring Agentic Commerce: UCP Checkout with Harmony

Note: This is an experimental proof-of-concept exploring how Harmony might integrate with emerging agentic commerce standards. The UCP specification is still evolving, and this implementation is intended for learning and experimentation, not production use.

The world of e-commerce is changing. With AI agents increasingly handling tasks on behalf of users—from finding products to completing purchases—there's a growing need for standardised protocols that let these agents interact with merchants seamlessly. Enter the Universal Commerce Protocol (UCP).

We've built an experimental Harmony example that demonstrates how you might use Harmony as a UCP gateway, translating between AI shopping platforms and legacy commerce backends.

What is UCP?

The Universal Commerce Protocol is an open standard developed by Google in collaboration with industry leaders including Shopify, Etsy, Walmart, and over 20 other partners. It defines building blocks for agentic commerce—from discovering what a merchant offers to completing purchases—allowing different systems to interoperate through one standard.

UCP addresses three key challenges in agentic commerce:

1. Discovery: How does an AI agent know what a merchant can do?
2. Checkout: How do you create a standardised cart and payment flow?
3. Payment Negotiation: How do merchants and platforms agree on payment methods?

Why Harmony for UCP?

Harmony's strength lies in protocol translation. It already bridges gaps between FHIR and HL7, DICOM and DICOMweb, SOAP and REST. UCP is essentially another protocol translation problem: converting UCP-compliant requests from AI platforms into whatever format your existing commerce backend understands.

This makes Harmony a natural fit for organisations that want to:

• Expose legacy commerce systems to UCP-compliant AI agents
• Avoid rewriting their entire backend to support a new protocol
• Maintain control over their commerce logic while participating in the agentic commerce ecosystem

The Proof-of-Concept

Our experimental example demonstrates a complete UCP checkout flow:

Profile Discovery

AI agents discover what your business supports by fetching a profile from /.well-known/ucp:

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/overview",
        "rest": {
          "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
          "endpoint": "http://localhost:8085/v1"
        }
      }
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specification/checkout",
        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
      }
    ]
  }
}

Request/Response Translation

The interesting part is how Harmony transforms data between formats. We use JOLT transforms to convert:

UCP Request → Legacy Backend:

// UCP format (from AI agent)
{
  "line_items": [
    {
      "item": { "id": "sku_123", "price": 2999 },
      "quantity": 2
    }
  ],
  "buyer": { "email": "user@example.com" }
}
 
// Legacy format (to backend)
{
  "items": [
    { "sku": "sku_123", "unit_price": 2999, "qty": 2 }
  ],
  "customer": { "email": "user@example.com" }
}

Legacy Backend → UCP Response:

// Legacy format (from backend)
{
  "cart_id": "cart_12345",
  "pricing": {
    "subtotal_cents": 5998,
    "tax_cents": 600,
    "total_cents": 6598
  }
}
 
// UCP format (to AI agent)
{
  "ucp": { "version": "2026-01-11" },
  "id": "cart_12345",
  "status": "ready_for_complete",
  "totals": [
    { "type": "subtotal", "label": "Subtotal", "amount": 5998 },
    { "type": "tax", "label": "Tax", "amount": 600 },
    { "type": "total", "label": "Total", "amount": 6598 }
  ],
  "payment": {
    "handlers": [...]
  }
}

Payment Handler Negotiation

UCP's payment architecture is particularly elegant. Rather than requiring every platform to integrate with every payment provider, merchants advertise which payment handlers they support:

{
  "payment": {
    "handlers": [
      {
        "id": "google-pay-handler",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config": {
          "merchant_info": {
            "merchant_id": "demo-merchant-123"
          }
        }
      }
    ]
  }
}

The AI platform then picks a compatible handler and acquires a payment token directly from the payment provider—the merchant never sees raw card data.

Architecture

The example follows Harmony's standard pipeline pattern, transforming UCP requests to legacy backend formats and converting responses back to UCP:

• Request transform: Converts incoming UCP checkout requests into your backend's expected format (e.g., cart creation, item addition)
• Response transform: Converts backend responses (cart IDs, pricing, payment options) back into UCP-compliant format
• Session handling: Each request flows through middleware chains that handle discovery, creation, updates, and completion

The workload includes four main endpoints:

• Profile discovery (.well-known/ucp/profile) - Advertises capabilities
• Session creation (/v1/checkout/sessions POST) - Initialize cart and line items
• Session update (/v1/checkout/sessions/{id} PATCH) - Modify session contents
• Session completion (/v1/checkout/sessions/{id}/complete POST) - Process payment and create order

Implementation

The example implements the core UCP checkout flow with these endpoints:

• GET /.well-known/ucp/profile - Merchants advertise their UCP version, supported capabilities (checkout, discounts, identity linking), available services, and payment handlers
• POST /v1/checkout/sessions - Create a new checkout session with line items, buyer information, and optional discounts
• PATCH /v1/checkout/sessions/{id} - Update an existing session (add/remove items, change quantities, apply discounts)
• POST /v1/checkout/sessions/{id}/complete - Submit payment token and complete the checkout to create an order

Each endpoint uses JOLT transforms to map between UCP format and your backend's native API, enabling any existing commerce system to participate in the agentic commerce ecosystem without modification

Try It Yourself

The complete UCP checkout example with all pipelines, transforms, and configuration is available as a workload template:

Once deployed, you can test the discovery endpoint:

curl http://localhost:8085/.well-known/ucp/profile | jq

This returns your merchant profile with supported capabilities, services, and payment handler options. The workload includes full testing documentation and example requests for creating sessions, updating items, and completing purchases.

What This Demonstrates

This proof-of-concept shows that:

1. Protocol translation works: Harmony's JOLT transforms can convert between UCP and legacy formats
2. Minimal backend changes: Your existing commerce backend doesn't need to understand UCP
3. Standards compliance: The gateway handles UCP versioning, capability negotiation, and payment handler advertisement

Limitations

This is experimental. Key limitations include:

• No persistent state: Sessions are stateless; a real implementation would need session storage
• Mock backend: Uses echo backend; production would connect to real commerce systems
• Simplified payment flow: Real payment handler integration requires additional security considerations
• No identity linking: The UCP Identity Linking capability is not implemented

What's Next for Agentic Commerce?

UCP is still evolving. Future capabilities on the roadmap include:

• Order Management: Post-purchase tracking and returns
• Loyalty Programs: Standardised rewards integration
• New Verticals: Travel, services, and beyond shopping

As the protocol matures, we'll continue exploring how Harmony can help organisations participate in the agentic commerce ecosystem without rebuilding their infrastructure.

Learn More

• UCP Specification
• UCP GitHub Repository
• Harmony Documentation
• Harmony Examples Repository

The future of commerce is agentic. This experiment shows one path to getting there.