/api/customer_rfm

Header

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

Request Body Schema

bins (integer 2–10, optional; default 5)
today (string YYYY-MM-DD, optional; defaults to server date)
customers (array, required)
       customer_id (string)
       transactions (array ≥ 1) of objects with:
             date (string YYYY-MM-DD)
             amount (float ≥ 0)

Example Request Body

{
  "bins":5,
  "today":"2025-04-24",
  "customers":[
    {
      "customer_id":"C-1001",
      "transactions":[
        {"date":"2025-04-21","amount":520.55},
        {"date":"2025-03-29","amount":310.00},
        {"date":"2025-02-10","amount":398.40}
      ]
    }
  ]
}

Example Response Body

{
  "customers":[
    {
      "customer_id":"C-1001",
      "recency_days":3,
      "frequency":3,
      "monetary_total":1228.95,
      "recency_score":3,
      "frequency_score":3,
      "monetary_score":5,
      "rfm_class":"335",
      "rfm_total":11,
      "rfm_tier":"Loyal",
      "interpretation":"Loyal customer – recent purchase, frequent buying, high spend."
    }
  ],
  "thresholds":{
    "recency":[66.6,24.2,2.6,1.8],
    "frequency":[2.4,2.8,3.2,3.6],
    "monetary":[381.54,567.18,773.79,1001.37]
  }
}

Description

Computes Recency (days since last order), Frequency (order count), Monetary (spend) per customer; bins each metric into 1…bins (recency inverted), concatenates into an RFM class (e.g. “335”), sums to rfm_total and maps to tiers (Champion, Loyal, Potential, Promising, At-Risk). Returns thresholds for reproducibility.

Business Usage

• Identify Champions for VIP perks and early-access offers • Trigger win-back campaigns for At-Risk segment • Feed RFM scores into CRM or personalization engines • Monitor cohort health by shifts in rfm_tier proportions

← Back to all routes