{"slug": "turn-woo-catalog-into-an-ai-ready-api-now-on-wordpress-org", "title": "Turn Woo catalog into an AI-ready API — now on WordPress.org", "summary": "KaliCart Bridge, a new WooCommerce plugin now available on WordPress.org, exposes product catalogs as a read-only, agent-oriented API with a discovery document. The plugin provides live data from the WooCommerce database, avoiding fragile HTML scraping, and includes explicit rules for query construction to ensure agents get accurate results.", "body_md": "AI agents are starting to shop. Not in a sci-fi way — in a \"your storefront is getting hit by something that parses HTML, recovers a price, and gets it wrong\" way. If you run a WooCommerce store, the agent reading it today has to scrape the rendered product page and reverse-engineer what's for sale, what it costs, and whether it's in stock.\n\nThat's fragile, and it's the wrong layer. A catalog already knows all of this precisely. It should just say so, in a format built for machines.\n\nThat's what **KaliCart Bridge** does — a WooCommerce plugin (now on the WordPress.org directory, search \"KaliCart Bridge\") that exposes the catalog as a read-only, agent-oriented API with a discovery document. Below is how it's designed and why, with real responses from a live install.\n\nThe entry point is a single discovery document. An agent fetches it first and learns the catalog's capabilities, endpoints, and rules before issuing a single product query:\n\n```\nGET /wp-json/kalicart/v1/discovery\n{\n  \"document_kind\": \"kalicart_merchant_bridge\",\n  \"schema_version\": \"1.0\",\n  \"plugin_version\": \"1.0.101\",\n  \"capabilities\": {\n    \"search\": true,\n    \"availability\": true,\n    \"shipping_policy\": true,\n    \"cart\": false,\n    \"checkout\": false,\n    \"payments\": false,\n    \"mutations\": false,\n    \"read_only\": true,\n    \"mcp\": true\n  },\n  \"freshness\": {\n    \"source\": \"live_woocommerce_database\",\n    \"is_realtime\": true,\n    \"is_sync_snapshot\": false\n  }\n}\n```\n\nTwo design choices worth calling out here:\n\n**It's read-only and says so explicitly.** `cart`\n\n, `checkout`\n\n, `payments`\n\n, and `mutations`\n\nare all `false`\n\n. The Bridge is a read surface over the catalog — it never touches orders or money. Checkout authority stays with the WooCommerce storefront. An agent reading this knows immediately what it is and isn't allowed to assume.\n\n**Data is live, not a sync snapshot.** Responses are read straight from the WooCommerce database at query time. There's no separate index to fall out of date — the price the agent reads is the price in the store right now.\n\nDiscovery advertises the read surface:\n\n```\n{\n  \"endpoints\": {\n    \"discovery\":  \"/wp-json/kalicart/v1/discovery\",\n    \"search\":     \"/wp-json/kalicart/v1/catalog/search\",\n    \"products\":   \"/wp-json/kalicart/v1/catalog/products\",\n    \"product\":    \"/wp-json/kalicart/v1/catalog/product/{id}\",\n    \"categories\": \"/wp-json/kalicart/v1/catalog/categories\",\n    \"meta\":       \"/wp-json/kalicart/v1/catalog/meta\",\n    \"mcp\":        \"/wp-json/kalicart/v1/mcp\"\n  },\n  \"authentication\": { \"required\": false, \"scheme\": \"none\" }\n}\n```\n\nNo API key. The public catalog is public — the same information a human sees on the storefront, just structured.\n\n`q`\n\n, attributes go in filters\nThis is the part most people get wrong when they design a search API for agents, so the discovery document is prescriptive about it:\n\n```\n{\n  \"query_construction\": {\n    \"rule\": \"q must contain ONLY the bare product noun (the spine). Every attribute (category, gender, color, price) MUST go in its own structured filter, never inside q. Stacking attributes into q returns 0 results.\",\n    \"correct\": [\n      \"?q=t-shirt&gender=male&max_price=50\",\n      \"?q=costume&gender=female&color=blue\"\n    ]\n  }\n}\n```\n\nAgents love to cram `\"blue men's t-shirt under 50\"`\n\ninto a single search string. Against a real catalog, that returns nothing. By splitting the product spine (`q=t-shirt`\n\n) from structured filters (`gender`\n\n, `color`\n\n, `max_price`\n\n), search stays predictable and the agent gets results instead of an empty array. The contract tells the agent how to behave, so you don't depend on it guessing right.\n\n```\nGET /wp-json/kalicart/v1/catalog/search?q=t-shirt&max_price=50\n{\n  \"success\": true,\n  \"total\": 1,\n  \"products\": [\n    {\n      \"id\": 460,\n      \"name\": \"T-shirt Nike Sportswear\",\n      \"price\": {\n        \"currency\": \"EUR\",\n        \"encoding\": \"decimal_major_units\",\n        \"regular\": 22,\n        \"sale\": 20,\n        \"current\": 20,\n        \"on_sale\": true,\n        \"discount_pct\": 9.1,\n        \"display\": \"20,00 €\"\n      },\n      \"stock\": {\n        \"availability_status\": \"in_stock\",\n        \"in_stock\": true,\n        \"quantity_tracked\": false,\n        \"confidence\": \"availability_status_only\",\n        \"agent_note\": \"Merchant does not expose numeric stock quantity. Treat as available for purchase, not as confirmed inventory count.\"\n      },\n      \"categories\": [\n        { \"id\": 33, \"name\": \"Uomo\", \"slug\": \"uomo\", \"path\": \"Moda > Uomo\" }\n      ]\n    }\n  ]\n}\n```\n\nNotice what's modeled here that scraping can't reliably recover:\n\n`current`\n\n, `regular`\n\n, `sale`\n\n, and the on-sale flag are separate fields, plus a `display`\n\nstring for humans and an explicit `encoding`\n\nso nobody confuses major units with ISO minor units.`/catalog/categories`\n\nendpoint to enumerate them. The principle behind the whole thing is that the domain constrains the machine, not the merchant.The discovery document also ships a rule that's more about agent behavior than data shape:\n\n```\n{\n  \"evidence_required\": {\n    \"rule\": \"Every product claim must be traceable to a catalog field.\",\n    \"sources\": [\"product_url\", \"price.current\", \"stock.in_stock\", \"stock.confidence\"],\n    \"note\": \"Do not present prices, availability or shipping estimates without citing the source field.\"\n  }\n}\n```\n\nThe point is to make hallucination structurally harder. If every claim an agent makes has to map back to a concrete field, it can't invent a price or a delivery promise — it either has the field or it doesn't.\n\nFor agent runtimes that speak Model Context Protocol, the same read-only catalog is exposed as an MCP server over JSON-RPC 2.0:\n\n```\n{\n  \"mcp\": {\n    \"enabled\": true,\n    \"transport\": \"http-post-jsonrpc-2.0\",\n    \"endpoint\": \"/wp-json/kalicart/v1/mcp\",\n    \"tools\": [\"search_products\", \"get_product\", \"list_products\", \"list_categories\", \"get_meta\"]\n  }\n}\n```\n\nSame catalog, same read-only guarantees — pick whichever your stack prefers. REST if you're calling HTTP directly, MCP if you're wiring it into an agent framework that already speaks the protocol.\n\nThe Bridge deliberately stops short of payment. There's a defined contract for an optional checkout *session* — create a WooCommerce cart and hand back a `checkout_url`\n\nfor a human to finish — but it processes nothing and creates no order. Full autonomous checkout (agent holds a pre-authorized mandate, completes the purchase end to end) is on the roadmap as an AP2-compatible contract, gated on WooCommerce/gateway support for programmatic payment confirmation. Until that exists, the safe boundary is: agents read the catalog, humans (or a redirect) own the money.\n\nIt's free on the WordPress.org directory — search \"KaliCart Bridge\" in your plugins page, activate, and your catalog gets a discovery document and the read endpoints above. Then `curl`\n\nyour own `/wp-json/kalicart/v1/discovery`\n\nand point an agent at it.\n\nFeedback from people who build agents or live in WooCommerce internals is exactly what I'm after — especially catalog edge cases and anything in the agent contract that reads ambiguously.", "url": "https://wpnews.pro/news/turn-woo-catalog-into-an-ai-ready-api-now-on-wordpress-org", "canonical_source": "https://dev.to/kalicart-bridge/turn-woo-catalog-into-an-ai-ready-api-now-on-wordpressorg-jdo", "published_at": "2026-06-18 16:47:20+00:00", "updated_at": "2026-06-18 16:59:23.662406+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["KaliCart Bridge", "WooCommerce", "WordPress.org"], "alternates": {"html": "https://wpnews.pro/news/turn-woo-catalog-into-an-ai-ready-api-now-on-wordpress-org", "markdown": "https://wpnews.pro/news/turn-woo-catalog-into-an-ai-ready-api-now-on-wordpress-org.md", "text": "https://wpnews.pro/news/turn-woo-catalog-into-an-ai-ready-api-now-on-wordpress-org.txt", "jsonld": "https://wpnews.pro/news/turn-woo-catalog-into-an-ai-ready-api-now-on-wordpress-org.jsonld"}}