Supported UCP Versions

The Finance District store plugins serve three UCP versions side by side: 2026-08-25 (default), 2026-04-08 and 2026-01-23. Each request is answered in the version the agent declares. Existing plugin releases keep working against Prism without any change.

Two separate versions

Two version numbers appear in a UCP integration with Prism. They change independently.

Version	Example	Where it appears	Who sets it
UCP protocol version	`2026-08-25`	`ucp.version` in the store profile and in every UCP response	The store, per request
Prism handler contract	`2026-10-07`	`version` inside the `xyz.fd.prism_payment` handler entry	Prism

A store on UCP 2026-01-23 and a store on UCP 2026-08-25 both advertise the same Prism handler contract 2026-10-07.

Plugin releases

Plugin	Release	Default UCP version	Also available
WooCommerce (core 0.3.1, Prism payment 0.3.0)	0.3.1	2026-08-25	2026-04-08, 2026-01-23
PrestaShop (`fdpsucp` 0.7.1, `fdpsprism` 0.7.0)	0.7.1	2026-08-25	2026-04-08, 2026-01-23
Medusa (`medusa-plugin-agentic-commerce` + `medusa-plugin-prism-payment`)	1.1.0	2026-08-25	2026-04-08, 2026-01-23
Saleor core	1.1.0	2026-08-25	2026-04-08, 2026-01-23
Saleor Next.js, Prism payment, dummy payment	2.1.0	2026-08-25	2026-04-08, 2026-01-23
Shopware Prism handler	0.7.0	Follows SwagAgenticCommerce	See Shopware

All plugin updates are minor releases. No config key, route, export or response field was removed or renamed.

The default is the latest UCP version, currently 2026-08-25. Fresh installs and upgrades start there. Agents that declare a version in their profile are served that version regardless of the default. Stores that never update the plugin are unaffected.

WooCommerce, PrestaShop: to stay on an older version, set it under UCP versions in the plugin settings. A version already saved there is kept on update.
Medusa, Saleor: an omitted version option means the latest version. To pin, set ucp_version (Medusa) or ucpVersion (Saleor) to "2026-04-08".

Discovery

GET /.well-known/ucp returns the profile in the store’s current version. It lists every other enabled version under ucp.supported_versions, each pointing to a leaf profile:

{
  "ucp": {
    "version": "2026-08-25",
    "supported_versions": {
      "2026-04-08": "https://shop.example/.well-known/ucp/2026-04-08",
      "2026-01-23": "https://shop.example/.well-known/ucp/2026-01-23"
    }
  }
}

GET /.well-known/ucp/{version} returns the profile for one enabled version. A version that is not enabled returns 404 version_unsupported. Leaf profiles never contain supported_versions. UCP 2026-01-23 has no cart or catalog capability. In that version, cart and catalog routes return 404.

Configuration

Every plugin has the same three settings. On Medusa and Saleor the current-version setting already existed and keeps its name. On WooCommerce and PrestaShop all three settings are new in 0.3.0 and 0.7.0.

Setting	WooCommerce option	PrestaShop key	Medusa option	Saleor option
Current version	`fd_ucp_version`	`FDPSUCP_UCP_VERSION`	`ucp_version`	`ucpVersion`
Also supported versions	`fd_ucp_supported_versions`	`FDPSUCP_UCP_SUPPORTED_VERSIONS`	`ucp_supported_versions`	`ucpSupportedVersions`
Version negotiation	`fd_ucp_version_negotiation`	`FDPSUCP_UCP_NEGOTIATION`	`ucp_version_negotiation`	`ucpVersionNegotiation`

Setting	Default	Meaning
Current version	Latest (`2026-08-25`)	Served at `/.well-known/ucp` and to agents that do not declare a version
Also supported versions	Every other known version (`2026-04-08`, `2026-01-23`)	Extra versions an agent may pick. The current version is removed from this list.
Version negotiation	`lenient`	`lenient` or `strict`. Decides what happens when the agent profile cannot be used.

Where to set them:

WooCommerce: WooCommerce > Settings > Advanced > UCP versions.
PrestaShop: Modules > Finance District UCP > Configure > UCP versions.
Medusa: options of the agenticCommerce module in medusa-config.ts.
Saleor: createAgenticCommerce({ ucpVersion, ucpSupportedVersions, ucpVersionNegotiation }). Wire the discoveryVersion route at src/app/.well-known/ucp/[version]/route.ts. The Next.js integration needs the Node.js runtime.

On Medusa and Saleor, leaving the supported list unset enables every known version other than the current one, so ucpVersion: "2026-04-08" alone keeps 2026-08-25 and 2026-01-23 available. On WooCommerce and PrestaShop, the settings page saves both values together.

An unknown version or negotiation value is rejected:

Medusa, Saleor: the store fails at boot.
WooCommerce, PrestaShop: saving the setting fails. If an unknown value is stored anyway, every UCP route answers 500 configuration_invalid and the admin shows a notice. The rest of the shop keeps running.

How a request gets its version

