Universal Commerce Protocol (UCP) for Magento 2
gtstudio/module-ucp
Implements Google's Universal Commerce Protocol so AI shopping agents can discover and drive checkout, exposing the /.well-known/ucp profile and the five UCP checkout session endpoints mapped to Magento quote state.
Build Tests
Code Quality
Tested on Magento 2.4.9
Recent Test History
Each release is tested against the latest Magento version at that time.
Share This Module's Status
README
Loaded from GitHubGtstudio_Ucp
Magento 2 module implementing Google's Universal Commerce Protocol (UCP) — an open standard that allows AI shopping agents to discover and drive checkout sessions on any compliant merchant.
What It Does
- Exposes
/.well-known/ucpprofile discovery endpoint so AI agents can locate the checkout API. - Implements the five UCP checkout session endpoints (
create,get,update,complete,cancel). - Maps Magento quote state to UCP session state (
incomplete→ready_for_complete→completed | cancelled). - Registers five AiAgents tools so the
ucp_checkoutagent can drive sessions programmatically. - Seeds a
ucp_checkoutagent with a UCP-aware system prompt via data patch.
Installation
composer require gtstudio/module-ucp
bin/magento module:enable Gtstudio_Ucp
bin/magento setup:upgrade
Endpoints
| Method | Path | Description |
|---|---|---|
GET |
/.well-known/ucp |
Profile discovery |
POST |
/ucp/checkout-sessions |
Create session |
GET |
/ucp/checkout-sessions/:id |
Get session |
PUT/PATCH |
/ucp/checkout-sessions/:id |
Update session |
POST |
/ucp/checkout-sessions/:id/complete |
Place order |
POST |
/ucp/checkout-sessions/:id/cancel |
Cancel session |
Session Lifecycle
incomplete
→ (add buyer email) requires_escalation | ready_for_complete
→ (complete with payment) completed
→ (cancel at any point) cancelled
Status is resolved dynamically from the linked Magento quote on every get or update call.
How It Works
- Router (
Controller/Router.php) — registered atsortOrder=20, intercepts/.well-known/ucpand/ucp/checkout-sessions/*before Magento's standard router. - Controllers — thin HTTP boundary classes extending
AbstractCheckout; delegate toCheckoutSessionManagementInterface. - CheckoutSessionManagement — core business logic: creates/updates Magento quotes, maps UCP payloads to Magento API calls, persists
UcpSessionrecords. - SessionMapper — converts
CartInterfaceto UCP JSON, resolves session state, surfaces recoverable validation messages.
Validation
Use the UCP conformance test suite or ucpchecker.com to validate the endpoints against the protocol spec.
Extensibility
- Swap the session mapper by declaring a
<preference>forGtstudio\Ucp\Api\CheckoutSessionManagementInterface. - Add custom profile capabilities by replacing
Gtstudio\Ucp\Api\ProfileBuilderInterface. - The
UcpSessionmodel exposes standard Magento getter/setter methods for plugin attachment.
AI Studio Ecosystem
| Module | Description |
|---|---|
| module-ai-connector | LLM provider abstraction (OpenAI, Anthropic, Gemini) |
| module-ai-agents | Agent orchestration, tools, and tool executor pool |
| module-ai-widgets | Admin chat widgets and Page Builder agent |
| module-ai-data-query | Natural-language store analytics tools |
| module-ai-knowledge-base | Vector search knowledge base |
| module-ai-dashboard | Admin AI dashboard with store assistant |
| module-ucp | (this module) |
License
Business Source License 1.1 — see LICENSE.
This content is fetched directly from the module's GitHub repository. We are not the authors of this content and take no responsibility for its accuracy, completeness, or any consequences arising from its use.