/api/customer_clv_features

Header

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

Request Body Schema

today (string YYYY-MM-DD, optional; defaults to server date UTC)
customers (array of objects, required)
        customer_id (string)
        transactions (array ≥ 1) of:
                date (string YYYY-MM-DD)
                amount (float ≥ 0)
                cost (float ≥ 0, optional—if omitted, monetary_value=average revenue)

Example Request Body

{
  "today":"2025-04-24",
  "customers":[
    {
      "customer_id":"C-1001",
      "transactions":[
        {"date":"2024-10-12","amount":520.55,"cost":312.33},
        {"date":"2025-02-20","amount":398.40,"cost":210.00}
      ]
    }
  ]
}

Example Response Body

{
  "customers":[
    {
      "customer_id":"C-1001",
      "frequency":1,
      "recency":131.0,
      "T":194.0,
      "monetary_value":188.40,
      "churned":false,
      "clv_potential_tier":"High",
      "interpretation":"C-1001 has 1 repeat purchase, 131 days between first & last, Avg margin/order: $188. Tier: High.",
      "explanations":{
        "frequency":"1 repeat purchase",
        "recency":"131 days between first & last buy",
        "T":"194 days observed",
        "monetary_value":"Avg margin/order: $188.40",
        "churned":"False (no churn)",
        "clv_potential_tier":"High potential"
      }
    }
  ]
}

Description

Extracts BG/NBD + Gamma-Gamma inputs per customer: frequency (repeat orders), recency (days between first & last), T (age in days), and average monetary_value. Optionally flags churned and assigns a clv_potential_tier (High/Medium/Low).

Business Usage

• Pipe directly into /api/customer_clv_forecast for 6/12/36-month CLV predictions. • Optimize CAC bids by targeting High-tier look-alikes and throttling Low-tier. • Combine monetary_value with RFM tiers for “High-Margin Champions.” • Feed recency/frequency into churn models or CRM workflows.

← Back to all routes