{"slug": "show-hn-kalicart-an-agent-readable-catalog-for-woocommerce-no-api-key", "title": "Show HN: KaliCart – an agent-readable catalog for WooCommerce (no API key)", "summary": "KaliCart Bridge, a free WooCommerce plugin, makes product catalogs machine-readable for AI shopping agents without requiring an API key or cloud service. It exposes structured REST endpoints and discovery signals, enabling agents to filter by attributes like color and stock with high accuracy, as demonstrated in a blind test. The plugin also supports federated catalog search via KaliCart Global and UCP interoperability for agents like ChatGPT and Copilot.", "body_md": "Free WooCommerce plugin that makes your product catalog machine-readable for AI shopping agents.\n\nARC/1.0 reference implementation · No LLM · No cloud · No API key\n\nWhen an AI shopping agent visits a WooCommerce store today, its default behavior is to fetch the storefront HTML and scrape product data from it. This is the wrong approach — and in a documented blind test on a live store, the cost was measurable:\n\n| Approach | API calls | Payload | Stock accuracy | Color filtering |\n|---|---|---|---|---|\n| HTML scraping | 5–6 | ~400 KB | High (dropdowns show real variants) | Manual, from text |\nWordPress REST (`wp/v2/product` ) |\n2 | ~77 KB (truncated) | Low — `class_list` reports defined sizes, not in-stock ones |\nNone |\nKaliCart Bridge (ARC/1.0) |\n2 |\n~4–5 KB (≈10 KB incl. discovery) |\nHigh — per-variant quantity with confidence level |\nNative `color=` filter |\n\n*Blind test: finding a dark-colored women's two-piece swimsuit, size S, under €150, on a live WooCommerce store. The agent was given no hints. It scraped HTML first, then tried the generic WordPress REST API (which produced a false positive on stock), and found the structured kalicart/v1 catalog only when explicitly pointed at it — even though that namespace was reachable from /wp-json the whole time. See *\n\n[BENCHMARK.md](/giuseppesocci-bot/kalicart-bridge/blob/main/BENCHMARK.md)for the full run, including honest caveats (n=1, discovery cost).\n\n**The signal to do better has always been there.** Every WordPress site already emits ``\n\nin the HTML ``\n\n. An agent that reads the head before scraping finds the REST API namespace in one call, discovers `kalicart/v1`\n\n, and filters natively. KaliCart Bridge makes that path correct and complete.\n\nKaliCart Bridge installs on any WooCommerce store and exposes five things:\n\n-\n**A discovery document**(`/wp-json/kalicart/v1/discovery`\n\n) — a self-describing JSON contract that tells an agent everything it needs: all endpoint URLs, accepted filters, shipping policy, coupon rules, agent instructions. One GET, no documentation required. -\n**A computable catalog**— structured REST endpoints for search, product listing, categories, and per-product detail including live stock per variant, price encoding declaration, purchase readiness, and shipping eligibility. -\n**Agent discovery signals**—``\n\nin the storefront``\n\n,`.well-known/kalicart-bridge.json`\n\n,`.well-known/agent-catalog.json`\n\n,`robots.txt`\n\nentries, and an agentic sitemap — so agents that land on the storefront can find the API without scraping. -\n**UCP interoperability**—`/.well-known/ucp.json`\n\ndeclares`catalog.search`\n\nand`catalog.lookup`\n\ncapabilities for UCP-compliant agents (ChatGPT, Copilot, Gemini). -\n**Federated catalog opt-in**— one toggle publishes eligible products into[KaliCart Global](https://global.kalicart.com), a read-only multi-merchant index that AI agents can query across stores without knowing any individual merchant in advance.\n\n```\nAI agent\n │\n ├─ 1. GET global.kalicart.com/v1/global-catalog/search?q=... ← find merchants + products\n │ (federated index — optional first step)\n │\n ├─ 2. GET {merchant}/wp-json/kalicart/v1/discovery ← read contract\n │\n ├─ 3. GET {merchant}/wp-json/kalicart/v1/catalog/search ← native filters\n │ ?q=bikini&color=purple&in_stock=true&max_price=150\n │\n └─ 4. GET {merchant}/wp-json/kalicart/v1/catalog/product/{id} ← verify variants + stock\n → per-variant quantity, shipping eligibility, purchase readiness\n │\n └─ Checkout always on merchant storefront (KaliCart never processes payments)\n```\n\n**Three layers of authority:**\n\n**KaliCart Global**— discovery and routing across the federated network** Merchant bridge**— authoritative price, live stock, variant detail** Merchant storefront**— sole authority for checkout and payment\n\n- Download\nor install from`kalicart-bridge-latest.zip`\n\n[WordPress.org](https://wordpress.org/plugins/kalicart-bridge/) - Upload and activate from\n**WP Admin → Plugins → Add New → Upload** - WooCommerce must be active\n- All discovery signals are injected automatically on activation\n- Visit\n**WP Admin → KaliCart** for the catalog health dashboard\n\nThat's it. Your catalog is now machine-readable.\n\nEvery ARC-compliant storefront emits this tag:\n\n```\n\n```\n\n**Read the before scraping.** This single tag gives you the discovery document URL directly.\n\n```\nGET https://shop.example.com/wp-json/kalicart/v1/discovery\n```\n\nThe discovery document is a self-describing contract. It contains:\n\n- All endpoint URLs\n- Accepted filter values (categories, colors, genders, price range)\n- Shipping policy\n- Coupon rules\n`agent_instructions`\n\n— ordered steps for correct query construction`result_guidance`\n\n— embedded in every response, tells you what to do next\n\n```\nGET /wp-json/kalicart/v1/catalog/search\n ?category=donna-beachwear-resortwear-bikini\n &color=purple\n &in_stock=true\n &max_price=150\n```\n\n**Critical rule:** `q`\n\nmust contain only the bare product noun. Every attribute (color, gender, size, price) must go in its own filter — never stacked into `q`\n\n.\n\n```\n✓ correct\nGET /catalog/search?q=bikini&color=black&gender=female&max_price=150&in_stock=true\n\n✗ wrong — zero results\nGET /catalog/search?q=black+women+bikini+under+150\n```\n\nSearch responses return product-level stock. For variable products (size, color variants), fetch the detail endpoint to get per-variant quantities:\n\n```\nGET /wp-json/kalicart/v1/catalog/product/{id}\n```\n\nResponse includes:\n\n```\n{\n \"variants\": [\n {\n \"attributes\": { \"pa_taglia\": \"s\" },\n \"stock\": {\n \"in_stock\": true,\n \"quantity\": 1,\n \"confidence\": \"numeric_stock_quantity\",\n \"agent_note\": \"Last unit available. Race condition possible — complete checkout immediately.\"\n }\n }\n ],\n \"shipping\": {\n \"free_shipping_available\": true,\n \"free_shipping_eligible_by_product_price\": true\n }\n}\n```\n\nTo find products without knowing the merchant in advance:\n\n```\nGET https://global.kalicart.com/v1/global-catalog/search\n ?q=bikini&color=purple&gender=female&price_max=150&availability=in_stock\n```\n\nResults include `merchant_id`\n\nand a link to the merchant's bridge for authoritative verification.\n\nEvery KaliCart Bridge response includes a `result_guidance`\n\nfield that tells the agent how to proceed:\n\n```\n{\n \"result_guidance\": {\n \"code\": \"SUMMARY_TRIAGE\",\n \"next_step\": \"rank_from_summary_then_verify_one_selected_product\",\n \"fact_coverage\": {\n \"complete_for\": [\"product_identity\", \"catalog_price\", \"availability_status\"],\n \"detail_required_for\": [\"exact_variants_or_sizes\", \"stock_precision_beyond_status\"]\n },\n \"detail_fetch_policy\": {\n \"verification_url_template\": \"https://shop.example.com/wp-json/kalicart/v1/catalog/product/{id}\"\n }\n }\n}\n```\n\nThis means agents do not need external documentation to know what to do next. The API tells them.\n\nKaliCart Bridge is the reference implementation of ** ARC/1.0 — Agent-Readable Catalog**, an open specification (CC BY 4.0) for exposing e-commerce catalogs as agent-consumable REST surfaces.\n\nARC/1.0 defines:\n\n- Three discovery signals (HTML head link,\n`.well-known/`\n\n,`robots.txt`\n\n) - The discovery document contract\n- Catalog endpoint requirements\n- The product object schema (price encoding, stock confidence levels, variant contract)\n- Consent model for federated indexing\n- UCP interoperability\n- Security rules (read-only, no API keys on public surfaces)\n\nAny e-commerce platform can implement ARC/1.0. KaliCart Bridge does it for WooCommerce.\n\nEvery AI agent that scrapes instead of using a structured catalog wastes:\n\n**~40× more data per task**(~400 KB scraped vs ~10 KB end-to-end including discovery, in the documented test)** More API calls**(5–6 vs 2 for the catalog calls)** LLM tokens**parsing irrelevant HTML boilerplate** Latency**on every user-facing query\n\nThe data returned by scraping the generic WordPress REST API is also less accurate: HTML dropdowns show truly available variants, but the `wp/v2`\n\n`class_list`\n\nfield reports all defined sizes regardless of current stock. In the documented test, an agent trusting `class_list`\n\nwould have reported a size as available when it was sold out.\n\nAs agentic commerce grows, the aggregate cost of the scraping default — compute, latency, and wrong answers handed to shoppers — becomes significant and avoidable. ARC/1.0 and KaliCart Bridge exist to change that default.\n\n**Plugin hub & download**:[bridge.kalicart.com](https://bridge.kalicart.com)** ARC/1.0 specification**:[bridge.kalicart.com/spec](https://bridge.kalicart.com/spec/)** Documentation**:[bridge.kalicart.com/docs](https://bridge.kalicart.com/docs/)** Federated catalog**:[global.kalicart.com](https://global.kalicart.com)** WordPress MCP plugin**:[mcp.kalicart.com](https://mcp.kalicart.com)** Institutional**:[kalicart.com](https://kalicart.com)** WordPress.org**:[wordpress.org/plugins/kalicart-bridge](https://wordpress.org/plugins/kalicart-bridge/)\n\nPlugin code: [GPLv2](https://www.gnu.org/licenses/gpl-2.0)\n\nARC/1.0 specification text: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)\n\n© 2026 Save The Brain", "url": "https://wpnews.pro/news/show-hn-kalicart-an-agent-readable-catalog-for-woocommerce-no-api-key", "canonical_source": "https://github.com/giuseppesocci-bot/kalicart-bridge", "published_at": "2026-06-29 16:08:24+00:00", "updated_at": "2026-06-29 16:20:48.317139+00:00", "lang": "en", "topics": ["ai-agents", "ai-products", "ai-tools", "ai-infrastructure", "developer-tools"], "entities": ["KaliCart", "WooCommerce", "WordPress", "ChatGPT", "Copilot", "Gemini", "KaliCart Global", "ARC/1.0"], "alternates": {"html": "https://wpnews.pro/news/show-hn-kalicart-an-agent-readable-catalog-for-woocommerce-no-api-key", "markdown": "https://wpnews.pro/news/show-hn-kalicart-an-agent-readable-catalog-for-woocommerce-no-api-key.md", "text": "https://wpnews.pro/news/show-hn-kalicart-an-agent-readable-catalog-for-woocommerce-no-api-key.txt", "jsonld": "https://wpnews.pro/news/show-hn-kalicart-an-agent-readable-catalog-for-woocommerce-no-api-key.jsonld"}}