Skip to content
UCP / commerce infrastructure for agents
Menu

/ commerce infrastructure for agents

Specification lab · Versioning

Migrating UCP from 2026-01-11 to 2026-04-08

UCP uses date-based versions. A safe migration treats each dated profile as a complete contract rather than changing fields in place.

Editorial team · Updated : 2026-08-12 · Primary query : UCP 2026-04-08 migration

UCP versions are dates in YYYY-MM-DD format. Moving from 2026-01-11 to 2026-04-08 should therefore be handled as a contract migration. The current profile changes only after the new schemas, services and capabilities have been tested together.

Key takeaways

  • Diff the official dated specifications and schemas, not copied examples.
  • Publish a complete profile for every version you continue to support.
  • Test request-time version validation before switching the current profile.
  • Keep a rollback profile and deployment artefact until old traffic disappears.

What should be compared first?

Start with machine-readable resources referenced by both dated specifications. Compare the profile schema, each capability schema, service transport definitions and error models. A prose changelog is useful context, but an implementation must react to the actual contracts it validates and emits.

Create a migration inventory with these columns:

Component Old reference New reference Change type Code owner Test status
Profile Dated profile schema Dated profile schema Add, remove or change Identity Pending
Checkout Dated checkout schema Dated checkout schema Field or behavior Commerce Pending
Cart Dated cart schema Dated cart schema Field or behavior Commerce Pending
Order Dated order schema Dated order schema Field or behavior Post-purchase Pending
Signatures Dated signature rules Dated signature rules Verification Security Pending

Do not mark “no change” from memory. Record the compared source URLs and file hashes.

How does dual-version support work?

The current UCP overview allows a business to advertise its current version and map older supported dates to separate profiles through supported_versions. Each mapped document is complete and self-contained for that version. A version-specific profile should not contain another supported_versions map.

This design prevents a mixed contract. A request using the old protocol receives the old set of services, capabilities, handlers and keys. A current request receives the current set.

What should request validation do?

The business validates the platform’s protocol version on every request. A request can proceed when the platform version matches the business’s current version or appears in the supported-version map. Otherwise, the specification defines a version_unsupported outcome.

Test at least these paths:

  1. Current platform version against current business profile.
  2. Old platform version against the mapped old profile.
  3. Unknown version against the current endpoint.
  4. Supported protocol version with an incompatible required capability.
  5. Current version with an extension whose parent is absent.

Version acceptance does not guarantee capability compatibility. Keep those assertions separate.

A safe cutover sequence

Use the following order in staging and production:

  1. Freeze the reviewed old profile and schemas.
  2. Implement new schemas behind an explicit version boundary.
  3. Add contract tests for old and new requests.
  4. Publish the version-specific old profile at its stable URI.
  5. Publish the new current profile with the old version mapping.
  6. Send controlled old and new requests from outside the network.
  7. Monitor version outcomes and signature failures.
  8. Remove old support only after a documented deprecation decision.

Avoid changing a single mutable profile while leaving handlers on old schemas. That creates a declaration the runtime cannot honor.

Rollback evidence

Keep the previous profile response, previous static artefact, schema hashes and request fixtures. If the new profile causes discovery, signature or compatibility failures, restore the old deployment and current-version declaration together. Rolling back only the JSON profile can be unsafe when the running handlers already expect the newer contract.

What this guide does not claim

This note does not claim that every implementation must support both dates, nor that the two versions differ in a particular field without a recorded schema diff. It provides a migration method derived from UCP’s documented version-discovery rules. The exact code change depends on the implementation being audited.

Primary sources and review date

Related implementation guides