How to Add UCP to Shopware (There Is a First-Party Plugin)
Shopware speaks UCP. That one sentence is the whole difference between this guide and the Magento one, where the answer was “there is nothing native, build the bridge yourself.” Shopware maintains a first-party agentic-commerce plugin that publishes the discovery document and serves the shopping capabilities over four transports.
So the job changes shape. You are not implementing a protocol against service contracts — you are installing an extension, deciding which sales channels are exposed, and getting the auth surface right. That last part is where the real work moved, and it is the part a quick-start guide will not tell you about.
What UCP is, in one paragraph
UCP (Universal Commerce Protocol) is an open, Apache-2.0 standard for how AI agents transact with stores — announced by Google and Shopify at NRF in January 2026, backed by Amazon, Walmart, Target, Stripe, Meta and Salesforce. It models a store as a set of capabilities in reverse-DNS namespaces (dev.ucp.shopping.catalog, dev.ucp.shopping.checkout, and so on), each reachable over a transport of your choosing. If you want the protocol itself explained from the spec — the endpoint shapes, the session state machine, the AP2 payment leg — that is all in the Magento guide, and it is platform-independent. This piece is about the Shopware side.
What Shopware actually ships
The plugin covers three separate surfaces, and it is worth keeping them apart in your head because they fail and get configured independently.
| Surface | What it does | Endpoints |
|---|---|---|
| UCP | The transactional protocol: catalog, cart, checkout, order, customer identity, payment | /.well-known/ucp |
| Native discovery | Plain documents that tell a crawler or agent what the store is, without transacting | /agents.md, /llms.txt, /.well-known/ai-catalog.json |
| Product feeds | Catalog ingestion for agents that read feeds rather than call APIs | OpenAI JSONL + Google Shopping XML, via Shopware’s export infrastructure |
It supports 6.5.x, 6.6.x and 6.7+ from one codebase, and it feature-detects at runtime: capabilities and transports your version cannot actually serve are removed from the published profile rather than advertised and then failing. That is the right behaviour and worth knowing, because it means two stores on the same plugin version can legitimately publish different profiles.
Four transports, one of them version-gated
| Transport | Path | Availability |
|---|---|---|
| REST | /ucp/v1 | All supported lanes |
| A2A | /.well-known/agent-card.json + /ucp/a2a | All supported lanes |
| Embedded | /ucp/embedded/* | All supported lanes — but see the origin rules below |
| MCP | /ucp/mcp | 6.7+ only |
Installing and turning it on
The plugin installs through Shopware’s normal extension mechanism and resolves its own Composer dependencies during the plugin lifecycle — it pulls the UCP PHP SDK (ucp-php-sdk/symfony-bundle) as a required runtime dependency. There is no “installed but UCP disabled” mode: without the SDK the plugin does not boot.
Exposure is then per sales channel, set in the Administration under the Agentic Commerce section: activate the channel, set the profile domain, and choose which capabilities and transports to publish. Everything else is CLI:
# which channels are exposed, and how
bin/console ucp:channels
# the resolved config for one channel
bin/console ucp:config:show --sales-channel=StorefrontThe configuration that actually matters
ucp:config:set is where the security posture lives. Omit the options you are not changing — passing none at all is an error rather than a no-op.
| Option | Why you care |
|---|---|
--signature-policy=strict|log|off | The single most important flag. log is for bringing a channel up; production wants strict. |
--idempotency=true|false | Whether a retried agent request can place a second order. Leave it on. |
--agent-allowlist=<host> | Repeatable, bare hosts with no scheme. Which agents may transact at all. |
--remote-profile-allowlist, --platform-allowlist | The other two trust lists — separate knobs, easy to conflate. |
--embedded-allowed-origins, --embedded-frame-ancestors | Repeatable, with scheme. Required for embedded pages — both of them. |
--webhook-url-override=<https-url> | Point shipment events somewhere other than the default. Empty value clears it. |
--continue-url-template=<url> | Where a shopper lands to finish in your storefront. Supports {checkoutId}, {cartId}, {salesChannelId}. |
bin/console ucp:config:set --sales-channel=Storefront \
--embedded-allowed-origins=https://chatgpt.com \
--embedded-frame-ancestors=https://chatgpt.com \
--idempotency=trueOrigin header, or from an origin that is not on the list, gets a controlled 403 UCP response — not a crash, not a blank page. If embedded checkout “does nothing” in an agent, this is the first thing to check, and the 403 body will tell you.Signing keys are per channel, and they rotate
Requests are signed with tenant-scoped keys managed per sales channel. Generate them, publish the public half, and retire rather than delete when rotating, so in-flight verifications do not fail:
bin/console ucp:signing-keys:generate --sales-channel=Storefront
bin/console ucp:signing-keys:list --sales-channel=Storefront
bin/console ucp:signing-keys:show-public --sales-channel=Storefront
bin/console ucp:signing-keys:retire --sales-channel=Storefront
bin/console ucp:signing-keys:delete --sales-channel=StorefrontThere is also SDK-provided storage maintenance you should schedule rather than discover later, particularly the signature-nonce cleanup:
bin/console ucp:storage:cleanup
bin/console ucp:storage:cleanup-signature-nonces --older-than-seconds=86400Shopware vs Magento, side by side
If you run both — plenty of merchants do — this is the honest comparison of what it takes to be agent-reachable on each.
| Shopware | Magento / Adobe Commerce | |
|---|---|---|
| First-party UCP support | Yes — maintained plugin | No |
| Discovery document | Published for you, per sales channel | You build the controller |
| Checkout session mapping | In the plugin, on top of the UCP PHP SDK | You map Quote ↔ session by hand |
| Transports | REST, A2A, embedded, MCP (6.7+) | Whatever you implement |
| Customer identity | Covered as a capability | OAuth 2.0 + PKCE you add yourself (Magento’s integration OAuth is 1.0a) |
| Multi-store scoping | Native — per sales channel | You design it |
| Your main job | Configuration, trust rules, key rotation | Building the module, then all of the above |
The gaps you still own
- Product feeds are public and unsigned. They have to be reachable by feed consumers, and they carry referral and affiliate tracking codes. Treat their contents as published, because they are.
- The plugin is not a chat agent. It deliberately does not do conversational AI, experimentation, or duplicate the Store API. It makes the store transactable by agents; it does not put an assistant on your storefront.
- Pre-6.7 native discovery uses fallback routes, which return
404when UCP is inactive for the channel. A404on/agents.mdis a configuration answer, not a bug report. - Protocol semantics belong to the SDK. The plugin wires Shopware into SDK interfaces. When behaviour surprises you, the SDK — not the plugin — is usually where the answer is.
- The spec is date-versioned and moving. There is no semver. Expect to track releases rather than pin once and forget.
agentic-commerce-lab/SwagUcp is a separate community Shopware plugin covering similar ground — checkout sessions over REST, the discovery endpoint, EC P-256 webhook signing, domain allowlisting. Worth knowing about if the first-party plugin does not fit your lane, though for most merchants the maintained one is the right default.Where WisWes fits
The two things solve different halves of the problem. UCP makes your store transactable by an agent that arrives from outside — from Gemini, Copilot Checkout, or a shopping agent that found you through a feed. WisWes is the assistant on your own storefront, talking to the shopper who is already there: catalog search, comparison, cart, and order questions, reaching Shopware in-process through the Store API. Turning on UCP does not replace that conversation, and running that conversation does not make you discoverable to external agents. If you are deciding where to spend first, the honest answer depends on whether your traffic problem is reach or conversion — and most stores know which one hurts.
FAQ
Does Shopware support UCP out of the box?
Shopware maintains a first-party agentic-commerce plugin — so it is a supported extension rather than something in core you flip on. Install it, activate the sales channels you want exposed, and it publishes /.well-known/ucp for you.
Which Shopware versions can do this?
6.5.x, 6.6.x and 6.7+ are supported from a single codebase. REST, A2A and embedded work across all of them; the MCP transport is 6.7+ only.
Do I have to expose my whole store?
No — exposure is per sales channel, and within a channel you choose which capabilities and transports to publish. A single B2C channel can be agent-reachable while your B2B channel is not.
What is the one setting people get wrong?
Leaving --signature-policy on log after going live. It is the right setting while bringing a channel up and the wrong one to keep. The second is forgetting that embedded needs both --embedded-allowed-origins and --embedded-frame-ancestors.
Is it worth doing now?
The discovery document and feeds are cheap and make you visible to agents that would otherwise skip you. The transactional surface deserves a real look at your signature policy and allowlists before you turn it on in production — which, given the plugin does the building for you, is where your time should go anyway.
Details here reflect the plugin’s documentation as of August 2026. UCP is date-versioned and moving quickly — verify command flags and endpoint paths against the repository before you build on them.
WisWes is an AI sales assistant for Shopware, Magento, and Shopify — the assistant on your storefront, alongside whatever agents arrive from outside.