The current UCP specification uses a profile as the starting point for discovery, capability negotiation and identity verification. Businesses publish their current profile at /.well-known/ucp. Platforms can fetch it before a request, while a platform identifies its own profile on requests through the transport-specific mechanism.
Key takeaways
- Serve the current business profile over HTTPS without a redirect.
- Make version, services and capabilities internally consistent.
- Validate every referenced specification and schema URL.
- Test the profile as an external agent would see it, not from inside the network.
What does a valid discovery response require?
A production profile should pass four transport checks before its JSON structure is reviewed. The UCP 2026-04-08 specification requires HTTPS, rejects redirects for profile endpoints, and requires public caching with a max-age of at least 60 seconds. A valid JSON body served through the wrong HTTP behavior is still a failed discovery surface.
Run this release checklist from outside the merchant network:
| Check | Pass condition | Why it matters |
|---|---|---|
| URL | https://merchant.example/.well-known/ucp |
Discovery starts from a predictable location |
| Status | Direct 200 response | Profile fetchers must not follow a redirect chain |
| Content | Valid JSON | Negotiation cannot begin with malformed data |
| Cache | Public max-age of at least 60 seconds |
Profiles are stable identity documents |
| Availability | Reachable from an external network | Internal success does not prove public discovery |
Use curl -i or an equivalent HTTP client to preserve headers. A browser view alone hides redirect and cache details.
Which profile fields need cross-checking?
The profile declares a protocol version plus the services, capabilities and payment handlers available at that version. Do not validate those sections as independent lists. Every capability should point to the intended versioned specification and schema, and every service should declare a transport the implementation actually serves.
A reviewer should answer these questions:
- Does
ucp.versionuse the date format defined by the specification? - Is every advertised service reachable through its declared transport?
- Does every capability reference the matching versioned specification?
- Are extension dependencies present with their parent capabilities?
- Are payment handlers limited to instruments the business can actually process?
- Are verification keys published in the structure required by the current profile schema?
The last check must use the current schema rather than a copied blog example. Profile structures can change between dated protocol versions.
How should referenced URLs be tested?
A profile is a graph of declarations. Fetch every spec, schema, service endpoint and supported-version profile. Record the final status, content type and response time, but do not invent a universal performance threshold when the specification does not define one.
The validation result should distinguish three states:
- Pass: the resource exists and matches the declared purpose.
- Fail: the resource is missing, malformed or contradicts the profile.
- Not verified: access or authentication prevented a conclusive test.
This distinction keeps an audit reproducible. “Looks correct” is not a result a second reviewer can repeat.
How do you test version support safely?
UCP uses date-based versions. The current profile describes the current version. If a business supports an older version, the specification allows supported_versions to map that date to a complete, version-specific profile. Those older profiles are leaf documents and should not repeat the supported-version map.
Test three requests in staging:
- A platform profile using the business’s current version.
- A platform profile using one explicitly supported older version.
- A platform profile using an unsupported version.
The first two should continue to capability negotiation. The third should produce the documented version_unsupported outcome without creating a commerce resource.
A release-ready evidence bundle
Store the following evidence with the deployment commit:
- Raw profile response and response headers.
- Hash of the reviewed JSON document.
- Results for every referenced URL.
- Current and supported version test results.
- Capability-intersection test results.
- Date and environment of the external check.
This is an independent validation checklist derived from the cited specifications. It is not an official UCP certification and should never be presented as one.
Final launch decision
A profile can launch when transport behavior, JSON schema, referenced resources, version handling and capability negotiation all pass. If one check is inconclusive, label it and keep the profile in staging. The safest UCP profile is not the longest one. It is the smallest accurate declaration of what the business can support today.
Primary sources and review date
- UCP specification overview, version 2026-04-08, reviewed 2026-08-12.
- Shopify agent profiles and UCP negotiation, reviewed 2026-08-12.