/api/segment_cluster_profiles

Header

X-Customer-Api-Id: <uuid> 
X-Secret:          <secret> 
Content-Type:      application/json 

Request Body Schema

customers: array<object>  
  id: string  
  frequency: int  
  amount_spent: float  
  product_types: array<string>  

labels: object<customer_id: cluster_id> 

Example Request Body

{
  "customers": [
    { "id": "C001", "frequency": 28, "amount_spent": 4120.75, "product_types": ["laptop","mouse","keyboard","monitor"] },
    { "id": "C002", "frequency":  5, "amount_spent":  190.40, "product_types": ["tea","coffee"] },
    { "id": "C003", "frequency": 12, "amount_spent":  845.10, "product_types": ["jeans","t-shirt","sneakers"] },
    { "id": "C004", "frequency":  2, "amount_spent":   75.00, "product_types": ["notebook"] },
    { "id": "C005", "frequency": 17, "amount_spent": 1324.55, "product_types": ["smartphone","earbuds"] },
    { "id": "C006", "frequency":  8, "amount_spent":  510.30, "product_types": ["dog food","cat food"] },
    { "id": "C007", "frequency": 24, "amount_spent": 2780.90, "product_types": ["smart-tv","soundbar","hdmi-cable"] },
    { "id": "C008", "frequency": 10, "amount_spent":  660.00, "product_types": ["yogurt","milk","cheese"] },
    { "id": "C009", "frequency":  3, "amount_spent":  120.00, "product_types": ["stationery"] },
    { "id": "C010", "frequency": 15, "amount_spent":  975.65, "product_types": ["beer","wine","snacks"] }
  ],
  "labels": {
    "C001": 0, "C002": 0, "C003": 0, "C004": 0, "C005": 0,
    "C006": 0, "C007": 1, "C008": 0, "C009": 0, "C010": 1
  }
}

Example Response Body

{
  "cluster_profiles": [
    {
      "cluster_id": 0,
      "n_customers": 31,
      "avg_spend": 591.11,
      "median_spend": 540.0,
      "avg_frequency": 8.81,
      "top_categories": "wine, cheese, diapers, sd-card, office-chair",
      "share_of_revenue_pct": 40.71,
      "insight": "Focus on retention & upsell"
    },
    {
      "cluster_id": 1,
      "n_customers":  7,
      "avg_spend": 2577.37,
      "median_spend": 2560.0,
      "avg_frequency": 23.14,
      "top_categories": "smart-tv, soundbar, hdmi-cable, tablet, stylus",
      "share_of_revenue_pct": 40.08,
      "insight": "Focus on retention & upsell"
    },
    {
      "cluster_id": 2,
      "n_customers":  2,
      "avg_spend": 4321.68,
      "median_spend": 4321.68,
      "avg_frequency": 29.0,
      "top_categories": "laptop, mouse, keyboard, monitor, gaming-pc",
      "share_of_revenue_pct": 19.20,
      "insight": "Growth-potential segment"
    }
  ]
}

Description

Transform a raw customer → cluster mapping + base features into C-level summary cards that answer: “How big is each segment, what do they buy, how valuable are they, and what should we do next?”

Business Usage

• One-click persona cards – drop cluster_profiles into Confluence, Notion, or a PDF. • Revenue skew insight – identify segments that punch above their head in revenue. • Creative brief generator – top_categories + insight = instant copy cues for marketing. • Board dashboards – feed these KPIs to leadership without exposing row-level data.

← Back to all routes