Agentic Commerce

@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

Feature Description Dual protocol support Both UCP and ACP endpoints from a single plugin Product discovery Full-text search and direct lookup for agents to browse your catalog Checkout sessions Create, update, complete, and cancel — with idempotency built in Pluggable payments Bring your own payment handler via the adapter interface Order tracking Agents can retrieve order status and details Webhook notifications Automatic agent callbacks on order placement Protocol discovery Copy to clipboard/.well-known/ucp and Copy to clipboard/.well-known/acp.json for automatic capability detection Product feed sync Scheduled job to push your catalog to agent platforms

Quick Start

1. Install

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

2. Configure Copy to clipboardmedusa-config.ts

1234567891011121314151617181920
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",

3. Set Environment Variables

12345678
# 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

1
npx medusa develop

Your agent APIs are now live:

12345678910
# 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.

Endpoint Method Description Copy to clipboard/.well-known/ucp GET Protocol discovery and capabilities Copy to clipboard/ucp/catalog/search POST Full-text product search Copy to clipboard/ucp/catalog/lookup POST Direct product lookup by ID or handle Copy to clipboard/ucp/carts POST Create a new cart Copy to clipboard/ucp/carts/:id GET Retrieve cart Copy to clipboard/ucp/carts/:id PUT Update cart (add/remove items, set address) Copy to clipboard/ucp/checkout-sessions POST Create checkout session from cart Copy to clipboard/ucp/checkout-sessions/:id GET Retrieve checkout session Copy to clipboard/ucp/checkout-sessions/:id PUT Update checkout session Copy to clipboard/ucp/checkout-sessions/:id/complete POST Complete checkout and place order Copy to clipboard/ucp/checkout-sessions/:id/cancel POST Cancel checkout session Copy to clipboard/ucp/orders/:id GET Retrieve order details

Required headers: Copy to clipboardUCP-Agent, Copy to clipboardRequest-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.

Endpoint Method Description Copy to clipboard/.well-known/acp.json GET Protocol discovery and capabilities Copy to clipboard/acp/checkout_sessions POST Create checkout session Copy to clipboard/acp/checkout_sessions/:id GET Retrieve checkout session Copy to clipboard/acp/checkout_sessions/:id POST Update checkout session Copy to clipboard/acp/checkout_sessions/:id/complete POST Complete checkout Copy to clipboard/acp/checkout_sessions/:id/cancel POST Cancel checkout session Copy to clipboard/acp/orders/:id GET Retrieve order Copy to clipboard/acp/product-feed GET Retrieve product feed

Required headers: Copy to clipboardAuthorization: Bearer <api_key>, Copy to clipboardAPI-Version

Payment Handlers

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

Using the Prism Payment Handler

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

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

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

Building a Custom Payment Handler

Implement the Copy to clipboardPaymentHandlerAdapter interface:

1234567891011121314151617181920
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[]> {

Register it as a Medusa module and reference it in Copy to clipboardpayment_handler_adapters:

12345678910111213141516
// 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

1234567891011
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 (Copy to clipboardreq.scope) via middleware — not from the module's constructor. This ensures all modules are registered and accessible at request time.

1234
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:

Workflow Description Copy to clipboardcreateCheckoutSessionWorkflow Validates cart, resolves region, prepares payment Copy to clipboardupdateCheckoutSessionWorkflow Handles item/address changes, re-prepares payment Copy to clipboardcompleteCheckoutSessionWorkflow Completes payment, creates order Copy to clipboardcancelCheckoutSessionWorkflow Cancels session and releases resources

Import them in your custom code:

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

Configuration

Plugin Options

Option Type Default Description Copy to clipboardapi_key Copy to clipboardstring Copy to clipboard"" API key for ACP Bearer token authentication Copy to clipboardsignatureKey Copy to clipboardstring Copy to clipboard"" HMAC-SHA256 key for request signing Copy to clipboardstorefront_url Copy to clipboardstring Copy to clipboard"http://localhost:8000" Public URL of your storefront Copy to clipboardstore_name Copy to clipboardstring Copy to clipboard"My Store" Store name in protocol responses Copy to clipboardstore_description Copy to clipboardstring Copy to clipboard"" Store description for discovery Copy to clipboardpayment_provider_id Copy to clipboardstring Copy to clipboard"pp_system_default" Medusa payment provider ID Copy to clipboardpayment_handler_adapters Copy to clipboardstring[] Copy to clipboard[] Module keys of payment handler adapters Copy to clipboarducp_version Copy to clipboardstring Copy to clipboard"2026-01-11" UCP protocol version to advertise Copy to clipboardacp_version Copy to clipboardstring Copy to clipboard"2026-01-30" ACP protocol version to advertise

Environment Variables

Variable Maps to Copy to clipboardAGENTIC_COMMERCE_API_KEY Copy to clipboardapi_key Copy to clipboardAGENTIC_COMMERCE_SIGNATURE_KEY Copy to clipboardsignatureKey Copy to clipboardSTOREFRONT_URL Copy to clipboardstorefront_url Copy to clipboardAGENTIC_STORE_NAME Copy to clipboardstore_name Copy to clipboardAGENTIC_STORE_DESCRIPTION Copy to clipboardstore_description Copy to clipboardAGENTIC_PAYMENT_PROVIDER Copy to clipboardpayment_provider_id

Exported Utilities

1234567891011121314151617181920
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,

Protocol Compliance

Types and formatters are audited against the official protocol specifications:

• UCP Copy to clipboard2026-01-11 — catalog, checkout, fulfillment, payment, order, discovery
• ACP Copy to clipboard2026-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 Copy to clipboard@financedistrict/medusa-plugin-prism-payment declares this package as a peer dependency with a Copy to clipboard^ range (e.g., Copy to clipboard^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