Developer guide

UCP for Shopware — Developer Guide

This guide is for plugin authors, app developers, and core contributors

UCP for Shopware — Developer Guide

This guide is for plugin authors, app developers, and core contributors extending Shopware's UCP integration. If you're a shop owner / merchant looking to enable UCP on your store, read the End-User Guide instead.

Table of contents

  1. Architecture overview
  2. Adding a new UCP capability
  3. Integrating a payment plugin with UCP
  4. AP2 mandates plugin integration
  5. Using the UCP Simulator API
  6. Diagrams (architecture + sequences)
  7. Runtime flows
  8. Shopware field mappings

TL;DR — three extension points

Shopware's UCP foundation is a thin orchestration layer over your shop's existing Store-API. As a plugin author you have three stable contracts you can target:

What you want to doWhat you implementWhat you tag with
Add a new capability (root or extension)UcpCapabilityucp.capability
Make an existing payment plugin (Stripe, Mollie, Adyen, …) appear in UCPUcpPaymentHandlerInterfaceucp.payment_handler
Mutate the published profile right before serializationSubscribe to UcpEvents::PROFILE_BUILT(no tag — use Symfony event listener)

Everything else is internal and may change between minor versions while the feature flag UCP_SERVER is still active.

Where to look in the source tree

text
shopware/src/Core/Framework/Ucp/
├── AGENTS.md                   ← internal architecture brief (read first)
├── README.md                   ← user-facing quick start
├── Discovery/                  ← /.well-known/ucp + supported_versions
├── Negotiation/                ← capability intersection algorithm
├── Capability/                 ← one folder per built-in capability
│   ├── Catalog/
│   ├── Cart/
│   ├── Checkout/
│   ├── Order/
│   ├── Discount/
│   ├── Fulfillment/
│   ├── BuyerConsent/
│   ├── Loyalty/
│   └── IdentityLinking/
├── Payment/                    ← payment-handler interface + registry
│   └── UcpPaymentHandlerInterface.php
├── Transport/
│   ├── Rest/                   ← REST envelope, route scope, exception listener
│   ├── Mcp/                    ← MCP JSON-RPC tools
│   ├── A2A/                    ← Agent-to-Agent (Agent Card)
│   ├── Embedded/               ← Embedded Protocol
│   └── Signature/              ← RFC 9421 / RFC 9530
├── Jwt/                        ← ES256 keypair generation + JCS canonicalization
├── Security/                   ← PrivateKeyEncryptor + Monolog key guard
└── DependencyInjection/        ← compiler passes that wire the registries

shopware/src/Administration/Resources/app/administration/src/module/sw-settings-ucp/
└── (Vue + Twig admin UI shown in the screenshots)

simulator/                      ← shop-agnostic UCP simulator + test harness

The simulator API guide includes the REST/MCP matrix used for adapter verification. The current Shopware UCP adapter passes all 34 simulator runs against the local Dockware shop, and the official upstream UCP conformance suite passes with TOTAL=13 FAILURES=0.

The internal architecture brief at shopware/src/Core/Framework/Ucp/AGENTS.md is the canonical source of truth for the core. This developer guide focuses on the extension points and what shapes the right answer for plugin authors.

Three Architecture Decisions Records (ADRs)

The shape of the integration is captured in three ADRs sitting under shopware/adr/:

ADRTopic
2026-05-20-ucp-feature-flag-and-bundle-placement.mdWhere UCP lives in the source tree, the UCP_SERVER feature flag, the three extension contracts
2026-05-20-ucp-jwt-key-storage-and-rotation.mdPer-Sales-Channel ES256 key storage, encryption at rest, rotation lifecycle
2026-05-20-ucp-sales-channel-binding.mdMulti-tenant resolution: how /.well-known/ucp picks the right config per request