Skip to content

Quick Start

Jump to bottom
Janno Jaerv edited this page May 5, 2026 · 1 revision

Quick Start

Get your Medusa v2 store discoverable by AI agents in under 10 minutes. No frontend changes required — everything is a backend plugin.

Prerequisites

  • Medusa v2 (2.x) backend, running locally or deployed
  • Node.js >= 20
  • PostgreSQL (standard Medusa requirement)

If you don't have Medusa installed yet, follow the Medusa Quick Start first, then come back here.

1. Install the packages

npm install \
  @financedistrict/medusa-plugin-agentic-commerce \
  @financedistrict/medusa-plugin-prism-payment

Skip medusa-plugin-prism-payment if you don't need stablecoin payments. You can always add a payment handler later — see Build a Handler.

2. Configure medusa-config.ts 

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

export default defineConfig({
  plugins: [
    {
      resolve: "@financedistrict/medusa-plugin-agentic-commerce",
      options: {},
    },
  ],
  modules: [
    // Prism payment handler adapter — UCP/ACP discovery + checkout-prepare
    {
      key: "prismPaymentHandler",
      resolve: "@financedistrict/medusa-plugin-prism-payment/modules/prism-payment-handler",
      options: {
        api_url: process.env.PRISM_API_URL || "https://prism-gw.fd.xyz",
        api_key: process.env.PRISM_API_KEY,
      },
    },
    // Prism Medusa payment provider — authorize/capture/refund
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@financedistrict/medusa-plugin-prism-payment/modules/prism-payment",
            id: "prism",
            options: {
              api_url: process.env.PRISM_API_URL || "https://prism-gw.fd.xyz",
              api_key: process.env.PRISM_API_KEY,
            },
          },
        ],
      },
    },
    // Core agentic commerce service
    {
      key: "agenticCommerce",
      resolve: "@financedistrict/medusa-plugin-agentic-commerce/modules/agentic-commerce",
      options: {
        api_key: process.env.AGENTIC_COMMERCE_API_KEY,
        storefront_url: process.env.STOREFRONT_URL || "https://your-store.com",
        store_name: "Your Store Name",
        store_description: "What your store sells",
        payment_handler_adapters: ["prismPaymentHandler"],
      },
    },
  ],
})

The three-module shape is intentional:

  • prismPaymentHandler — agent-side concerns (discovery, payment requirements). Plugged into the agentic-commerce service via payment_handler_adapters.
  • Prism payment provider — Medusa's standard payment-provider concerns (authorize/capture/refund). Plugged into Medusa's payment module via the providers array.
  • agenticCommerce — the core service that ties everything together and serves the UCP/ACP routes.

If you're using a different payment handler (or your own), only the first two change.

3. Set environment variables

# Agentic Commerce
AGENTIC_COMMERCE_API_KEY=your-secret-api-key
STOREFRONT_URL=https://your-store.com

# Prism Payment (skip if you're not using stablecoin payments)
PRISM_API_URL=https://prism-gw.fd.xyz
PRISM_API_KEY=your-prism-api-key

AGENTIC_COMMERCE_API_KEY becomes the Bearer token agents use to call ACP endpoints. Generate something opaque (openssl rand -base64 32).

4. Start your store

npx medusa develop

The plugin auto-mounts:

  • GET /.well-known/ucp — UCP discovery
  • GET /.well-known/acp.json — ACP discovery (capabilities only — handlers come per-session, see UCP and ACP)
  • POST /ucp/checkout-sessions and friends — UCP checkout flow
  • POST /acp/checkout_sessions and friends — ACP checkout flow

No route files to create. Plugin auto-discovery handles it.

5. Verify it works

# UCP discovery — open by default
curl http://localhost:9000/.well-known/ucp | jq .

# ACP discovery — also open
curl http://localhost:9000/.well-known/acp.json | jq .

# 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}'

You should see your store's UCP profile, available services, and registered payment handlers in the discovery response.

6. (Optional) Test the ACP Bearer auth

ACP requires Authorization: Bearer <token> per spec. The token is whatever you set as AGENTIC_COMMERCE_API_KEY:

curl -X POST http://localhost:9000/acp/checkout_sessions \
  -H "Authorization: Bearer $AGENTIC_COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"line_items": [{"id": "<some-product-variant-id>", "quantity": 1}]}'

What's next

Troubleshooting

Discovery endpoint 404s? Make sure the plugin is in the plugins array (not just modules). The routes are auto-registered by the plugin loader, not by module resolution.

payment_handler_adapters: ["prismPaymentHandler"] doesn't resolve? The string must match the key of the handler module above. Common typos: prism-payment-handler (wrong), prismPayment (wrong).

Prism returns 401? Set PRISM_API_KEY to a real key from the Prism merchant dashboard. The handler logs a warning and serves an empty payment config when no key is set, but discovery responses won't include any Prism handler.

ACP routes return 401? Set AGENTIC_COMMERCE_API_KEY env var, and include Authorization: Bearer <that-value> on the request.

Clone this wiki locally