The agent names its profile in the UCP-Agent header (profile="https://..."). The store fetches that profile and reads ucp.version. The profile fetch is restricted: HTTPS only, public addresses only, no redirects, 3 second timeout, 64 KiB limit. Results, including failures, are cached for 10 minutes.

Agent profile	`lenient` (default)	`strict`
No `profile` in `UCP-Agent`	Current version, as in earlier releases	Same
Unreachable, not HTTPS, private host, too large, timeout	Current version + warning	`424 agent_profile_unavailable`
No or malformed `ucp.version`	Current version + warning	`422 version_unsupported`
Unknown version date	Current version + warning	`422 version_unsupported`
Known version, disabled by the store	`422 version_unsupported`	`422 version_unsupported`
Enabled version	That version	That version

The warning is one structured log line with the key ucp_profile_resolution and the outcome (unreachable, undeclared or unknown). The 422 version_unsupported message lists what the store serves, for example: Version 2026-07-01 is not supported. This business implements versions 2026-08-25, 2026-04-08, 2026-01-23.

Lenient mode deviates from the UCP spec on purpose. The spec says a business must reject an agent whose profile it cannot read or whose version it does not know. Lenient mode serves the current version instead, so agents built before version negotiation keep working. A version the store disabled is always rejected. Choose strict to follow the spec exactly.

Session pinning

A checkout session (and a cart, where the plugin has one) keeps the version its agent declared when it was created.

Later request on the same session	Result
Agent declares the same version	Served in that version
Agent declares a different enabled version	`422 version_unsupported`
Agent profile cannot be read, has no version, or names an unknown version (lenient)	Served in the session’s version + warning

A session is pinned only when the agent profile declared a version the store serves. Sessions created on a fallback, and sessions created by an earlier release, are not pinned.

Payment instruments and the Prism handler entry

Upgraded plugins accept both Prism handler entry shapes:

the current entry: id xyz.fd.prism_payment, version 2026-10-07, spec, schema, config, config_schema, instrument_schemas and, except for 2026-01-23, available_instruments;
the original entry: id x402 (or xyz.fd.prism_payment), config_schema, instrument_schemas, config.

Either way, the store advertises the current entry with id xyz.fd.prism_payment. Instruments sent by agents written for earlier releases still complete:

handler_id: xyz.fd.prism_payment, x402 or missing
type: x402, tokenized, default or missing
credential.type: x402 or missing

The Prism quote binding and Prism settlement still apply: the signed amount must match the checkout’s Prism quote.

Prism contract selection

The UCP version is part of the path. Prism picks the handler contract from the route, not from the caller.

Route	Handler contract
`GET /ucp/{ucpVersion}/handlers`	`2026-10-07` for UCP `2026-01-23`, `2026-04-08`, `2026-08-25`. Other values return `422 version_unsupported`.

The versioned handlers route is public and needs no API key. Payment requirements do not depend on the UCP version. POST /api/v2/merchant/payment-requirements needs the API key and returns the raw x402 PaymentRequired object. The merchant builds the UCP checkout entry {id, version, config}: id and version come from the handlers declaration for its UCP version, config is that object. Prism sends the handlers response with:

Cache-Control: private, max-age=3600

Handler documents

URL	Content
`https://prism-gw.fd.xyz/ucp/{version}/schema.json`	Handler config schema for UCP `{version}`
`https://prism-gw.fd.xyz/ucp/{version}/instrument_schema.json`	Instrument and credential schema for UCP `{version}`
`https://prism-gw.fd.xyz/ucp/{version}/prism.md`	Handler spec for UCP `{version}`
`https://prism-gw.fd.xyz/ucp/schema.json`, `/ucp/instrument_schema.json`, `/ucp/prism.md`	Unchanged. Still served for the original contract.

A versioned URL for a version Prism does not serve returns 404.

Shopware

On Shopware, SwagAgenticCommerce (SAG) serves UCP, and the Prism handler follows the version SAG serves.

SwagAgenticCommerce	UCP served	Plugins
1.2.x	2026-04-08	Prism handler 0.7.0
1.3.x	2026-08-25	Prism handler 0.7.0

Prism handler 0.7.0 requires shopware/agentic-commerce >=1.0.0 <2.0.0. Shopware serves one UCP version per SAG release. A store that upgrades SAG from 1.2 to 1.3 moves from 2026-04-08 to 2026-08-25, and agents that only speak 2026-04-08 get 422 version_unsupported from SAG. Stores that stay on SAG 1.2 keep 2026-04-08.

Getting Started

Concepts

Architecture

Integrations

API Reference

Going to Production

AI Tooling

Resources

Two separate versions

Plugin releases

Discovery

Configuration

How a request gets its version

Session pinning

Payment instruments and the Prism handler entry

Prism contract selection

Handler documents

Shopware

​Two separate versions

​Plugin releases

​Discovery

​Configuration

​How a request gets its version

​Session pinning

​Payment instruments and the Prism handler entry

​Prism contract selection

​Handler documents

​Shopware

Two separate versions

Plugin releases

Discovery

Configuration

How a request gets its version

Session pinning

Payment instruments and the Prism handler entry

Prism contract selection

Handler documents

Shopware