Catalog

Why the catalog API

Your WhatsApp number can have a product catalog attached (from Meta Commerce Manager). Instead of adding products by hand on the Catalog page, use this API to push products from your source of truth (your store DB, an ERP, a spreadsheet) and to read back the orders customers submit from the catalogue.

All calls act on the catalog connected to your workspace’s default WhatsApp number — resolved from your API key — so nothing about the number, catalog id, or token is hardcoded.

Authentication

Every request sends your key as the X-API-Key header. A workspace admin creates one under Settings → API Keys (the token is shown once).

-H "X-API-Key: wa_live_xxx"

Get the connected catalog

curl https://api.whatbot.in/public/v1/catalog -H "X-API-Key: wa_live_xxx"

{ "connected": true, "catalog_id": "1234567890", "name": "My Store", "product_count": 42 }

Returns { "connected": false, "catalog_id": null, "name": null, "product_count": 0 } when no catalog is attached to the number — or when the lookup fails, so treat false as “not available right now” rather than proof there is no catalog.

List products

curl "https://api.whatbot.in/public/v1/catalog/products?limit=100&search=ring" \
  -H "X-API-Key: wa_live_xxx"

search (optional) — case-insensitive filter on the product name.
limit (optional, default 100) — the endpoint accepts up to 500, but only the first 100 products are ever fetched from WhatsApp, and there is no paging. search filters within those 100.

price and sale_price come back as WhatsApp formats them for display (e.g. "₹1,999.00"), not as the integer you write. Like GET /catalog, a failed lookup returns { "products": [] } rather than an error.

{
  "products": [
    {
      "retailer_id": "SKU-001",
      "name": "Gold Ring",
      "description": "22k, 4g",
      "price": "₹1,999.00",
      "currency": "INR",
      "sale_price": null,
      "availability": "in stock",
      "condition": "new",
      "visibility": "published",
      "brand": "Acme",
      "image_url": "https://cdn.example.com/ring.jpg",
      "url": "https://store.example.com/ring"
    }
  ]
}

Add or update a product

Upsert by retailer_id (your SKU): the first call creates the product, later calls with the same retailer_id update it.

curl -X POST https://api.whatbot.in/public/v1/catalog/products \
  -H "X-API-Key: wa_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "retailer_id": "SKU-001",
    "name": "Gold Ring",
    "description": "22k, 4g",
    "price": 199900,
    "currency": "INR",
    "availability": "in stock",
    "condition": "new",
    "image_url": "https://cdn.example.com/ring.jpg",
    "url": "https://store.example.com/ring"
  }'

{ "success": true, "product_id": "7890...", "retailer_id": "SKU-001" }

Field	Required	Notes
`retailer_id`	✅	Your SKU / Content ID — the upsert key. Up to 100 characters.
`name`	✅	Product title. Up to 200 characters.
`price`	✅	Integer in the currency’s minor units — paise/cents. `199900` = ₹1,999.00.
`currency`	✅	Three-letter ISO 4217 code, e.g. `INR`, `USD`.
`image_url`	✅	A public image URL that WhatsApp can fetch. Missing returns `422`.
`sale_price`	—	Integer minor units, like `price`.
`availability`	—	`in stock` · `out of stock` · `preorder` · `available for order` · `discontinued` (spaces, not underscores). Defaults to `in stock`.
`condition`	—	`new` · `refurbished` · `used`. Defaults to `new`.
`visibility`	—	`published` (shown) or `staging` (hidden). Defaults to `published`.
`description`, `brand`, `fb_product_category`, `url`	—	Optional metadata. `fb_product_category` takes a numeric category id or a taxonomy name.

Delete a product

curl -X DELETE https://api.whatbot.in/public/v1/catalog/products/SKU-001 \
  -H "X-API-Key: wa_live_xxx"

{ "success": true, "retailer_id": "SKU-001" }

List orders

Orders customers submitted from the catalog (WhatsApp order messages), newest first, with the customer’s name/number and the line items. limit defaults to 100, max 500.

curl "https://api.whatbot.in/public/v1/catalog/orders?limit=100" \
  -H "X-API-Key: wa_live_xxx"

{
  "orders": [
    {
      "id": "a1b2...",
      "conversation_id": "c9e6...",
      "customer_name": "Devi",
      "phone": "919876543210",
      "items": [
        { "retailer_id": "SKU-001", "name": "Gold Ring", "image_url": "https://cdn.example.com/ring.jpg", "url": "https://store.example.com/ring", "quantity": 2, "item_price": 1999.0, "currency": "INR" }
      ],
      "total": 3998.0,
      "currency": "INR",
      "note": "Gift wrap please",
      "created_at": "2026-07-14T06:03:28Z"
    }
  ]
}

item_price comes from the WhatsApp order as sent, and total is the sum of quantity × item_price. name falls back to the retailer_id when the product can’t be found in the catalog. phone is masked if your workspace masks the public API.

Errors

Failures return a 4xx with a plain-English detail (vendor codes and Graph URLs are stripped), e.g. A product image URL is required. or This WhatsApp number isn't permitted to manage its product catalog. A missing catalog returns 400 No product catalog is connected to this WhatsApp number.