Agentic commerce

Why

AI agents are becoming a real commerce channel. They need machine-readable APIs to browse catalogs, fill carts, handle payments, and confirm orders — without scraping HTML or reverse-engineering checkout flows.

This plugin gives your Medusa store a standards-compliant agent API in minutes. No custom code, no frontend changes. And the pluggable payment handler adapter system means any payment method — stablecoins, cards, wallets — can be added without modifying the core plugin.

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"

Requirements

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

License

MIT