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, with Copy to clipboardsupported_versions Copy to clipboard/.well-known/ucp/:version GET Discovery profile for one enabled UCP version (404 when not enabled) 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

Versions: the store serves Copy to clipboarducp_version (default: the latest version, currently Copy to clipboard2026-08-25) plus every version in Copy to clipboarducp_supported_versions (default: every other known version, currently Copy to clipboard2026-04-08, Copy to clipboard2026-01-23). The version for a request comes from the Copy to clipboarducp.version of the agent profile named in Copy to clipboardUCP-Agent: ...; profile="https://...". The profile is fetched over HTTPS only, from public addresses only, with a 3 s timeout, a 128 KiB cap and no redirects, and cached for 10 minutes.

Agent profile Copy to clipboardlenient (default) Copy to clipboardstrict no Copy to clipboardUCP-Agent header Copy to clipboard400 missing_ucp_agent Copy to clipboard400 missing_ucp_agent no Copy to clipboardprofile in Copy to clipboardUCP-Agent current version current version unreachable or not HTTPS current version + warning log Copy to clipboard424 profile_unreachable no or malformed Copy to clipboarducp.version current version + warning log Copy to clipboard422 profile_malformed unknown version Copy to clipboard422 version_unsupported Copy to clipboard422 version_unsupported known version the store disabled Copy to clipboard422 version_unsupported Copy to clipboard422 version_unsupported enabled version that version that version

Other FD store plugins serve the current version when Copy to clipboardUCP-Agent is missing; this plugin keeps its original Copy to clipboard400.

A checkout session or cart created for a declared version stays on it. A later request that declares a different version gets Copy to clipboard422 version_unsupported; a request whose profile cannot be resolved keeps the session's version. Copy to clipboardlenient deviates from the UCP spec on purpose: agents built before version negotiation keep working. Warnings are logged as JSON with the key Copy to clipboarducp_profile_resolution. In Copy to clipboard2026-01-23, cart and catalog routes answer Copy to clipboard404 capabilities_incompatible.

Complete checkout: each Copy to clipboardpayment.instruments[] entry carries a Copy to clipboardcredential. With the Prism provider, Copy to clipboardhandler_id is Copy to clipboardxyz.fd.prism_payment, Copy to clipboardx402 or omitted; Copy to clipboardtype is Copy to clipboardx402, Copy to clipboardtokenized, Copy to clipboarddefault or omitted; Copy to clipboardcredential.type is Copy to clipboardx402 or omitted. Any other value returns Copy to clipboard422 invalid_instrument, and the signed amount must still match the cart's Prism quote. A failed payment returns Copy to clipboard422 payment_failed; responses under 500 are cached per Copy to clipboardIdempotency-Key for 24 hours, so retry with a new key.

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 latest (Copy to clipboard"2026-08-25") Current UCP version, served when the agent declares none. Set Copy to clipboard"2026-04-08" to keep the root profile of 0.x releases Copy to clipboarducp_supported_versions Copy to clipboardstring[] every known version except Copy to clipboarducp_version Further UCP versions served on request; the current version is removed from this list Copy to clipboarducp_version_negotiation Copy to clipboard"lenient" | "strict" Copy to clipboard"lenient" How an unusable agent profile is handled (see UCP above) Copy to clipboardacp_version Copy to clipboardstring Copy to clipboard"2026-01-30" ACP protocol version to advertise

An unknown version or negotiation value stops the store at boot.

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-04-08, Copy to clipboard2026-08-25 — catalog, cart, checkout, fulfillment, payment, order, discovery; Copy to clipboard2026-01-23 — 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