> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fd.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Supported UCP Versions

> Which UCP versions the Finance District store plugins and Prism serve, how a version is chosen per request, and how to configure it.

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](#shopware) |

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

<Note>
  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"`.
</Note>

## 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:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

<Note>
  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.
</Note>

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.`

<Warning>
  **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.
</Warning>

### 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:

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.