# UCP for Magento 2 - Profile, Catalog and Checkout, Step by Step > How to make a Magento 2 store work with UCP: the /.well-known/ucp profile, catalog search, checkout sessions, orders, webhooks and signatures. Source: https://angeo.dev/magento-ucp/ Updated: 2026-10-17 Guide - Agentic commerce # UCP for Magento 2 - Profile, Catalog and Checkout, Step by Step **The Universal Commerce Protocol (UCP) lets AI shopping agents find a store, search its catalog and build a checkout through one published contract.** This guide shows what each part means for a Magento 2 store, in the order you should build it. **In one sentence** Publish an honest profile, answer catalog calls, then let agents build checkouts that end on your own checkout page. ## UCP in four layers UCP is easier to plan when you split it into layers. Each layer needs the one before it. | Layer | What it is | Magento module | | 1. Profile | A public JSON file at `/.well-known/ucp`: who you are, what you support, where to call, your public keys | [UCP Profile](https://angeo.dev/modules/ucp/) | | 2. Catalog | `catalog.search` and `catalog.lookup`: agents find products and variants | [UCP Catalog](https://angeo.dev/modules/ucp-catalog/) | | 3. Checkout | Checkout sessions with items, buyer, coupon and shipping; orders and webhooks | [UCP Checkout](https://angeo.dev/modules/ucp-checkout/) | | 4. Transports | The same operations over REST and over MCP | [UCP Checkout over MCP](https://angeo.dev/modules/ucp-checkout-mcp/) | The profile is a promise. The other layers keep it. The most common mistake is a profile that declares checkout while nothing answers the call. ## Step 1 - Publish an honest profile The [profile](https://angeo.dev/well-known-ucp-definition/) lists services, capabilities, extensions, payment handlers and signing keys. Three rules matter most in spec 2026-08-25: - **Keys in `keys[]`.** Publish public keys only, as a JWK Set. Keep the private key on the server. - **Authority binding.** Each capability's `schema` URL must match its namespace. A platform rejects a mismatch [silently](https://angeo.dev/ucp-authority-binding/), so check it yourself before going live. - **Only declare what you serve.** A switch in the admin is not enough. Advertise checkout only when an endpoint really answers it. ``` composer require angeo/module-ucp bin/magento angeo:ucp:keys:generate bin/magento angeo:ucp:validate curl -sI https://your-store/.well-known/ucp ``` In Magento the profile is served by a controller, so it gets the right `Content-Type` and CORS headers without nginx changes. If your host blocks every path that starts with a dot, allow `/.well-known/`. ## Step 2 - Answer catalog calls An agent that read your profile will now search. UCP models a product as a set of **variants**, and the variant is what the buyer purchases. A Magento configurable product maps to that shape directly: each child is a variant with its own price, stock and options. Two details separate a good catalog from a frustrating one: - **"Does not exist" is not "out of stock".** Red/Large that was never made is different from Red/Small that is sold out. Report both facts, so the agent does not tell a shopper something is unavailable when it never existed. - **Prices in minor units.** `15000` means 150.00 in the request currency. If the store cannot convert, skip the filter and say so in the response. ``` curl -s -X POST https://your-store/ucp/v1/catalog/search \ -H 'Content-Type: application/json' \ -d '{"query":"shirt","pagination":{"limit":5}}' ``` ## Step 3 - Let agents build a checkout A [UCP checkout](https://angeo.dev/ucp-checkout-definition/) is a session the agent creates and updates. The agent adds items, the buyer's email, a coupon and a shipping address. The store answers with live totals and its own shipping options. The key decision is **who takes payment**. Payment through the agent needs payment handlers and authorization such as [AP2 mandates](https://angeo.dev/ap2-definition/). For most Magento stores in 2026 the safer route is the handoff: 1. The agent builds the session until the status is `requires_escalation`. 2. The store returns a `continue_url`. 3. The buyer opens it, lands on the normal Magento checkout with the cart, address and shipping method ready, and pays there. The store keeps its payment methods, fraud checks and terms. There is no card data in the agent flow and no new PCI scope. Make retries safe. Agents retry on timeouts, so honour the `Idempotency-Key` header: the same key with the same body returns the stored answer, and a different body gets `409`. ## Step 4 - Orders, webhooks and signatures After the buyer orders, the platform that created the checkout wants the result. The **order** capability lets it read status, shipments and refunds. **Webhooks** push those changes to the platform, signed with your store key. Signatures also work the other way. With RFC 9421 verification on, the store checks that a request really comes from the platform it claims. Start in *optional* mode: invalid signatures are refused, missing ones are logged. Move to *required* when you know which platforms sign. ## Step 5 - Offer the same checkout over MCP Some agents speak MCP, not REST. UCP defines an MCP binding with the same five checkout operations as tools. In Magento, [UCP Checkout over MCP](https://angeo.dev/modules/ucp-checkout-mcp/) adds them to your MCP server and shares sessions with REST, so an agent can even mix the two. ## How to check your work - `bin/magento angeo:ucp:validate` - profile shape, authority binding, switches with no effect. - The [UCP conformance suite](https://github.com/Universal-Commerce-Protocol/conformance) - discovery, version negotiation, the session lifecycle and idempotency. A handoff-only store will not pass the payment tests, and that is expected. - `bin/magento angeo:aeo:audit` - the `ucp_profile` signal, including leaked private keys. - [AI Agent Activity](https://angeo.dev/modules/agent-activity/) - which platforms call your UCP endpoints, and how many sessions turn into orders. ## What UCP does not do for you UCP makes a store **usable** by agents. It does not make agents choose you. Discovery still depends on accurate product data, real availability, clear policies and being known. Build UCP on top of that groundwork, not instead of it. And reaching Google's own surfaces can need acceptance into Google's programme, beyond what the protocol requires. ## Questions Do I need all four UCP modules? Start with the profile and the catalog. Add checkout when you want agents to build orders, and the MCP binding when agents that speak MCP should use the same checkout. Does UCP let an AI agent take payment in my store? Only if you add payment handlers. The common Magento setup hands the buyer back with continue_url, so they pay on your normal checkout. Is UCP the same as ACP? No. ACP comes from OpenAI and Stripe and now mostly serves product discovery in ChatGPT. UCP is advertised in /.well-known/ucp and is the route to Google AI Mode and Gemini. How do I know if agents use my UCP endpoints? Log the calls by platform. The AI Agent Activity module counts UCP profile reads, catalog calls and checkout sessions, and links orders back to them. Which UCP version should I target? 2026-08-25, the current release in October 2026. A store can keep serving an older version for platforms that integrated against it, if it declares it. ## Related - [UCP - definition](https://angeo.dev/ucp-definition/) - [/.well-known/ucp - definition](https://angeo.dev/well-known-ucp-definition/) - [UCP authority binding](https://angeo.dev/ucp-authority-binding/) - [UCP checkout - definition](https://angeo.dev/ucp-checkout-definition/) - [UCP readiness checklist for Magento 2](https://angeo.dev/ucp-readiness-checklist-magento/) - [ACP vs UCP for Magento 2](https://angeo.dev/acp-vs-ucp-for-magento-2/) - [UCP modules for Magento compared](https://angeo.dev/magento-ucp-modules-compared/) - [Gemini and Google AI Mode for Magento](https://angeo.dev/gemini-google-ai-mode-magento/) - [Magento agentic commerce hub](https://angeo.dev/magento-agentic-commerce-hub/) ## Sources - [UCP specification](https://ucp.dev/) - [UCP specification: Checkout capability](https://ucp.dev/latest/specification/shopping/checkout/) - [UCP conformance suite](https://github.com/Universal-Commerce-Protocol/conformance) - [RFC 9421: HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421) Verified 16 October 2026 against UCP spec 2026-08-25 and the module code at its latest tags. Reaching Google surfaces can also need acceptance into Google's programme. Disclosure: we publish the open-source UCP modules for Magento 2 described here.