Building a Dual-Protocol Checkout with Agorio SDK: Support UCP and ACP in Your AI Commerce Agent

The AI commerce landscape is rapidly standardizing around two open protocols: Google's Universal Commerce Protocol (UCP) and OpenAI's Agentic Commerce Protocol (ACP). By holiday 2026, Visa and Mastercard will enable all US cardholders for agent transactions, while Shopify's 4.8M merchants are discoverable via UCP and Stripe's 1.5M merchants can accept ACP payments with one line of code.

For developers building AI shopping agents, this creates a critical challenge: should you implement UCP, ACP, or both?

In this step-by-step tutorial, you'll learn how to build a dual-protocol checkout system using the Agorio SDK — the only open-source toolkit that supports both UCP and ACP with auto-detection. We'll walk through setting up a TypeScript project, discovering merchants via UCP, managing checkout sessions via ACP, and assembling a full-featured shopping agent.

Why Dual-Protocol Support Matters

UCP and ACP solve different problems:

Protocol	Lead Developers	Primary Use Case	Discovery Method	Payment Model
UCP	Google, Shopify, 25+ partners	Full commerce lifecycle (discovery, cart, checkout, order tracking)	Decentralized (/.well-known/ucp)	Multiple handlers (Google Pay, Shop Pay, tokenization)
ACP	OpenAI, Stripe	Checkout-focused, delegated payment	Centralized (merchant application)	Any PSP via delegated payment (Stripe first)

Merchants are adopting both. If your agent only supports one protocol, you'll miss transactions on the other. The smart solution: support both, but avoid writing twice the code.

What Agorio Provides

Agorio abstracts the protocol differences behind a unified API:

• UcpClient – Discovers merchants via /.well-known/ucp, normalizes capability formats, handles REST/MCP/A2A transports.
• AcpClient – Manages ACP checkout sessions (create, get, update, complete, cancel) with Bearer auth and request tracing.
• ShoppingAgent – 17 built‑in tools that work across both protocols via automatic detection.
• MockMerchant – A full UCP‑compliant test server, plus ACP‑only and MCP‑only variants.
• LLM adapters – Gemini, Claude, OpenAI, Ollama — swap without changing your agent logic.

With Agorio, you write commerce logic once; the SDK adapts to the merchant's supported protocol.

Step 1: Project Setup

Start a new TypeScript project and install Agorio:

npm init -y
npm install typescript ts-node @types/node --save-dev
npm install @agorio/sdk

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "outDir": "./dist",
    "strict": true
  }
}

Step 2: Discover a Merchant via UCP

First, let's discover a merchant's capabilities using the UcpClient. The client automatically fetches the /.well-known/ucp manifest and normalizes the capability format.

import { UcpClient } from '@agorio/sdk';

const client = new UcpClient();

async function discoverMerchant(domain: string) {
  try {
    const result = await client.discover(domain);
    console.log(`Merchant ${domain} supports:`);
    result.capabilities.forEach(cap => {
      console.log(`  - ${cap.name} (${cap.version})`);
    });
    return result;
  } catch (error) {
    console.error(`Discovery failed:`, error);
    return null;
  }
}

// Example: discover a UCP-enabled merchant
await discoverMerchant('shop.example.com');

The result object contains normalized services, payment handlers, and transport bindings. You can now invoke any UCP capability (catalog, cart, checkout) using the client's REST or MCP transport.

Step 3: Create an ACP Checkout Session

For merchants that support ACP (like Stripe‑enabled stores), you'll manage checkout sessions via the AcpClient. ACP uses delegated payment: the user's payment method stays with their PSP (Stripe, PayPal), and the agent acts as an operator.

import { AcpClient } from '@agorio/sdk';

const acp = new AcpClient({
  baseUrl: 'https://api.stripe.com/acp/v1', // Replace with merchant's ACP endpoint
  apiKey: process.env.STRIPE_API_KEY!,
});

