🏢 Magento / Adobe Commerce UCP Guide

Why Add UCP to Magento?

Magento (Adobe Commerce) powers some of the world's largest online stores. Adding UCP support positions your enterprise for AI-driven commerce, allowing AI agents to discover products, check inventory, and complete transactions.

• Enterprise Scale: UCP works with Magento's multi-store, multi-language setup
• GraphQL Ready: Magento's GraphQL API integrates seamlessly with UCP
• B2B Support: Expose B2B catalogs and pricing to AI agents
• Headless Compatible: Works with PWA Studio and headless setups

Prerequisites

• Magento 2.4+ or Adobe Commerce
• SSH/CLI access to your Magento installation
• Composer installed
• Basic understanding of Magento module structure

Implementation

Create a new module to serve the UCP profile:

# Create module directories
mkdir -p app/code/Vendor/Ucp/Controller/WellKnown
mkdir -p app/code/Vendor/Ucp/etc

Create app/code/Vendor/Ucp/registration.php:

<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Vendor_Ucp',
    __DIR__
);

Create app/code/Vendor/Ucp/etc/module.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_Ucp" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Store"/>
        </sequence>
    </module>
</config>

Create app/code/Vendor/Ucp/etc/frontend/routes.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="standard">
        <route id="wellknown" frontName=".well-known">
            <module name="Vendor_Ucp"/>
        </route>
    </router>
</config>

Create app/code/Vendor/Ucp/Controller/WellKnown/Ucp.php:

<?php
namespace Vendor\Ucp\Controller\WellKnown;

use Magento\Framework\App\Action\HttpGetActionInterface;
use Magento\Framework\Controller\Result\JsonFactory;
use Magento\Store\Model\StoreManagerInterface;
use Magento\Framework\App\Config\ScopeConfigInterface;

class Ucp implements HttpGetActionInterface
{
    private JsonFactory $jsonFactory;
    private StoreManagerInterface $storeManager;
    private ScopeConfigInterface $scopeConfig;

    public function __construct(
        JsonFactory $jsonFactory,
        StoreManagerInterface $storeManager,
        ScopeConfigInterface $scopeConfig
    ) {
        $this->jsonFactory = $jsonFactory;
        $this->storeManager = $storeManager;
        $this->scopeConfig = $scopeConfig;
    }

    public function execute()
    {
        $store = $this->storeManager->getStore();
        $baseUrl = $store->getBaseUrl();
        
        $profile = [
            'profile_version' => '1.0',
            'merchant' => [
                'name' => $this->scopeConfig->getValue('general/store_information/name'),
                'url' => $baseUrl,
                'contact' => [
                    'email' => $this->scopeConfig->getValue('trans_email/ident_general/email')
                ]
            ],
            'capabilities' => ['browse', 'search'],
            'policies' => [
                'returns_url' => $baseUrl . 'returns',
                'shipping_url' => $baseUrl . 'shipping-policy',
                'privacy_url' => $baseUrl . 'privacy-policy'
            ],
            'service_bindings' => [
                [
                    'type' => 'REST',
                    'base_url' => $baseUrl . 'rest/V1'
                ],
                [
                    'type' => 'GraphQL',
                    'base_url' => $baseUrl . 'graphql'
                ]
            ]
        ];

        $result = $this->jsonFactory->create();
        $result->setHeader('Access-Control-Allow-Origin', '*');
        $result->setData($profile);
        
        return $result;
    }
}

# Enable the module
bin/magento module:enable Vendor_Ucp

# Run setup upgrade
bin/magento setup:upgrade

# Clear cache
bin/magento cache:clean

GraphQL Integration

Magento's GraphQL API is ideal for AI agents. Expose your GraphQL endpoint in the UCP profile for efficient product queries.

Sample GraphQL Query for AI Agents

{
  products(search: "laptop", pageSize: 10) {
    items {
      name
      sku
      price_range {
        minimum_price {
          final_price {
            value
            currency
          }
        }
      }
      image {
        url
      }
      stock_status
    }
  }
}

Multi-Store Configuration

For multi-store setups, each store view can have its own UCP profile. The module automatically uses the current store context.

Validate Your Implementation

Common Issues & Solutions

🤖 Test with AI Agents

Resources

• Official UCP Specification
• Magento GraphQL Developer Guide
• Magento PHP Developer Guide
• UCP Learning Center