Architecture

Architecture

The big-picture mental model for how medusa-plugin-agentic-commerce works. Read this before diving into any other page — it's the lens everything else assumes.

The gateway pattern

The plugin is a protocol gateway, not a payment product. It implements the UCP and ACP wire protocols on top of Medusa's modules and routes payment-related calls to pluggable handlers (Prism, Stripe, etc.). It does not move money itself; the handler does.

                    ┌──────────────────────┐
   AI agent  ──────▶│  Medusa backend      │
   (UCP/ACP)        │                      │
                    │  + this plugin       │
                    │    (auto-mounted     │
                    │     routes,          │
                    │     workflows,       │
                    │     subscribers)     │
                    └──────┬───────┬───────┘
                           │       │
                           │       │  HTTP
                           │       ▼
                           │   ┌────────────────┐
                           │   │ Payment handler│  one per registered
                           │   │ (Prism/Stripe/…)│  handler — the plugin
                           │   └────────────────┘  just dispatches
                           │
                           │ Module DI
                           ▼
                    ┌──────────────────────┐
                    │ Medusa modules        │  products, carts, orders,
                    │ (cart, product,       │  shipping, regions
                    │  order, payment, …)   │
                    └──────────────────────┘

Two design rules fall out of this:

1. No payment-specific logic in the gateway. Every payment handler is interchangeable from the plugin's point of view. Prism is just one of N possible handlers a merchant could use.
2. No replication of Medusa concerns. Anything Medusa already models (regions, currencies, shipping options, products) is read at request time and translated. Adding handler-style configuration for things Medusa already configures is a smell — see Two integration patterns.

Two integration patterns

Not every concern in UCP/ACP is a third-party service. The plugin keeps two patterns separate:

Pattern A — External services (handler registry)

Examples: payment handlers (Prism, Stripe, future tax/address services).

• Source of truth lives outside Medusa
• Each is a separate deployable service or vendor
• The plugin discovers handlers via payment_handler_adapters config and routes traffic to the matching adapter at request time

Pattern B — Medusa-native concerns (read-through translation)

Examples: shipping options, regions, currencies, products, addresses.

• Source of truth lives in Medusa, configured via Medusa's existing admin UI
• The plugin reads from Medusa modules at request time and translates to UCP/ACP shape
• The plugin has no configuration option for these — Medusa already does

This means there will never be an "Agentic Shipping" tab in the Medusa admin. Merchants configure shipping via Medusa's standard Shipping Options / Profiles flow; agents see whatever's currently active.

When unsure: default to Pattern B. Adding an "Agentic X" surface should require justification.

What's automatic, what you configure

The plugin uses Medusa v2's plugin loader, which auto-registers:

Surface	Where it lives	Auto-registered?
Routes (/.well-known/*, /ucp/*, /acp/*)	packages/core/src/api/	✅
Workflows (create/update/complete checkout)	packages/core/src/workflows/	✅
Subscribers (order events → agent callbacks)	packages/core/src/subscribers/	✅
Scheduled jobs (product feed sync)	packages/core/src/jobs/	✅
Core service (agenticCommerce)	packages/core/src/modules/agentic-commerce/	configured via modules:
Payment handler adapters	Each handler's own modules/*	configured via modules: + payment_handler_adapters

So the merchant's medusa-config.ts only registers modules explicitly. Routes and lifecycle hooks come for free.

Configuration model

Medusa v2 doesn't have an external "App" with its own database — config lives in medusa-config.ts and resolves at boot. There's only one configuration path here, unlike the Saleor side which has a separate Dashboard App.

If you want runtime config changes (toggling protocols, swapping API keys without redeploy), you currently need to deploy with new env vars. Future versions may add a Medusa admin panel for this — the plugin's agenticCommerce service is already structured to read config from a database table if/when that's added.

Where to read more

• Quick Start — full configuration walkthrough
• Build a Handler — author your own payment handler package
• UCP and ACP — protocol overview, what we support
• Authentication — every token in the system