async function createAcpCheckout(productId: string, quantity: number) {
  const session = await acp.createCheckout({
    lineItems: [{
      productId,
      quantity,
      price: {
        amount: 2999, // $29.99 in minor units (cents)
        currency: 'USD',
      },
    }],
    merchantDomain: 'shop.example.com',
  });

  console.log(`ACP checkout session ${session.id} created`);
  console.log(`Status: ${session.status}`); // "not_ready_for_payment"
  return session;
}

const session = await createAcpCheckout('prod_123', SB_1);

The AcpClient handles all required headers (Authorization, API‑Version, Idempotency‑Key, Request‑Id) and validates responses against the ACP schema.

Step 4: Build a Dual-Protocol Shopping Agent

Now combine both clients into a single ShoppingAgent. The agent automatically detects whether a merchant speaks UCP or ACP and uses the appropriate client.

import { ShoppingAgent, GeminiAdapter } from '@agorio/sdk';

const agent = new ShoppingAgent({
  llm: new GeminiAdapter({ apiKey: process.env.GEMINI_API_KEY! }),
  verbose: true,
  // ShoppingAgent automatically instantiates UcpClient and AcpClient
});

async function runShoppingTask(task: string) {
  const result = await agent.run(task);

  console.log(result.answer);           // Natural language summary
  console.log(result.checkout?.orderId); // Order ID if purchase completed
  console.log(result.usage?.totalTokens); // LLM token usage

  return result;
}

// This single command works for both UCP and ACP merchants:
await runShoppingTask('Go to shop.example.com and buy wireless headphones');

The agent's 17 built‑in tools handle the entire flow: merchant discovery, product search, adding to cart, submitting shipping and payment, and order tracking. You can extend with custom tools via plugins.

Step 5: Test with Mock Merchants

Before hitting real merchants, test with Agorio's mock servers. MockMerchant provides a full UCP‑compliant server; MockAcpMerchant provides an ACP‑only server.

import { MockMerchant, MockAcpMerchant } from '@agorio/sdk';

// Start a UCP merchant
const ucpMerchant = new MockMerchant();
await ucpMerchant.start();
console.log(`UCP mock merchant running at ${ucpMerchant.domain}`);

// Start an ACP merchant
const acpMerchant = new MockAcpMerchant();
await acpMerchant.start();
console.log(`ACP mock merchant running at ${acpMerchant.domain}`);

// Test your agent against the mock
const result = await agent.run(`Go to ${ucpMerchant.domain} and buy a laptop`);
console.log(`Order placed:`, result.checkout?.orderId);

// Clean up
await ucpMerchant.stop();
await acpMerchant.stop();

Both mocks simulate realistic latency, support configurable error rates for chaos testing, and provide structured product catalogs (10 products by default).

Step 6: Deployment Considerations

When moving to production, keep these points in mind:

1. LLM cost control – Set maxIterations in AgentOptions to limit agent loops.
2. Observability – Use the onLog callback to stream logs to your monitoring system, or integrate with Agorio Cloud for full tracing.
3. Session storage – Swap MemorySessionStorage for FileSessionStorage or @agorio/session-redis in multi‑process deployments.
4. Idempotency – Always pass idempotencyKey on completeCheckout to prevent duplicate charges.
5. Compliance – If you handle EU users, enable the built‑in EU AI Act compliance export (GET /api/compliance/export).

Conclusion: Why Agorio is the Right Choice

Building dual‑protocol AI commerce agents from scratch requires deep knowledge of both UCP and ACP specs, plus months of implementation work. Agorio gives you:

• Protocol agnosticism – Write once, run on UCP, ACP, or both.
• Production‑ready tooling – Mock merchants, LLM adapters, observability, CLI.
• Enterprise hardening – RBAC, audit logs, compliance exports, security posture.

The SDK is open‑source (MIT), has zero runtime fees, and already powers agents handling real purchases.

Get started today:

• npm: npm install @agorio/sdk
• GitHub: github.com/Nolpak14/agorio
• Docs: agorio.dev/docs
• Playground: agorio.dev/playground

If you're building AI commerce agents, join the 10+ GitHub stars and 46+ weekly npm downloaders who've chosen Agorio as their foundation. Ship your agent in 20 lines, not 20 weeks.