UCP Manifest Schema: Complete Field-by-Field Reference

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

string

required

The UCP spec version this manifest targets. Currently "1.0". Agents use this to determine which features and schemas to expect.

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.

object

Optional merchant identity block. Provides context for agents and platforms indexing your store.

string

Your store’s display name.

string

Canonical URL for your store homepage.

string

Absolute URL to your store logo. Use a square PNG or SVG for best results.

object

required

Map of capability name to configuration object. Must include at least product_catalog and checkout.

`product_catalog` capability

string

required

Absolute HTTPS URL for your catalog endpoint. Agents send GET requests here to fetch products.

string

default:"json"

Response format. Accepted values: "json", "xml". Defaults to "json" if omitted.

string

default:"1.0"

Capability version. Increment this when you change the request or response shape in a breaking way.

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.

string[]

default:"[]"

List of filter query parameters your endpoint accepts. Common values: "category", "price_range", "availability", "brand".

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

string

required

Absolute HTTPS URL for your checkout endpoint. Agents POST cart and shipping data here.

string[]

default:"[\"POST\"]"

HTTP methods your checkout endpoint accepts. Typically ["POST"].

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.

string

default:"1.0"

Capability version. Increment this if you change the checkout request or response schema in a breaking way.

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.

string

Absolute HTTPS URL for your shipping rates endpoint.

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.

string

Absolute HTTPS URL for your order management endpoint.

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.

string

Absolute HTTPS URL for your returns endpoint.

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"
    }
  }
}

Full-featured store with all optional capabilities

/.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": []
}

Get Started

UCP

ACP

Attribution

Guides

UCP Manifest Schema: Complete Field-by-Field Reference

Full schema reference

Top-level fields

`product_catalog` capability

`checkout` capability

Optional capabilities

`shipping`

`orders`

`returns`

Versioning

Configuration examples

Minimal — just catalog and checkout

Full-featured store with all optional capabilities

Generate and validate your manifest

​Full schema reference

​Top-level fields

​product_catalog capability

​checkout capability

​Optional capabilities

​shipping

​orders

​returns

​Versioning

​Configuration examples

​Minimal — just catalog and checkout

​Full-featured store with all optional capabilities

​Generate and validate your manifest

Full schema reference

Top-level fields

`product_catalog` capability

`checkout` capability

Optional capabilities

`shipping`

`orders`

`returns`

Versioning

Configuration examples

Minimal — just catalog and checkout

Full-featured store with all optional capabilities

Generate and validate your manifest