UCP Checkout for Magento 2 — module reference
UCP Checkout adds the UCP checkout capability (dev.ucp.shopping.checkout, spec 2026-08-25) with the discount and fulfillment extensions, plus the order capability since 1.1.0.
An agent that speaks UCP — the protocol behind Google AI Mode and Gemini checkout — can create a checkout session over REST, add items, set the buyer, a coupon code and a shipping address, pick one of your live shipping rates and see live totals. When the buyer is ready, the agent sends them to continue_url. Their cart opens on your store with the address and shipping method already set, and they pay as usual.
No card data, no payment handler, no PCI scope.
Operations
| Operation | Endpoint | What happens |
|---|---|---|
| Create Checkout | POST {endpoint}/checkout-sessions | New guest quote with the items → 201 |
| Get Checkout | GET {endpoint}/checkout-sessions/{id} | Items, totals, status |
| Update Checkout | PUT {endpoint}/checkout-sessions/{id} | Full replacement: lines, buyer, discount code, shipping |
| Complete Checkout | POST {endpoint}/checkout-sessions/{id}/complete | requires_escalation + continue_url — never charges |
| Cancel Checkout | POST {endpoint}/checkout-sessions/{id}/cancel | Session and quote closed |
| Get Order | GET {endpoint}/orders/{order number} | Status, shipments, refunds |
| continue_url | GET /ucp/checkout/continue/{token} | Loads the cart in the buyer’s browser, then opens /checkout |
{endpoint} is https://your-store/ucp/v1 by default.
Session status
incomplete— something the agent can fix: no email, an unknown item, not enough stock. Messages say what and where (path).requires_escalation— everything the API can collect is there. The rest happens on your checkout throughcontinue_url.completed— the buyer placed the order.order.idandorder.permalink_urlare filled in.canceled— cancelled by the agent, or expired (default after 6 hours).
Shipping
One shipping method, one destination and one group. The agent writes the address into fulfillment.methods[0].destinations[0]. The response lists your live Magento rates for that address as groups[0].options, cheapest first. The agent picks one with selected_option_id. Countries outside your allowed countries and unknown options come back as fixable errors with a path. An update without fulfillment clears the address and the rate. Pickup is not offered.
Orders and webhooks (1.1.0)
After the buyer orders, the agent can read the order at GET {endpoint}/orders/{order number}: line status, shipments with tracking, refunds, cancellation and totals. Only the platform whose UCP-Agent profile created the checkout gets the order. Others get 404. Set Request Security → Inbound Signature Verification to required in UCP Profile, so the profile is proven by a signature.
If the platform’s profile declares a webhook_url for the order capability, the store POSTs the order to it on create, shipment, refund and cancel. Each call is signed (RFC 9421 + Content-Digest) with your store key and carries Webhook-Id and Webhook-Timestamp. A cron job sends every minute and retries after 1 min, 5 min, 30 min, 2 h and 12 h.
Webhook signing needs the private key in app/etc/env.php, as angeo:ucp:keys:generate prints it. The key id must also be published in the profile.
'ucp' => ['signing_keys' => ['<kid>' => '-----BEGIN PRIVATE KEY-----...']],Ids, idempotency and versions
- Item ids:
gid://magento/ProductVariant/{id}(as returned by UCP Catalog),gid://magento/Product/{id}for simple products, or a plain SKU. Configurable children are added through their parent. - Idempotency-Key on create, update, complete and cancel: the same key and body replays the stored answer. The same key with a different body gives
409. Keys are kept 24 hours. - Version negotiation through
UCP-Agent: profile="…"; version="…". Versions the store serves are accepted. Others get422.
Requirements
| Magento | 2.4.6+ (Open Source, Mage-OS or Adobe Commerce) — magento/framework >=103.0.6 <104 |
|---|---|
| PHP | 8.1 – 8.5 — ~8.1.0||~8.2.0||~8.3.0||~8.4.0||~8.5.0 |
| Other angeo modules | angeo/module-ucp ^2.2 |
| PHP extensions | json |
Installation
composer require angeo/module-ucp-checkout
bin/magento module:enable Angeo_UcpCheckout
bin/magento setup:upgrade
bin/magento setup:di:compile # production mode only
bin/magento cache:flushSetting it up
In Stores → Configuration → Angeo → UCP (Universal Commerce Protocol):
- Declared Root Capabilities → Checkout = Yes. Optional: Order, and Declared Extensions → Discount and Fulfillment.
- Transport → REST Endpoint URL: leave empty (
{baseUrl}/ucp/v1), or enter your own HTTPS URL. - Checkout Sessions: your terms, privacy and refund links (sent in every checkout), the session lifetime and the limits.
- Check the profile:
bin/magento angeo:ucp:validate
curl -s https://your-store/.well-known/ucp | jq '.ucp.capabilities | keys'Exclude /ucp/ from full-page cache (Varnish, LiteSpeed, Cloudflare). The responses send Cache-Control: no-store.
Try it
curl -s -X POST https://your-store/ucp/v1/checkout-sessions \
-H 'Content-Type: application/json' \
-H 'UCP-Agent: profile="https://agent.example/profile"' \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"line_items":[{"item":{"id":"24-MB02"},"quantity":1}],
"buyer":{"email":"jane@example.com"}}' | jq '{id, status, totals, continue_url}'Configuration reference
All settings are under Stores → Configuration → Angeo → UCP (Universal Commerce Protocol). The table shows each field, its config path (for bin/magento config:set) and its default value.
Checkout Sessions (angeo/module-ucp-checkout) (8)
| Setting | Config path | Default |
|---|---|---|
| Session Lifetime (hours) | angeo_ucp/checkout/session_ttl_hours | 6 |
| Max Line Items per Session | angeo_ucp/checkout/max_line_items | 50 |
| Max Quantity per Line | angeo_ucp/checkout/max_quantity | 1000 |
| Terms of Service URL | angeo_ucp/checkout/terms_url | — |
| Privacy Policy URL | angeo_ucp/checkout/privacy_url | — |
| Refund / Returns Policy URL | angeo_ucp/checkout/refund_url | — |
| Handoff Page Path | angeo_ucp/checkout/handoff_path | checkout |
| Keep Expired Sessions (days) | angeo_ucp/checkout/retention_days | 30 |
Cron and stored data
| Job | Cron group | Schedule |
|---|---|---|
angeo_ucp_checkout_webhooks | default | * * * * * |
angeo_ucp_checkout_cleanup | default | 17 3 * * * |
| Table | What it holds | Columns |
|---|---|---|
angeo_ucp_checkout_session | Angeo UCP checkout sessions | entity_id, session_id, quote_id, store_id, status, agent_profile, continue_token, item_refs, pending_messages, snapshot, order_id, order_increment_id, order_url, destination_id, expires_at, created_at, updated_at |
angeo_ucp_order_webhook | Angeo UCP order webhook queue | entity_id, event_id, order_id, session_id, event, status, attempts, last_status, last_error, next_attempt_at, created_at |
angeo_ucp_checkout_idempotency | Angeo UCP checkout idempotency keys | entity_id, operation, idempotency_key, session_id, request_hash, http_status, response_body, created_at |
Conformance
The official UCP conformance suite also tests completing a checkout with payment. This module does not do that on purpose, so a full run will not pass every test. Discovery, version negotiation, the create/get/update/cancel lifecycle, idempotency and shipping options are the parts it is built to pass.
Not included yet
- Payment through the agent (payment handlers, AP2, card credentials).
- Pickup, or several destinations or packages per checkout.
- Checkouts for signed-in customers over the API (identity linking).
FAQ
Does the agent take payment?
No. Complete Checkout returns requires_escalation and a continue_url. The buyer opens it, lands on your checkout with the cart ready, and pays there.
Which shipping rates does the agent see?
Your live Magento rates for the address the agent sends, cheapest first. The agent picks one, and it shows up in the totals.
Can another platform read my orders?
No. Only the platform whose UCP-Agent profile created the checkout can read the order. Use the required signature mode so that profile is proven.
How do retries work?
Send an Idempotency-Key. The same key with the same body returns the stored answer. The same key with a different body gives 409.
Can agents use MCP instead of REST?
Yes. Install UCP Checkout over MCP. It adds the same five operations as MCP tools and shares sessions with REST.
Related
- UCP Profile — a signed /.well-known/ucp profile for UCP agents
- UCP Catalog — catalog.search and catalog.lookup endpoints behind the UCP profile
- UCP Checkout over MCP — the same UCP checkout as five MCP tools
- AI Agent Activity — report on AI agent calls, crawler visits, fake bots and agent-built orders
- MCP Checkout — guest cart and checkout tools for AI agents, with server-side limits
- UCP for Magento 2 — complete guide
- UCP checkout — definition
- All module reference pages · Compatibility matrix
This page was written from the README.md, composer.json and etc/*.xml files of tag 1.1.0, read on 16 October 2026. Settings, commands and defaults come straight from that code. If a newer release is out, the README on GitHub wins.