@financedistrict/medusa-plugin-agentic-commerce

Make your Medusa v2 store shoppable by AI agents.

This plugin adds UCP and ACP protocol endpoints to your Medusa backend, so AI shopping agents can discover your products, create checkouts, and complete purchases — through standard HTTP APIs that require no frontend at all.

Why this matters

AI agents are becoming the next commerce channel. Just like merchants once added mobile apps alongside their websites, they'll soon need to serve autonomous agents that shop on behalf of consumers. But agents don't browse — they need structured APIs with standardized discovery, checkout flows, and payment settlement.

UCP (Universal Commerce Protocol) and ACP (Agentic Commerce Protocol) are the emerging open standards for this. This plugin implements both as native Medusa v2 modules, so your store speaks the language agents understand — in minutes, with no custom code and no frontend changes.

What you get

Quick Start

1. Install

npm install @financedistrict/medusa-plugin-agentic-commerce

2. Configure medusa-config.ts

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  // Register the plugin for route/workflow/subscriber auto-discovery
  plugins: [
    {
      resolve: "@financedistrict/medusa-plugin-agentic-commerce",
      options: {},
    },
  ],
  modules: [
    // Register the core service module with your configuration
    {
      key: "agenticCommerce",
      resolve: "@financedistrict/medusa-plugin-agentic-commerce/modules/agentic-commerce",
      options: {
        api_key: process.env.AGENTIC_COMMERCE_API_KEY,
        signatureKey: process.env.AGENTIC_COMMERCE_SIGNATURE_KEY,
        storefront_url: process.env.STOREFRONT_URL || "https://your-store.com",
        store_name: "Your Store Name",
        store_description: "What your store sells",
        // Reference payment handler adapter module keys (see Payment Handlers)
        payment_handler_adapters: ["prismPaymentHandler"],
      },
    },
  ],
})

3. Set Environment Variables

# Required
AGENTIC_COMMERCE_API_KEY=your-secret-api-key

# Optional
AGENTIC_COMMERCE_SIGNATURE_KEY=your-hmac-secret
STOREFRONT_URL=https://your-store.com
AGENTIC_STORE_NAME="Your Store"
AGENTIC_STORE_DESCRIPTION="Premium widgets for humans and agents"

4. Start Your Store

npx medusa develop

Your agent APIs are now live:

# Discovery
curl http://localhost:9000/.well-known/ucp
curl http://localhost:9000/.well-known/acp.json

# Search products (UCP)
curl -X POST http://localhost:9000/ucp/catalog/search \
  -H "UCP-Agent: my-agent/1.0" \
  -H "Request-Id: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query": "t-shirt", "limit": 10}'

Protocols

UCP (Unified Commerce Protocol)

UCP is designed for agent-to-merchant interactions. It uses a shopping-cart model where agents manage carts directly.

Required headers: UCP-Agent, Request-Id

ACP (Agent Commerce Protocol)

ACP is designed for platform-to-merchant interactions. It uses a session-based model where the platform manages the checkout flow.

Required headers: Authorization: Bearer <api_key>, API-Version

Payment Handlers

Payment is handled through a pluggable adapter system. Each adapter implements the PaymentHandlerAdapter interface and registers as a Medusa module.

Using the Prism Payment Handler

For x402 stablecoin payments (USDC, FDUSD, etc.), use the companion package:

npm install @financedistrict/medusa-plugin-prism-payment

See @financedistrict/medusa-plugin-prism-payment for setup instructions.

Building a Custom Payment Handler

Implement the PaymentHandlerAdapter interface:

import type {
  PaymentHandlerAdapter,
  CheckoutPrepareInput,
} from "@financedistrict/medusa-plugin-agentic-commerce"

export default class MyPaymentAdapter implements PaymentHandlerAdapter {
  readonly id = "my_payment_handler"
  readonly name = "My Payment"

  // Discovery — what to advertise in .well-known endpoints
  async getUcpDiscoveryHandlers(): Promise<Record<string, unknown[]>> {
    return {
      "com.example.my_payment": [{
        id: "my-handler",
        version: "1.0.0",
      }],
    }
  }

