/api/customer_loyalty

Header

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

Request Body Schema

weights (object of five floats 0–1, sum = 1; optional, defaults = equal)
purchase_total, visit_frequency, avg_ticket, product_diversity, recency_days
customers (array of objects, required)
customer_id (string)
features (object with keys purchase_total, visit_frequency, avg_ticket, product_diversity, recency_days; all numeric)

Example Request Body

{
  "weights":{
    "purchase_total":0.25,
    "visit_frequency":0.30,
    "avg_ticket":0.10,
    "product_diversity":0.15,
    "recency_days":0.20
  },
  "customers":[
    {
      "customer_id":"C-1001",
      "features":{
        "purchase_total":17850.55,
        "visit_frequency":62,
        "avg_ticket":287.27,
        "product_diversity":36,
        "recency_days":3
      }
    }
  ]
}

Example Response Body

{
  "customers":[
    {
      "customer_id":"C-1001",
      "loyalty_score":1.0,
      "segment":"Platinum"
    }
  ],
  "summary":{
    "mean_score":0.6013,
    "median_score":0.7026,
    "top_decile_threshold":0.9611,
    "segment_counts":{
      "Platinum":2,
      "Silver":1,
      "At-Risk":1
    }
  }
}

Description

Computes a weighted, min–max–scaled loyalty index per customer and assigns tier labels (Platinum, Gold, Silver, Bronze, At-Risk) based on default thresholds.

Business Usage

• Drive CRM tiers and dynamic campaigns by loyalty_score • Prioritize perks for top decile (score ≥ top_decile_threshold) • Trigger win-back flows for At-Risk segment • Monitor cohort health via summary.mean_score on dashboards

← Back to all routes