Merchant copilot

The merchant copilot is a small set of admin-only REST endpoints under fahad-ai/v1/admin. Each one returns real WooCommerce data, sales, refunds, product attributes, unanswered reviews, so the copilot can reason over your actual numbers instead of inventing them. The copilot proposes; you apply.

What it is, and is not

These endpoints are separate from the storefront assistant. They are not exposed to shoppers, they do not use the storefront nonce, and they never write to your store. Every route is read-only and returns grounded data straight from WooCommerce. The copilot drafts and suggests; nothing reaches your catalogue, prices or reviews until you act on it yourself.

Who can call them

Every admin endpoint is gated by the manage_woocommerce capability, the same gate a real store manager has. There is no public or shopper path to this data. The permission check is centralised, so all four routes share one contract: if you cannot manage WooCommerce, you get nothing back.

GET /wp-json/fahad-ai/v1/admin/insights
GET /wp-json/fahad-ai/v1/admin/sale-candidates
GET /wp-json/fahad-ai/v1/admin/product-context
GET /wp-json/fahad-ai/v1/admin/review-drafts

Store insights

GET /admin/insights returns a grounded sales summary for a recent window: order count, gross revenue, refund total, refunded order count, and the store currency. It counts only real completed and processing orders. Pass days to set the window. It is clamped to a sensible 1 to 90 days, and defaults to 7.

GET /wp-json/fahad-ai/v1/admin/insights?days=30

{
  "window_days": 30,
  "orders": 142,
  "revenue": 8740.50,
  "refunds": 210.00,
  "refunded_orders": 3,
  "currency": "USD"
}

Sale candidates

GET /admin/sale-candidates surfaces products worth considering for a discount. The list is filtered to products that are in stock and not already on sale, then ranked so the slowest movers, fewest recent units sold, come first. Each candidate carries a concrete, bounded suggested discount so the copilot proposes an actual deal rather than a vague nudge. Pass limit to cap the count.

GET /wp-json/fahad-ai/v1/admin/sale-candidates?days=30&limit=5

{
  "candidates": [
    {
      "id": 812,
      "name": "Linen Travel Pouch",
      "price": 24.00,
      "units_sold": 1,
      "suggested_discount_percent": 10
    }
  ]
}

This is a proposal, not an action. No sale price is set and no product is touched. You review the candidates and decide which, if any, go on sale.

Product context

GET /admin/product-context returns a single product's real attributes: name, SKU, price, categories, attribute values and the short description, stripped to plain text. This is the grounding for any generated description, SEO meta or alt text, so the copilot can rewrite the wording without inventing specifications. It returns trusted WooCommerce fields only. Pass the product_id.

GET /wp-json/fahad-ai/v1/admin/product-context?product_id=812

{
  "id": 812,
  "name": "Linen Travel Pouch",
  "sku": "LTP-001",
  "price": 24.00,
  "categories": ["Travel", "Accessories"],
  "attributes": { "Material": "Linen", "Color": "Sand" },
  "short_description": "A light, packable pouch for cables and small essentials."
}

If the product does not exist, the endpoint returns a 404 rather than a guess. The copilot stays inside these facts when it drafts copy.

Review drafts

GET /admin/review-drafts lists approved product reviews that have no store reply yet, along with the real review text and rating a drafted reply must address. A review counts as answered once it has a child comment, an existing reply, so answered reviews drop off the list. The content is the actual review, never a fabricated one. Pass limit to cap the count.

GET /wp-json/fahad-ai/v1/admin/review-drafts?limit=10

{
  "reviews": [
    {
      "id": 5531,
      "product_id": 812,
      "author": "Dana R.",
      "rating": 4,
      "content": "Great little pouch, wish it came in more colors."
    }
  ]
}

The endpoint gives the copilot the genuine review and rating so the reply it drafts speaks to what the customer actually said. The reply is a draft for you to read, edit and post.

How a merchant uses it

1. The copilot calls /admin/insights to ground itself in your recent sales and refunds.
2. It calls /admin/sale-candidates to propose specific slow movers to discount, with a suggested percentage.
3. For copy work it calls /admin/product-context so any description or meta it drafts sticks to your real product facts.
4. For customer care it calls /admin/review-drafts to draft replies to the reviews you have not answered yet.
5. You review each proposal and apply the ones you want. The endpoints never make the change for you.