Documentation

A JavaScript adapter for the Universal Commerce Protocol (UCP), enabling seamless integration with commerce platforms, payments, and product catalogs.

Next.js Support

TypeScript

Google-led Protocol

Installation

Terminal

npm install ucp-handler @ucp/sdk zod@^3

# or with yarn
yarn add ucp-handler @ucp/sdk zod@^3

# or with pnpm  
pnpm add ucp-handler @ucp/sdk zod@^3

# or with bun
bun add ucp-handler @ucp/sdk zod@^3

Next.js Usage

Create an API route to handle UCP requests. The route should be placed at app/api/ucp/[transport]/route.ts.

app/api/ucp/[transport]/route.ts

import { createUcpHandler } from "ucp-handler";
import { z } from "zod";

const handler = createUcpHandler(
  (commerce) => {
    commerce.product(
      "get_product",
      "Retrieve product details by ID",
      {
        productId: z.string(),
      },
      async ({ productId }) => {
        const product = await fetchProductFromDB(productId);
        return {
          content: [{ 
            type: "product", 
            data: product,
            schema: "https://schema.org/Product"
          }],
        };
      }
    );

    commerce.payment(
      "create_checkout",
      "Create a checkout session",
      {
        items: z.array(z.object({
          productId: z.string(),
          quantity: z.number()
        })),
        currency: z.string().default("USD")
      },
      async ({ items, currency }) => {
        const session = await createCheckoutSession(items, currency);
        return {
          content: [{ 
            type: "checkout", 
            sessionId: session.id,
            url: session.url
          }],
        };
      }
    );
  },
  {
    // Optional server options
  },
  {
    basePath: "/api/ucp",
    maxDuration: 60,
    verboseLogs: true,
  }
);

export { handler as GET, handler as POST };

Platform Integration

Connect your UCP endpoints to various commerce platforms and marketplaces.

Google Shopping

Sync your product catalog directly with Google Merchant Center.

• Endpoint: https://your-domain.com/api/ucp
• Protocol: UCP/1.0

// UCP Google Shopping configuration
{
  "ucp_endpoint": "https://your-domain.com/api/ucp",
  "merchant_id": "YOUR_MERCHANT_ID",
  "capabilities": ["products", "inventory", "pricing"]
}

Shopify

Connect your Shopify store to the UCP ecosystem for unified commerce.

Configuration file: shopify.ucp.json

{
  "store_domain": "your-store.myshopify.com",
  "ucp_bridge": {
    "products": true,
    "orders": true,
    "customers": true
  }
}

Payment Providers

Unified payment integration through UCP-compliant handlers.

UCP supports all major payment providers through standardized interfaces.

Configuration Options

The createUcpHandler function accepts the following configuration options:

interface UcpConfig {
  basePath?: string;        // Base path for UCP endpoints
  maxDuration?: number;     // Maximum duration for requests in seconds
  verboseLogs?: boolean;    // Log debugging information
  schemaValidation?: boolean; // Validate against schema.org
  merchantId?: string;      // Your merchant identifier
  supportedCurrencies?: string[]; // Supported currency codes
}

Security & Compliance

UCP.js includes built-in support for PCI compliance and secure transaction handling.

Secure Payment Handler

import { createUcpHandler, withUcpAuth } from "ucp-handler";
import type { MerchantAuth } from "@ucp/sdk/auth";

const handler = createUcpHandler((commerce) => {
  commerce.payment(
    "process_payment",
    "Process a secure payment",
    { 
      amount: z.number(),
      currency: z.string(),
      paymentMethod: z.string()
    },
    async ({ amount, currency, paymentMethod }, extra) => {
      // Access merchant auth via extra.authInfo
      const merchantId = extra.authInfo?.merchantId;
      
      const result = await processSecurePayment({
        amount,
        currency,
        paymentMethod,
        merchantId
      });
      
      return {
        content: [{
          type: "payment_result",
          transactionId: result.id,
          status: result.status
        }],
      };
    }
  );
});

// Wrap with merchant authentication
const authHandler = withUcpAuth(handler, verifyMerchantToken, {
  required: true,
  requiredScopes: ["payments:write"],
});

export { authHandler as GET, authHandler as POST };

Features

Product Catalog Management
Unified Payment Processing
Inventory Synchronization
Schema.org Compliance
Full TypeScript Support

Requirements

Next.js 13 or later
Node.js 18 or later
UCP Merchant Account (for payments)

Learn more about the Universal Commerce Protocol at ucp.dev or Google Merchant UCP Guides.

UCP Specification