/api/customer_clv_forecast

Header

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

Request Body Schema

horizon_months (int 1–60, required)
today (string YYYY-MM-DD, optional; defaults to server date)
customers (array, required)
       customer_id (string)
       transactions (array ≥ 1) of objects:
             date (string YYYY-MM-DD)
             amount (float ≥ 0)
             cost (float ≥ 0, optional)
     churn_date (string YYYY-MM-DD, optional)

Example Request Body

{
  "horizon_months":6,
  "today":"2025-04-24",
  "customers":[
    {
      "customer_id":"C-1001",
      "transactions":[
        {"date":"2024-01-15","amount":250,"cost":140},
        {"date":"2024-05-10","amount":480,"cost":270},
        {"date":"2024-10-12","amount":520,"cost":312},
        {"date":"2025-02-20","amount":398,"cost":210}
      ]
    },
    {
      "customer_id":"C-1002",
      "transactions":[
        {"date":"2024-03-02","amount":120,"cost":60}
      ],
      "churn_date":"2024-04-01"
    }
  ]
}

Example Response Body

{
  "horizon_months":6,
  "today":"2025-04-24",
  "customers":[
    {
      "customer_id":"C-1001",
      "transactions":[
        {"date":"2024-01-15","amount":250,"cost":140},
        {"date":"2024-05-10","amount":480,"cost":270},
        {"date":"2024-10-12","amount":520,"cost":312},
        {"date":"2025-02-20","amount":398,"cost":210}
      ]
    },
    {
      "customer_id":"C-1002",
      "transactions":[
        {"date":"2024-03-02","amount":120,"cost":60}
      ],
      "churn_date":"2024-04-01"
    }
  ]
}

Description

Derives CLV features (frequency, recency, T, monetary) Splits data time-aware, trains BG/NBD+Gamma-Gamma vs. Gradient Boosted Regression Selects lowest out-of-sample MAE as best_algorithm Forecasts dollar-value CLV (and optional txn count or avg margin) over the horizon Honors churn_date by zeroing post-churn revenue

Business Usage

High CLV: premium concierge, extended credit (▶ +15 % retention) Medium CLV: cross-sell bundles, subscription upsells (▶ +7 % margin) Low CLV: automated win-back, feedback surveys, reduce CAC bids (▶ −12 % wasted spend)

← Back to all routes