gtstudio/module-ucp

Universal Commerce Protocol (UCP) implementation for Magento 2. Enables AI agent-driven checkout via Google's open commerce standard.

Maintainers

Package info

github.com/gabrielgts/module-ucp

Type:magento2-module

pkg:composer/gtstudio/module-ucp

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

1.0.0 2026-03-25 03:24 UTC

Requires

  • php: >=8.1
  • magento/framework: >=2.4.4

MIT bc7d3e1a07711066e27705e859e106aa876f696e

  • Gabriel Silveira

This package is auto-updated.

Last update: 2026-05-22 18:56:44 UTC

README

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.

UCP checkout flow

What It Does

  • Exposes /.well-known/ucp profile 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_checkout agent can drive sessions programmatically.
  • Seeds a ucp_checkout agent 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

  1. Router (Controller/Router.php) — registered at sortOrder=20, intercepts /.well-known/ucp and /ucp/checkout-sessions/* before Magento's standard router.
  2. Controllers — thin HTTP boundary classes extending AbstractCheckout; delegate to CheckoutSessionManagementInterface.
  3. CheckoutSessionManagement — core business logic: creates/updates Magento quotes, maps UCP payloads to Magento API calls, persists UcpSession records.
  4. SessionMapper — converts CartInterface to 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> for Gtstudio\Ucp\Api\CheckoutSessionManagementInterface.
  • Add custom profile capabilities by replacing Gtstudio\Ucp\Api\ProfileBuilderInterface.
  • The UcpSession model 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.