Skip to main content
Before an AI agent can browse your catalog or place an order, it needs to know what your store supports and where to call it. The /.well-known/ucp file is that declaration. When a UCP-compatible platform — Google AI Mode, Gemini, or any other agent — encounters your domain, it fetches this file first. Without it, agents cannot discover or transact with you at all.
The manifest must be served at https://yourdomain.com/.well-known/ucp (or /.well-known/ucp.json) with Content-Type: application/json and no authentication required. Agents will not send credentials to fetch capability discovery files.

​
Minimal manifest

The minimum valid manifest requires a product_catalog capability and a checkout capability. Both must include an endpoint URL.
/.well-known/ucp
{
  "version": "1.0",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products"
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout"
    }
  }
}

​
Full manifest with all capabilities

Declare optional capabilities to unlock additional agent behaviors — shipping cost calculation, order tracking, and return initiation.
/.well-known/ucp
{
  "version": "1.0",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products",
      "format": "json",
      "version": "1.0",
      "supports_search": true,
      "supports_filters": ["category", "price", "availability"]
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout",
      "supported_methods": ["POST"],
      "requires_authentication": false,
      "version": "1.0"
    },
    "shipping": {
      "endpoint": "https://yourstore.com/api/ucp/shipping",
      "supported_methods": ["POST"]
    },
    "orders": {
      "endpoint": "https://yourstore.com/api/ucp/orders",
      "supported_methods": ["GET", "POST"]
    },
    "returns": {
      "endpoint": "https://yourstore.com/api/ucp/returns",
      "supported_methods": ["POST"]
    }
  }
}

​
Required capabilities

CapabilityRequiredDescription
product_catalogYesEndpoint agents call to fetch your products
checkoutYesEndpoint agents call to create and confirm orders

​
Optional capabilities

CapabilityDescription
shippingShipping options and real-time cost calculation
ordersOrder history lookup and tracking status
returnsInitiating returns from inside the agent experience
reviewsProduct reviews and ratings for agent context

​
Hosting the manifest

Place the file at public/.well-known/ucp. Next.js serves everything in public/ as static files automatically.
mkdir -p public/.well-known
Then create public/.well-known/ucp with your manifest JSON. No additional configuration required — Vercel will serve it at /.well-known/ucp.
Vercel sets Content-Type based on file extension. Since ucp has no extension, verify the response header is application/json. You may need a vercel.json rewrite rule or a Route Handler to set the header explicitly.

​
Common mistakes

The manifest must be at https://yourdomain.com/.well-known/ucp, not on a subdomain like shop.yourdomain.com/.well-known/ucp. Check that your web server routes the root domain correctly, and that .well-known directories aren’t blocked by a .htaccess or server config.
Validate your JSON before deploying. Common causes: trailing commas, unescaped quotation marks inside strings, or missing closing brackets.
cat .well-known/ucp | python3 -m json.tool
If the command exits without output, your JSON is valid.
The response must include Content-Type: application/json. Some static hosts serve unknown file extensions as text/plain. Override this in your hosting configuration — see the Nginx and Express examples above.
The /.well-known/ucp file must be publicly accessible with no API key, cookie, or auth header required. AI agents follow the .well-known convention and will not authenticate to fetch this file.

​
Validate with Asva

Use the Manifest Generator and Validator to generate a compliant manifest from your endpoint URLs, validate the JSON of an existing file, and confirm your hosted manifest is publicly reachable. To validate via the API: 
curl -X POST https://asva-ai.com/api/audit \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourstore.com", "checks": ["well_known"]}'

​
Next steps

Product catalog endpoint

Structure your catalog endpoint so agents can find the right product and variant.

Checkout and payments

Implement cart creation and order confirmation.