How to Add UCP to Magento (There Is No Native Support — Yet)

Magento does not speak UCP. There is no module to enable, no checkbox in the admin, no Adobe Commerce release note. The Universal Commerce Protocol was co-authored by Shopify — which ships it first-party — and the rest of the platform world, Magento included, has to add it by hand.

So if you want an AI agent (Google’s AI Mode, Gemini, Microsoft Copilot Checkout) to find a product in your Magento catalog, build a cart, and complete a purchase without a human ever touching your storefront, you are building that bridge yourself. This is the map of what that actually takes, written against the real 2026-04-08 spec — not the press release.

What UCP is, in one paragraph

UCP (Universal Commerce Protocol) is an open, Apache-2.0 standard for how AI agents transact with stores. Google and Shopify announced it at NRF in January 2026, backed by Amazon, Walmart, Target, Stripe, Meta, Salesforce and others. It is a spec, not a server: the reference implementations (Python/FastAPI, Node/Hono) live in a separate samples repo, and there is no official Magento, WooCommerce, or PHP SDK. “Adding UCP” means implementing the spec’s surfaces against your platform’s own APIs.

The capabilities you have to expose

UCP models a store as a set of capabilities, each in a reverse-DNS namespace, each reachable over a transport (REST, MCP, or A2A — your choice). For the Shopping vertical (the only one fully specified; Lodging and Food are still “coming soon”):

The two front doors

Discovery is two separate well-known files. Do not conflate them.

GET https://yourstore.com/.well-known/ucp
        → the UCP profile: which capabilities you support,
          on which transports, at which endpoints, with which signing keys

GET https://yourstore.com/.well-known/oauth-authorization-server
        → RFC 8414 OAuth metadata for Identity Linking
          (falls back to /.well-known/openid-configuration)

The profile is the whole game — it is the single URL an agent hits first. Here is the services block from the spec, showing the same shopping capabilities offered over both REST and MCP:

{
  "dev.ucp.shopping": [
    {
      "version": "2026-04-08",
      "transport": "rest",
      "endpoint": "https://yourstore.com/ucp/v1",
      "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json"
    },
    {
      "version": "2026-04-08",
      "transport": "mcp",
      "endpoint": "https://yourstore.com/ucp/mcp",
      "schema": "https://ucp.dev/2026-04-08/services/shopping/mcp.openrpc.json"
    }
  ]
}

Note the endpoint is any URL you choose — the spec’s paths (/checkout-sessions, /orders/{id}) are appended to it. And because the same capabilities can ride REST or MCP, an existing MCP server for your store is already a valid UCP transport. More on that below.

The endpoints, concretely

Checkout (paths relative to your endpoint):

Order:

Catalog: search and lookup operations, whose exact paths are defined in the referenced OpenAPI schema rather than inline in the prose spec.

A minimal create request is genuinely small — the agent sends an item and a quantity, and your session does the rest:

POST /checkout-sessions
UCP-Agent: profile="https://agent.example/profile"
Idempotency-Key: 6f2a…-uuid
Content-Type: application/json

{ "line_items": [ { "item": { "id": "item_123" }, "quantity": 2 } ] }

The session you return carries the whole state — status, buyer, line items, totals, fulfillment, payment.instruments, messages, and once complete, the order. Prices are integer minor units (2500 = $25.00), and status flows incomplete → ready_for_complete → completed.

The auth you can’t skip

This is where “agent-ready” gets real, and where Magento gives you the least help.

• Identity Linking is OAuth 2.0 Authorization Code + PKCE, S256 mandatory (plain is forbidden). Scopes are {capability}:{permission}, e.g. dev.ucp.shopping.order:read, dev.ucp.shopping.checkout:manage.
• Every REST call authenticates with one of: API key (X-API-Key), OAuth Bearer, HTTP Message Signatures (RFC 9421), or mutual TLS — and must carry UCP-Agent, Idempotency-Key (cached ≥24h), and Request-Id headers over TLS 1.3.
• Payment rides AP2 (Agent Payments Protocol): the checkout session carries payment_handlers, and AP2 supplies the payment mandate so the agent’s wallet pays while you remain Merchant of Record. (AP2’s detailed mechanics are the least-settled part of the spec today — verify against the live AP2 docs before you build the money leg.)

How this maps onto Magento — and where the gaps are

Most of what UCP asks for, Magento already does under a different name. The work is translation, plus two genuine gaps.

The bare minimum to implement it

Strip it to the smallest thing an agent can actually transact against, and it is a single Composer module doing seven jobs:

1. Serve /.well-known/ucp. A controller returning your profile JSON: the shopping capability, your transport(s), your endpoint base, your signing keys. This is the front door; without it you are invisible.
2. Serve /.well-known/oauth-authorization-server. The OAuth 2.0 metadata document (issuer, authorization/token/jwks endpoints, code_challenge_methods_supported: ["S256"]).
3. Catalog search + lookup. A thin façade over ProductRepositoryInterface and Magento search that returns products in the UCP catalog shape.
4. Checkout sessions. The five endpoints above, backed by a Magento quote: create spins up a quote, update sets items/address, tax and totals come from Magento’s totals collectors, complete places the order via CartManagementInterface::placeOrder.
5. Order read + shipment webhooks. GET /orders/{id} off OrderRepositoryInterface, plus an observer on shipment/delivery that POSTs a signed order entity to the agent’s webhook URL.
6. OAuth 2.0 + PKCE. The real work item. Magento’s built-in integration OAuth is 1.0a and does not fit; you add an OAuth 2.0 authorization server (a library, or bridge to your identity provider) that issues scoped tokens against Magento customers.
7. AP2 payment. Accept the agent’s payment mandate at complete and settle through your existing PSP while remaining Merchant of Record.

A skeleton module is small in file count:

app/code/YourCo/Ucp/
├── registration.php
├── etc/module.xml
├── etc/frontend/routes.xml         # routes /.well-known/ucp + /ucp/v1/*
├── etc/di.xml                      # wire the façades to Magento service contracts
├── Controller/WellKnown/Ucp.php    # the profile document
├── Controller/WellKnown/Oauth.php  # the OAuth metadata document
├── Controller/CheckoutSessions/    # Create / Get / Update / Complete / Cancel
├── Controller/Orders/Get.php
├── Model/SessionMapper.php         # Quote  ↔ UCP checkout session
├── Model/OrderMapper.php           # Order  ↔ UCP order
├── Model/CatalogMapper.php         # Product ↔ UCP catalog item
└── Observer/EmitOrderWebhook.php   # signed shipment events

The honest scoping: items 1–5 are mapping work — mechanical, testable, a few hundred lines against interfaces Magento already exposes. Items 6 and 7 are the hard 20%: OAuth 2.0/PKCE and AP2 are where a weekend prototype turns into real engineering, because Magento gives you nothing reusable for either.

The caveats worth stating out loud

• The spec is date-versioned and moving. 2026-04-08 is current; there is no semver, so pin your version and expect to track releases.
• Only Shopping is real. Lodging and Food are on the roadmap.
• No Magento reference exists. The official samples are Python and Node only. Any Magento guide today (including this one) is community work, not Adobe’s.
• AP2 is the soft spot. The payment-mandate mechanics are the least-documented corner of the spec — don’t ship the money leg off a blog post, including this paragraph.

Where WisWes fits

WisWes already exposes a Magento store to AI agents over MCP — one of UCP’s three sanctioned transports — through the WisWes_MCP module: catalog search, cart, checkout guidance, and order lookup, in-process against Magento’s service layer. In UCP terms, that is the mcp binding in your profile already built. Going fully UCP-native is then additive: publish the two .well-known documents, add the REST checkout-session surface for agents that prefer REST over MCP, and layer OAuth 2.0 identity linking on top. The commerce plumbing — the quote/order/catalog mapping that is 80% of the work — is the part that already exists. If you want the deeper story on running AI logic inside Magento itself, see How to Build Custom AI Inside Magento and MCP Tools in AI Ecommerce Agents.

FAQ

Does Magento (Adobe Commerce) support UCP out of the box?
No. As of mid-2026 there is no native UCP in Magento or Adobe Commerce and no official SDK. Shopify ships it first-party; Magento merchants implement it themselves via a module.

What is the absolute minimum to be “agent-ready”?
A module that serves /.well-known/ucp, exposes catalog search plus the checkout-session endpoints mapped onto a Magento quote, returns orders, and authenticates agents. Discovery + checkout + order + auth is the floor.

Do I have to build REST if I already have an MCP server?
Not necessarily. UCP is transport-agnostic — MCP and A2A are first-class alternatives to REST. An existing MCP server for your store can be declared as an mcp transport in your profile. Add REST only for agents that require it.

Who pays, and do I lose control of the order?
You stay Merchant of Record. Payment is delegated through AP2 to the agent’s wallet, but the order, fulfillment, and customer relationship remain yours.

Is it worth doing now?
UCP is already wired into Google AI Mode, Gemini, and Copilot Checkout for 20+ retailers. If agent-driven discovery matters to your category, the discovery document is a low-cost way to stop being invisible to those agents while you scope the deeper checkout work.

WisWes is an AI sales assistant for Magento, Shopware, and Shopify — already agent-reachable over MCP, and the shortest path to making your store buyable by the next wave of shopping agents.