Product Insights

The product-insights endpoint analyses a single product's sales, purchases, and cost history and returns a prioritised list of business insights — margin compression, cost spikes, demand anomalies, supplier reliability problems, seasonality, currency effects, and more. Each insight comes with a severity, a plain-language explanation, the metrics behind it, and a concrete recommendation. Call it again later and it also tells you what has changed since the last time.

1. The Endpoint

A single synchronous POST. Send whichever of the three datasets you have; the endpoint runs every analyser that its inputs support and returns all insights in one response. You do not need to call /forecast or any other endpoint first — the required statistical modelling happens internally.

{
  "identifier": "SKU-12345",
  "product_name": "Wireless Mouse",
  "base_currency": "USD",
  "sales": [
    {"date": "2024-01-05", "quantity_sold": 12, "selling_price": 25.00},
    {"date": "2024-02-05", "quantity_sold": 18, "selling_price": 25.00},
    {"date": "2024-03-05", "quantity_sold": 9,  "selling_price": 22.50}
  ],
  "purchases": [
    {"date": "2024-01-01", "quantity_purchased": 100, "cost_price": 10.00,
     "supplier_id": "SUPP-001", "purchase_order_date": "2023-12-18",
     "expected_delivery_date": "2023-12-30", "actual_delivery_date": "2024-01-01"}
  ],
  "cost_history": [
    {"date": "2024-01-01", "cost_price": 10.00},
    {"date": "2024-03-01", "cost_price": 11.50, "change_reason": "supplier price increase"}
  ],
  "insight_settings": {
    "margin_threshold": 0.10,
    "enable_seasonality_detection": true
  }
}

2. Request Parameters

Top-level fields identify the product and configure the analysis. Unlike the forecasting endpoints, product-insights takes no model, periods, or frequency — it works directly off the data you provide.

3. Datasets

Every row in every dataset needs a date. Dates must be YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, and the format must be consistent within a dataset (you cannot mix date-only and date-time rows in the same array). Rows are sorted chronologically for you, so you can send them in any order.

sales[]

purchases[]

cost_history[]

4. Tuning & Thresholds

The optional insight_settings object controls how sensitive the analysers are. Thresholds are expressed as fractions — 0.30 means "flag a 30% change." Anything you omit falls back to the defaults below.

5. Response Structure

On success (HTTP 200) the body always has the same top-level shape: a result object holding the analysis, and a meta object holding timing and data-quality info.

{
  "result": {
    "tenant_context": null,
    "identifier": "SKU-12345",
    "product_info": { "name": "Wireless Mouse", "group_id": null },
    "base_currency": "USD",
    "insights": [
      {
        "class": "margin",
        "type": "margin_compression",
        "severity": "warning",
        "title": "Margin dropped 8.2% versus baseline",
        "description": "Average gross margin fell from 58.0% to 49.8% over the recent period.",
        "metrics": {
          "current_margin_percent": 49.8,
          "baseline_margin_percent": 58.0,
          "margin_change_percentage": -8.2,
          "transactions_analyzed": 3
        },
        "recommendation": {
          "action": "review_pricing",
          "description": "Review selling price or negotiate cost to protect margin.",
          "priority": "high"
        },
        "confidence": "medium",
        "date": "2024-03-05",
        "change_status": "new"
      }
    ],
    "summary": {
      "total_insights": 1,
      "severity_distribution": { "critical": 0, "warning": 1, "info": 0 },
      "categories": ["profitability"],
      "analysis_period": { "start_date": "2024-01-01", "end_date": "2024-03-05", "total_days": 65 },
      "data_sources_analyzed": ["sales", "purchases", "cost_history"]
    },
    "comparison": null
  },
  "meta": {
    "timing": { "validation": 2.1, "analysis": 148.7, "total": 151.9 },
    "data_quality": {
      "total_data_points": 6,
      "datasets_provided": ["sales", "purchases", "cost_history"]
    }
  }
}

result fields

result.summary fields

summary.categories — possible values

Each insight type maps to one business category. On this single-product endpoint you will see these values:

Portfolio-level categories (pricing, customer_risk, portfolio_risk, categories, inventory_management) only appear via batch analysis, which compares products against each other.

Anatomy of an Insight

Every entry in insights has the same envelope. The metrics object is the only part whose keys vary — they depend on the insight type (documented in the catalog).

6. Insight Catalog

Which analysers run depends on which datasets you send. The tables below group every insight type by the dataset that unlocks it, with the severity levels it can emit and its most important metrics. A type only appears in the response when its trigger condition (usually a change beyond the relevant threshold) is met.

Requires sales

Requires purchases

Requires cost_history

Cross-currency (any dataset, needs ≥ 2 distinct currencies)

7. Change Tracking

Every analysis is stored against its identifier (and tenant_context, if given). On the next call for the same product, the endpoint diffs the new insights against the previous run and returns a comparison object — so you can surface "what's new since last time" instead of re-showing everything. It is null only on the very first analysis.

"comparison": {
  "from": "2024-06-01T09:14:22+00:00",
  "to": "2024-07-01T08:02:11+00:00",
  "result": [
    {
      "hasSignificantChange": true,
      "summary": "Margin fell a further 4.1 points",
      "changes": [
        {
          "class": "margin",
          "metric": "current_margin_percent",
          "previousValue": 49.8,
          "currentValue": 45.7,
          "change": -4.1,
          "changePercentage": -8.2,
          "isSignificant": true,
          "severity": "warning",
          "description": "Margin continued to compress."
        }
      ]
    }
  ],
  "developments": {
    "new": [ { "type": "cost_price_change", "class": "cost", "severity": "warning", "title": "Unit cost up 15%" } ],
    "changed": [ { "type": "margin_compression", "class": "margin", "severity": "warning", "title": "Margin dropped further" } ],
    "resolved": [ { "type": "sales_volume_anomaly", "class": "sales", "severity": "info", "title": "Sales spike normalised" } ],
    "unchanged_count": 2,
    "summary": "1 new, 1 changed, 1 resolved, 2 unchanged"
  }
}

developments

8. Response Metadata

The top-level meta object reports timing and a quick read on the data you supplied.

9. Batch Analysis

To analyse many products at once, upload them as a batch. Batch analysis runs asynchronously and additionally computes portfolio-level insights that compare products against each other (ABC classification, customer and product-group concentration, price elasticity, weekday performance) — insights the single-product endpoint cannot produce.

{
  "series": [
    {
      "identifier": "SKU-1",
      "sales": [
        {"date": "2024-01-15", "quantity_sold": 10, "selling_price": 5.00},
        {"date": "2024-02-15", "quantity_sold": 20, "selling_price": 5.00}
      ]
    },
    {
      "identifier": "SKU-2",
      "cost_history": [
        {"date": "2024-01-01", "cost_price": 2.00},
        {"date": "2024-03-01", "cost_price": 2.60}
      ]
    }
  ]
}

{
  "uuid": "9b2c...",
  "identifier": "my-batch-01",
  "status": "completed",
  "batch_parts": 1,
  "results": [ /* one analysis per product, same shape as result.insights */ ],
  "started_at": "2024-07-01T08:00:00+00:00",
  "completed_at": "2024-07-01T08:00:12+00:00"
}

10. Error Responses

{
  "error": "Validation failed",
  "errors": {
    "identifier": ["The identifier field is required."],
    "data": ["At least one dataset (sales, purchases, or cost_history) must be provided."]
  },
  "time_taken_ms": 1.4
}

{
  "error": "Could not analyse the supplied data",
  "time_taken_ms": 3.2
}

Next Steps