Skip to main content
The /.well-known/ucp manifest is a machine-readable contract between your store and AI agents. It communicates three things: what commerce capabilities you support, where agents should call to use each one, and how those calls should be structured. Think of it as a robots.txt for agentic commerce — a declaration of what’s available and how to interact with it. This page documents every field you can include.

​
Full schema reference

/.well-known/ucp
{
  "version": "1.0",
  "updated_at": "2026-04-10T00:00:00Z",
  "merchant": {
    "name": "Your Store",
    "url": "https://yourstore.com",
    "logo": "https://yourstore.com/logo.png"
  },
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products",
      "format": "json",
      "version": "1.0",
      "supports_search": true,
      "supports_filters": ["category", "price_range", "availability", "brand"],
      "pagination": true
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout",
      "supported_methods": ["POST"],
      "requires_authentication": false,
      "version": "1.0",
      "supported_payment_methods": ["card", "paypal", "upi"]
    },
    "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"]
    }
  }
}

​
Top-level fields

​
version
string
required
The UCP spec version this manifest targets. Currently "1.0". Agents use this to determine which features and schemas to expect.
​
updated_at
string
ISO 8601 timestamp of when the manifest was last modified (e.g. "2026-04-10T00:00:00Z"). Helps agents and caching layers determine freshness.
​
merchant
object
Optional merchant identity block. Provides context for agents and platforms indexing your store.
​
merchant.name
string
Your store’s display name.
​
merchant.url
string
Canonical URL for your store homepage.
Absolute URL to your store logo. Use a square PNG or SVG for best results.
​
capabilities
object
required
Map of capability name to configuration object. Must include at least product_catalog and checkout.

​
product_catalog capability

​
capabilities.product_catalog.endpoint
string
required
Absolute HTTPS URL for your catalog endpoint. Agents send GET requests here to fetch products.
​
capabilities.product_catalog.format
string
default:"json"
Response format. Accepted values: "json", "xml". Defaults to "json" if omitted.
​
capabilities.product_catalog.version
string
default:"1.0"
Capability version. Increment this when you change the request or response shape in a breaking way.
​
capabilities.product_catalog.supports_search
boolean
default:"false"
Set to true if your catalog endpoint accepts a ?q= query parameter for keyword search. If false or omitted, agents will not attempt search queries.
​
capabilities.product_catalog.supports_filters
string[]
default:"[]"
List of filter query parameters your endpoint accepts. Common values: "category", "price_range", "availability", "brand".
​
capabilities.product_catalog.pagination
boolean
default:"false"
Set to true if your catalog endpoint supports page-based or cursor-based pagination via a next URL in the response.

​
checkout capability

​
capabilities.checkout.endpoint
string
required
Absolute HTTPS URL for your checkout endpoint. Agents POST cart and shipping data here.
​
capabilities.checkout.supported_methods
string[]
default:"[\"POST\"]"
HTTP methods your checkout endpoint accepts. Typically ["POST"].
​
capabilities.checkout.requires_authentication
boolean
default:"false"
Set to true if agents must send authentication credentials with checkout requests. Most implementations set this to false and handle authentication via payment tokens.
​
capabilities.checkout.version
string
default:"1.0"
Capability version. Increment this if you change the checkout request or response schema in a breaking way.
​
capabilities.checkout.supported_payment_methods
string[]
Payment method types your checkout endpoint accepts. Common values: "card", "paypal", "upi", "apple_pay", "google_pay".

​
Optional capabilities

​
shipping

Declare a shipping capability if you want agents to request real-time shipping quotes before presenting checkout options to the customer.
​
capabilities.shipping.endpoint
string
Absolute HTTPS URL for your shipping rates endpoint.
​
capabilities.shipping.supported_methods
string[]
HTTP methods accepted. Typically ["POST"].

​
orders

Declare an orders capability to allow agents to look up order status and tracking on the customer’s behalf.
​
capabilities.orders.endpoint
string
Absolute HTTPS URL for your order management endpoint.
​
capabilities.orders.supported_methods
string[]
HTTP methods accepted. Typically ["GET", "POST"].

​
returns

Declare a returns capability to allow agents to initiate return requests without the customer visiting your site.
​
capabilities.returns.endpoint
string
Absolute HTTPS URL for your returns endpoint.
​
capabilities.returns.supported_methods
string[]
HTTP methods accepted. Typically ["POST"].

​
Versioning

Update the updated_at timestamp whenever you modify the manifest. Increment a capability’s version field when the request or response shape for that capability changes in a breaking way. 
// Before adding search support
"product_catalog": {
  "endpoint": "https://yourstore.com/ucp/v1/products",
  "version": "1.0"
}

// After adding search support
"product_catalog": {
  "endpoint": "https://yourstore.com/ucp/v1/products",
  "version": "1.1",
  "supports_search": true
}
Agents may cache your manifest for up to 24 hours. Set Cache-Control: max-age=3600 on the manifest response as a reasonable default — this allows agents to cache for one hour before re-fetching.

​
Configuration examples

​
Minimal — just catalog and checkout

/.well-known/ucp
{
  "version": "1.0",
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products"
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout"
    }
  }
}
/.well-known/ucp
{
  "version": "1.0",
  "updated_at": "2026-04-10T00:00:00Z",
  "merchant": {
    "name": "Your Store",
    "url": "https://yourstore.com",
    "logo": "https://yourstore.com/logo.png"
  },
  "capabilities": {
    "product_catalog": {
      "endpoint": "https://yourstore.com/api/ucp/products",
      "format": "json",
      "version": "1.0",
      "supports_search": true,
      "supports_filters": ["category", "price_range", "availability", "brand"],
      "pagination": true
    },
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout",
      "supported_methods": ["POST"],
      "requires_authentication": false,
      "version": "1.0",
      "supported_payment_methods": ["card", "paypal", "upi"]
    },
    "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"]
    }
  }
}

​
Generate and validate your manifest

Generate a compliant manifest from your endpoint URLs using the API: 
curl -X POST https://asva-ai.com/api/manifest \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourstore.com",
    "catalog_endpoint": "https://yourstore.com/api/ucp/products",
    "checkout_endpoint": "https://yourstore.com/api/ucp/checkout",
    "supports_search": true,
    "shipping_endpoint": "https://yourstore.com/api/ucp/shipping"
  }'
Or use the browser tool: asva-ai.com/tools/manifest Validate an existing hosted manifest: 
curl -X POST https://asva-ai.com/api/manifest/validate \
  -H "Authorization: Bearer $ASVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourstore.com/.well-known/ucp"}'
A valid manifest returns: 
{
  "valid": true,
  "warnings": [
    "supports_search not declared — agents will not attempt catalog search queries"
  ],
  "errors": []
}