Overview & Agentic Commerce Architecture #
UCP Discovery Endpoint #
GET
/.well-known/ucp
Headers
| Header | Value |
|---|---|
| Accept | application/json |
Request Example
Response
200 OK
{
"ucp": {
"version": "2026-10-08",
"supported_versions": {
"2026-10-08": "https://store.example.com/.well-known/ucp/2026-10-08",
"2026-08-25": "https://store.example.com/.well-known/ucp/2026-08-25",
"2026-04-08": "https://store.example.com/.well-known/ucp/2026-04-08",
"2026-01-23": "https://store.example.com/.well-known/ucp/2026-01-23"
},
"services": {
"dev.ucp.shopping": [
{
"version": "2026-10-08",
"spec": "https://ucp.dev/2026-10-08/specification/overview/",
"transport": "mcp",
"endpoint": "https://store.example.com/api/ucp/mcp",
"schema": "https://ucp.dev/2026-10-08/services/shopping/mcp.openrpc.json"
}
]
},
"capabilities": {
"dev.joonweb.catalog": [
{
"version": "2026-10-08",
"spec": "https://joonweb.dev/agents/catalog/store-catalog",
"schema": "https://joonweb.dev/ucp/schemas/2026-10-08/joonweb_catalog.json",
"extends": [
"dev.ucp.shopping.catalog.search",
"dev.ucp.shopping.catalog.lookup"
],
"documentation_url": "https://joonweb.dev/agents/catalog/store-catalog"
}
]
},
"payment_handlers": {
"dev.joonweb.razorpay": [
{
"id": "razorpay",
"version": "2026-10-08",
"spec": "https://razorpay.com/docs/payments/payment-gateway/",
"schema": "https://joonweb.dev/ucp/schemas/2026-10-08/razorpay.json",
"config": {
"enabled_payment_methods": [
"upi",
"card",
"netbanking",
"wallet"
]
}
}
],
"dev.joonweb.cod": [
{
"id": "cod",
"version": "2026-10-08",
"spec": "https://joonweb.dev/agents/catalog/store-catalog#active-payment-methods-api",
"schema": "https://joonweb.dev/ucp/schemas/2026-10-08/cod.json",
"config": {
"type": "cash_on_delivery"
}
}
]
}
}
}Storefront Products Feed #
GET
/products.json
Parameters
| Field | Type | Description |
|---|---|---|
| page | integer | [Optional] Page number to fetch (default: 1) |
| limit | integer | [Optional] Number of products to return (default: 30, max: 250) |
| collection | string | [Optional] Filter by collection slug or ID |
| category | integer | [Optional] Filter by category ID (ccid) |
| q | string | [Optional] Search keyword matching title or tags |
Headers
| Header | Value |
|---|---|
| Accept | application/json |
Request Example
Response
200 OK
{
"products": [
{
"id": 104593,
"title": "Pure Kashmiri Mogra Saffron (Grade A1)",
"handle": "pure-kashmiri-saffron",
"body_html": "<p>Artisanal organic Grade A1 Kashmiri Saffron harvested from organic farms.</p>",
"vendor": "Kasturika",
"product_type": "Ayurveda & Wellness",
"tags": [
"saffron",
"organic",
"kesar",
"wellness",
"pure"
],
"inventory_quantity": 45,
"variants": [
{
"id": 593821,
"variant_id": 4920,
"title": "1g / Premium Glass Jar",
"price": 999,
"compare_at_price": 1299,
"sale_price": 999,
"sku": "KAS-KESAR-1G",
"available": true,
"inventory_quantity": 45
}
],
"images": [
{
"id": 1029,
"src": "https://static.joonsite.com/storage/104/media/saffron-1.jpg",
"alt": "Pure Kashmiri Mogra Saffron Jar"
}
]
}
],
"pagination": {
"total": 128,
"limit": 30,
"page": 1,
"has_next": true
}
}Active Payment Methods Discovery #
GET
/api/ucp/mcp?tool=get_payment_methods
Parameters
| Field | Type | Description |
|---|---|---|
| postal_pin | string | [Optional] Buyer PIN code to evaluate Cash on Delivery serviceability |
| cart_total | number | [Optional] Total order amount to evaluate COD limits and partial payment advance rules |
Headers
| Header | Value |
|---|---|
| Accept | application/json |
Request Example
Response
200 OK
{
"site_id": 104,
"store": "Kasturika",
"currency": "INR",
"has_online": true,
"has_cod": true,
"has_upi": true,
"total_methods": 2,
"methods": [
{
"code": "razorpay",
"name": "Razorpay Secure Gateway",
"type": "automatic",
"is_online": true,
"description": "UPI (Google Pay, PhonePe, Paytm), Cards & NetBanking",
"supported_channels": [
"upi",
"card",
"netbanking",
"wallet"
],
"available": true
},
{
"code": "cod",
"name": "Cash on Delivery",
"type": "manual",
"is_online": false,
"description": "Pay cash upon delivery at your doorstep",
"supported_channels": [
"cash"
],
"available": true,
"cod_rate": 0
}
]
}Model Context Protocol (MCP) Tools Reference #
MCP Client Configuration (Claude Desktop / Cursor) #
json
{
"mcpServers": {
"joonweb-store": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-fetch",
"https://store.example.com/api/ucp/mcp"
]
}
}
}ChatGPT Custom GPT Action OpenAPI 3.1 Specification #
json
{
"openapi": "3.1.0",
"info": {
"title": "JoonWeb Storefront Autonomous Commerce API",
"version": "2026-10-08",
"description": "Enables ChatGPT to search products, inspect inventory, verify active payment gateways, and generate instant checkout permalinks."
},
"servers": [
{
"url": "https://store.example.com"
}
],
"paths": {
"/products.json": {
"get": {
"operationId": "searchProducts",
"summary": "Search products in the catalog",
"parameters": [
{ "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search keyword" },
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
{ "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }
],
"responses": {
"200": { "description": "Product catalog feed" }
}
}
},
"/api/ucp/mcp": {
"get": {
"operationId": "getPaymentMethods",
"summary": "Discover active store payment methods",
"parameters": [
{ "name": "tool", "in": "query", "schema": { "type": "string", "default": "get_payment_methods" } },
{ "name": "postal_pin", "in": "query", "schema": { "type": "string" } },
{ "name": "cart_total", "in": "query", "schema": { "type": "number" } }
],
"responses": {
"200": { "description": "List of active payment methods" }
}
}
}
}
}Autonomous Agent Shopping Flow (Python Example) #
python
import requests
STORE_URL = "https://store.example.com"
# 1. Discover UCP Capabilities
discovery_res = requests.get(f"{STORE_URL}/.well-known/ucp").json()
print("Discovered UCP Version:", discovery_res["ucp"]["version"])
# 2. Search Store Catalog for Products
search_res = requests.get(f"{STORE_URL}/products.json", params={"q": "perfume", "limit": 5}).json()
products = search_res.get("products", [])
print(f"Found {len(products)} matching products.")
if products:
target_product = products[0]
first_variant = target_product["variants"][0]
print(f"Selected: {target_product['title']} - Variant #{first_variant['variant_id']}")
print(f"Price: ₹{first_variant['sale_price']} (MRP: ₹{first_variant['price']})")
# 3. Check Active Payment Gateways
payments_res = requests.get(
f"{STORE_URL}/api/ucp/mcp",
params={"tool": "get_payment_methods", "cart_total": first_variant["sale_price"]}
).json()
enabled_methods = [m["name"] for m in payments_res.get("methods", []) if m["available"]]
print("Available Payment Methods:", ", ".join(enabled_methods))
# 4. Generate 1-Click Hosted Checkout Permalink
checkout_url = f"{STORE_URL}/checkout?variant_id={first_variant['variant_id']}&quantity=1"
print("Buyer Checkout Permalink:", checkout_url)