Turn Woo catalog into an AI-ready API — now on WordPress.org

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.

That'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.

That'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.

Start with discovery, not endpoints

The 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:

GET /wp-json/kalicart/v1/discovery

{
  "document_kind": "kalicart_merchant_bridge",
  "schema_version": "1.0",
  "plugin_version": "1.0.101",
  "capabilities": {
    "search": true,
    "availability": true,
    "shipping_policy": true,
    "cart": false,
    "checkout": false,
    "payments": false,
    "mutations": false,
    "read_only": true,
    "mcp": true
  },
  "freshness": {
    "source": "live_woocommerce_database",
    "is_realtime": true,
    "is_sync_snapshot": false
  }
}

Two design choices worth calling out here:

It's read-only and says so explicitly. cart, checkout, payments, and mutations are all false. 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.

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.

The endpoints

Discovery advertises the read surface:

{
  "endpoints": {
    "discovery":  "/wp-json/kalicart/v1/discovery",
    "search":     "/wp-json/kalicart/v1/catalog/search",
    "products":   "/wp-json/kalicart/v1/catalog/products",
    "product":    "/wp-json/kalicart/v1/catalog/product/{id}",
    "categories": "/wp-json/kalicart/v1/catalog/categories",
    "meta":       "/wp-json/kalicart/v1/catalog/meta",
    "mcp":        "/wp-json/kalicart/v1/mcp"
  },
  "authentication": { "required": false, "scheme": "none" }
}

No API key. The public catalog is public — the same information a human sees on the storefront, just structured.

Query construction: the spine goes in q, attributes go in filters

This is the part most people get wrong when they design a search API for agents, so the discovery document is prescriptive about it:

{
  "query_construction": {
    "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.",
    "correct": [
      "?q=t-shirt&gender=male&max_price=50",
      "?q=costume&gender=female&color=blue"
    ]
  }
}

Agents love to cram "blue men's t-shirt under 50" into a single search string. Against a real catalog, that returns nothing. By splitting the product spine (q=t-shirt) from structured filters (gender, color, max_price), 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.

A real search response

GET /wp-json/kalicart/v1/catalog/search?q=t-shirt&max_price=50

{
  "success": true,
  "total": 1,
  "products": [
    {
      "id": 460,
      "name": "T-shirt Nike Sportswear",
      "price": {
        "currency": "EUR",
        "encoding": "decimal_major_units",
        "regular": 22,
        "sale": 20,
        "current": 20,
        "on_sale": true,
        "discount_pct": 9.1,
        "display": "20,00 €"
      },
      "stock": {
        "availability_status": "in_stock",
        "in_stock": true,
        "quantity_tracked": false,
        "confidence": "availability_status_only",
        "agent_note": "Merchant does not expose numeric stock quantity. Treat as available for purchase, not as confirmed inventory count."
      },
      "categories": [
        { "id": 33, "name": "Uomo", "slug": "uomo", "path": "Moda > Uomo" }
      ]
    }
  ]
}

Notice what's modeled here that scraping can't reliably recover:

• Price is unambiguous. current, regular, sale, and the on-sale flag are separate fields, plus a display string for humans and an explicit encoding so nobody confuses major units with ISO minor units.
• Stock carries its own confidence. This merchant doesn't track numeric inventory, so the response says so and tells the agent how to interpret it — "available for purchase" is not the same claim as "47 in stock." That distinction is the difference between an agent making a safe statement and a wrong one.
• Categories are the merchant's own. The Bridge doesn't force a global taxonomy onto the store; it exposes the merchant's native WooCommerce categories with their full path, and a /catalog/categories endpoint to enumerate them. The principle behind the whole thing is that the domain constrains the machine, not the merchant.

Evidence-required reasoning

The discovery document also ships a rule that's more about agent behavior than data shape:

{
  "evidence_required": {
    "rule": "Every product claim must be traceable to a catalog field.",
    "sources": ["product_url", "price.current", "stock.in_stock", "stock.confidence"],
    "note": "Do not present prices, availability or shipping estimates without citing the source field."
  }
}

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

REST or MCP — same data

For agent runtimes that speak Model Context Protocol, the same read-only catalog is exposed as an MCP server over JSON-RPC 2.0:

{
  "mcp": {
    "enabled": true,
    "transport": "http-post-jsonrpc-2.0",
    "endpoint": "/wp-json/kalicart/v1/mcp",
    "tools": ["search_products", "get_product", "list_products", "list_categories", "get_meta"]
  }
}

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

Where checkout lives (and doesn't)

The 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 for 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.

Try it

It'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 your own /wp-json/kalicart/v1/discovery and point an agent at it.

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