Capability negotiation is the mechanism that prevents a UCP participant from assuming unsupported features. A platform advertises its profile. The business resolves that profile, compares versions and computes the intersection between both capability sets. Extensions whose dependencies are absent are then removed.
Key takeaways
- Discovery tells each party what the other claims to support.
- Negotiation keeps only compatible protocol and capability versions.
- Extensions cannot survive without at least one required parent.
- Each response advertises only capabilities relevant to that operation.
What enters the negotiation?
Negotiation starts with two versioned profiles: one for the platform and one for the business. Each profile describes its current protocol version and available services, capabilities and payment handlers. The transport also carries the platform profile location so the business can resolve the caller’s declaration.
The input is not a marketing list. It is a machine-readable contract for the current request. A capability that exists in documentation but is absent from a profile is not active for that participant.
How is the common feature set calculated?
The UCP 2026-04-08 specification defines an intersection process. First, the business determines whether the platform’s protocol version is supported. It then keeps capability versions supported by both profiles. Finally, it prunes extensions that no longer have an eligible parent.
The safe mental model is:
platform capabilities
∩
business capabilities
↓
compatible versions
↓
dependency pruning
↓
active capabilities for this operationThis sequence matters. Pruning extensions before the version intersection can leave a feature attached to a parent that is not actually compatible.
Why can extension pruning repeat?
An extension can depend on another extension, which in turn depends on a root capability. Removing the root can invalidate the first extension and then invalidate the second. The specification therefore requires pruning to continue until no more capabilities are removed.
Test this with a synthetic chain in staging:
- Advertise a checkout root capability.
- Add a fulfillment extension that extends checkout.
- Add a custom extension that depends on fulfillment.
- Remove checkout from the platform profile.
- Verify that both dependent extensions disappear from the result.
This is a useful regression test because a single-pass filter can leave an invalid transitive dependency behind.
What belongs in each response?
The response should not echo every negotiated capability. It includes only capabilities relevant to the operation being returned. The current UCP overview associates checkout operations with the checkout root, cart operations with the cart root, and order events with the order root. Relevant extensions can accompany those roots.
This keeps a response precise. A cart response should not claim that order or checkout behavior was active simply because both parties support those features elsewhere.
How should failures be classified?
Discovery and negotiation failures are different operational events:
- A discovery failure means a required profile could not be fetched or parsed.
- A version failure means the advertised protocol version is not supported.
- A capability failure means profiles are valid, but the required common feature set is empty or incompatible.
Do not collapse these into a generic server error. The caller needs to know whether to retry a fetch, switch version, remove an optional feature or continue through a human-facing URL.
A deterministic test matrix
Build tests from controlled profile pairs:
| Scenario | Expected result |
|---|---|
| Same protocol and capability versions | Capability remains active |
| Supported older protocol version | Version-specific profile is used |
| Unsupported protocol version | version_unsupported outcome |
| Shared root, unsupported extension | Root remains, extension is removed |
| Extension without parent | Extension is removed |
| No compatible required capability | Capability negotiation fails |
Save both input profiles and the computed result. That evidence makes a failure reproducible without access to production logs.
Implementation rule
Keep negotiation in deterministic application code. A language model can help explain an error, but it should not decide whether two signed, versioned capability declarations are compatible. Protocol compatibility must produce the same result for the same inputs every time.
Primary sources and review date
- UCP specification overview, negotiation protocol, reviewed 2026-08-12.
- Shopify agent profiles and UCP negotiation, reviewed 2026-08-12.