  async getAcpDiscoveryHandlers(): Promise<unknown[]> {
    return [{
      id: "com.example.my_payment",
      name: "My Payment",
      version: "1.0.0",
      psp: "my-psp",
      requires_delegate_payment: false,
      instrument_schemas: [/* ... */],
    }]
  }

  // Checkout preparation — called when a checkout session is created
  async prepareCheckoutPayment(input: CheckoutPrepareInput) {
    // Call your payment gateway, return config for the agent
    return { id: "my-handler", version: "1.0.0", config: { /* ... */ } }
  }

  // Response formatting — include payment config in checkout responses
  getUcpCheckoutHandlers(cartMetadata?: Record<string, unknown>) {
    return { /* ... */ }
  }

  getAcpCheckoutHandlers(cartMetadata?: Record<string, unknown>) {
    return [/* ... */]
  }
}

Register it as a Medusa module and reference it in payment_handler_adapters:

// medusa-config.ts
modules: [
  {
    key: "myPaymentHandler",
    resolve: "./src/modules/my-payment-handler",
    options: { /* ... */ },
  },
  {
    key: "agenticCommerce",
    resolve: "@financedistrict/medusa-plugin-agentic-commerce/modules/agentic-commerce",
    options: {
      payment_handler_adapters: ["myPaymentHandler"],
      // ...
    },
  },
]

Architecture

medusa-config.ts
  |
  +-- plugins: [@financedistrict/medusa-plugin-agentic-commerce]
  |     Routes, workflows, subscribers, jobs auto-discovered
  |
  +-- modules:
        +-- agenticCommerce (core service)
        |     Config, auth, formatting, payment registry
        |
        +-- prismPaymentHandler (optional adapter)
              Discovery, checkout-prepare, response formatting

How Adapter Resolution Works

Medusa v2 modules have isolated DI containers. The plugin resolves payment handler adapters from the request-scoped container (req.scope) via middleware — not from the module's constructor. This ensures all modules are registered and accessible at request time.

Request → resolvePaymentAdapters middleware → route handler
              |
              +-- req.scope.resolve("prismPaymentHandler")
              +-- agenticCommerceService.resolveAdapters(req.scope)

Workflows

The plugin provides four reusable workflows that orchestrate the checkout process:

Import them in your custom code:

import {
  createCheckoutSessionWorkflow,
  completeCheckoutSessionWorkflow,
} from "@financedistrict/medusa-plugin-agentic-commerce/workflows"

Configuration

Plugin Options

Environment Variables

Exported Utilities

import {
  // Service & module
  AgenticCommerceService,
  AgenticCommerceModule,
  AGENTIC_COMMERCE_MODULE,

  // Payment adapter interface
  PaymentHandlerAdapter,      // type
  CheckoutPrepareInput,       // type
  PaymentHandlerRegistry,

  // Error formatting
  formatAcpError,
  formatUcpError,

  // Address translation
  medusaToAcpAddress,
  acpAddressToMedusa,
  medusaToUcpAddress,
  ucpAddressToMedusa,

  // Status mapping
  resolveAcpStatus,
  resolveUcpStatus,
} from "@financedistrict/medusa-plugin-agentic-commerce"

Protocol Compliance

Types and formatters are audited against the official protocol specifications:

• UCP 2026-01-11 — catalog, checkout, fulfillment, payment, order, discovery
• ACP 2026-01-30 — checkout sessions, delegate payment, capabilities

Versioning

This package follows semver. While pre-1.0:

• Protocol spec changes → minor bump (e.g., 0.1.x → 0.2.0)
• Medusa compatibility changes → patch bump (e.g., 0.1.0 → 0.1.1)
• Bug fixes → patch bump

The companion @financedistrict/medusa-plugin-prism-payment declares this package as a peer dependency with a ^ range (e.g., ^0.1.0), so incompatible combinations are caught at install time.

Requirements

• Medusa v2 (2.x)
• Node.js >= 20
• PostgreSQL (standard Medusa requirement)

License

MIT

---