/.well-known/ucp: what the check tests and how to fix it

Weight 0.5, ecommerce sites only. Needs a JSON profile with ucp.version (YYYY-MM-DD) and non-empty ucp.services and ucp.payment_handlers.

Agent Protocols · Weight 0.5 in the w2agent Score

How common is it?

11% of 71 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

The audit requests /.well-known/ucp once. The file is accepted only if the answer is a 200 with a JSON content type (application/json or a +json type) whose body is not the same as the body your site returns for a random made-up .well-known path. A catch-all page therefore cannot pass as a profile.

The body must be a JSON object with a top-level ucp object, and that object must have:

  • version: a string in YYYY-MM-DD form. Only the pattern is checked, not whether the date is a real UCP release.
  • services: a non-empty object whose every value is an array.
  • payment_handlers: a non-empty object whose every value is an array.

All three present gives pass, 100. Anything else fails with a message listing the problems, and there is no partial. capabilities, keys and the contents of the arrays are not read.

The check only applies to commerce sites. After the checks run, a result that is not a pass or partial is changed to skip with the message "Not applicable" unless the audit detected the site as ecommerce. Detection looks for signals such as a Shopify, WooCommerce, BigCommerce or Magento marker, Product JSON-LD, og:type of product, cart or checkout paths, price microdata and add-to-cart buttons, and needs a combined confidence of at least 0.5 that also beats any other site type the audit tries, such as local business. A valid profile on a store the detector missed keeps its pass. So a skip means "not detected as a store", not "no profile".

Why it matters to agents

UCP is the Universal Commerce Protocol, published at ucp.dev as an open protocol co-developed by large retailers, platforms and payment companies. It is an industry specification with dated releases, not an IETF or W3C standard. The specification says a business publishes its profile at /.well-known/ucp, that ucp.version, ucp.services and ucp.payment_handlers are required in a profile, and that platforms read it to negotiate capabilities such as catalog, cart and checkout before calling any endpoint.

Google's guide to generative AI search says protocols like UCP are emerging that will allow Search agents to do more. It does not say that publishing a profile changes how your pages are ranked or shown. The payoff is for stores that actually implement the protocol's services.

The audit is stricter than the specification in one place. The specification says the services and payment_handlers registries must be present even when empty, but this check needs both to be non-empty. It is also looser elsewhere: the specification forbids redirects on profile endpoints and requires a Cache-Control header with public and a max-age of at least 60 seconds. The audit tests neither rule.

How to fix it

Only if your store implements UCP services:

  1. Follow the specification's business profile example. An abridged skeleton:
{
  "ucp": {
    "version": "2026-08-25",
    "services": {
      "dev.ucp.shopping": [
        { "version": "2026-08-25", "transport": "rest", "endpoint": "https://example.com/ucp/v1" }
      ]
    },
    "payment_handlers": {
      "com.example.processor": [{ "id": "processor", "version": "2026-08-25" }]
    }
  }
}

The real entries need the spec and schema members the specification lists; take them from its example.

  1. Serve it at https://example.com/.well-known/ucp with Content-Type: application/json, over HTTPS, without a redirect, and with Cache-Control: public, max-age=3600 or similar.
  2. Use a dated release as the version. The specification says a business must not advertise a non-date string such as "draft".
  3. If your commerce platform provides UCP, check its documentation before hand-writing the file.

If you do not run a store, or do not offer UCP, the skip or fail is accurate and needs no action. Related: A2A agent card, since a UCP profile can list an A2A transport, and MCP endpoint, since it can list an MCP transport.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →