> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asva-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP Manifest Schema: Complete Field-by-Field Reference

> Complete field-by-field reference for the /.well-known/ucp manifest — every capability, required vs. optional fields, versioning, and configuration examples.

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

```json /.well-known/ucp theme={null}
{
  "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

<ParamField path="version" type="string" required>
  The UCP spec version this manifest targets. Currently `"1.0"`. Agents use this to determine which features and schemas to expect.
</ParamField>

<ParamField path="updated_at" type="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.
</ParamField>

<ParamField path="merchant" type="object">
  Optional merchant identity block. Provides context for agents and platforms indexing your store.
</ParamField>

<ParamField path="merchant.name" type="string">
  Your store's display name.
</ParamField>

<ParamField path="merchant.url" type="string">
  Canonical URL for your store homepage.
</ParamField>

<ParamField path="merchant.logo" type="string">
  Absolute URL to your store logo. Use a square PNG or SVG for best results.
</ParamField>

<ParamField path="capabilities" type="object" required>
  Map of capability name to configuration object. Must include at least `product_catalog` and `checkout`.
</ParamField>

## `product_catalog` capability

<ParamField path="capabilities.product_catalog.endpoint" type="string" required>
  Absolute HTTPS URL for your catalog endpoint. Agents send `GET` requests here to fetch products.
</ParamField>

<ParamField path="capabilities.product_catalog.format" type="string" default="json">
  Response format. Accepted values: `"json"`, `"xml"`. Defaults to `"json"` if omitted.
</ParamField>

<ParamField path="capabilities.product_catalog.version" type="string" default="1.0">
  Capability version. Increment this when you change the request or response shape in a breaking way.
</ParamField>

<ParamField path="capabilities.product_catalog.supports_search" type="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.
</ParamField>

<ParamField path="capabilities.product_catalog.supports_filters" type="string[]" default="[]">
  List of filter query parameters your endpoint accepts. Common values: `"category"`, `"price_range"`, `"availability"`, `"brand"`.
</ParamField>

<ParamField path="capabilities.product_catalog.pagination" type="boolean" default="false">
  Set to `true` if your catalog endpoint supports page-based or cursor-based pagination via a `next` URL in the response.
</ParamField>

## `checkout` capability

<ParamField path="capabilities.checkout.endpoint" type="string" required>
  Absolute HTTPS URL for your checkout endpoint. Agents `POST` cart and shipping data here.
</ParamField>

<ParamField path="capabilities.checkout.supported_methods" type="string[]" default="[&#x22;POST&#x22;]">
  HTTP methods your checkout endpoint accepts. Typically `["POST"]`.
</ParamField>

<ParamField path="capabilities.checkout.requires_authentication" type="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.
</ParamField>

<ParamField path="capabilities.checkout.version" type="string" default="1.0">
  Capability version. Increment this if you change the checkout request or response schema in a breaking way.
</ParamField>

<ParamField path="capabilities.checkout.supported_payment_methods" type="string[]">
  Payment method types your checkout endpoint accepts. Common values: `"card"`, `"paypal"`, `"upi"`, `"apple_pay"`, `"google_pay"`.
</ParamField>

## Optional capabilities

### `shipping`

Declare a shipping capability if you want agents to request real-time shipping quotes before presenting checkout options to the customer.

<ParamField path="capabilities.shipping.endpoint" type="string">
  Absolute HTTPS URL for your shipping rates endpoint.
</ParamField>

<ParamField path="capabilities.shipping.supported_methods" type="string[]">
  HTTP methods accepted. Typically `["POST"]`.
</ParamField>

### `orders`

Declare an orders capability to allow agents to look up order status and tracking on the customer's behalf.

<ParamField path="capabilities.orders.endpoint" type="string">
  Absolute HTTPS URL for your order management endpoint.
</ParamField>

<ParamField path="capabilities.orders.supported_methods" type="string[]">
  HTTP methods accepted. Typically `["GET", "POST"]`.
</ParamField>

### `returns`

Declare a returns capability to allow agents to initiate return requests without the customer visiting your site.

<ParamField path="capabilities.returns.endpoint" type="string">
  Absolute HTTPS URL for your returns endpoint.
</ParamField>

<ParamField path="capabilities.returns.supported_methods" type="string[]">
  HTTP methods accepted. Typically `["POST"]`.
</ParamField>

## 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.

```json theme={null}
// 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
}
```

<Note>
  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.
</Note>

## Configuration examples

### Minimal — just catalog and checkout

```json /.well-known/ucp theme={null}
{
  "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

```json /.well-known/ucp theme={null}
{
  "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:

```bash theme={null}
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](https://asva-ai.com/tools/manifest)

Validate an existing hosted manifest:

```bash theme={null}
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:

```json theme={null}
{
  "valid": true,
  "warnings": [
    "supports_search not declared — agents will not attempt catalog search queries"
  ],
  "errors": []
}
```