Customer Lifetime Value (CLV) Forecasting Engine: A Serverless ML Microservice

The Context & Objective

In e-commerce and retail, allocating marketing budgets based purely on historical transactions is a lagging indicator. To optimize Customer Acquisition Cost (CAC), businesses need to predict the future purchasing behavior of a user. The objective of this project was to build a predictive Customer Lifetime Value (CLV) engine and deploy it as an independent, highly scalable serverless microservice capable of returning instant financial projections.

Technical Architecture & Engineering

To balance computational efficiency with accurate forecasting, I separated the model training pipeline from the production inference API:

Statistical Modeling (BTYD Framework): Instead of standard regression, I implemented the industry-standard “Buy-Til-You-Die” statistical models using the lifetimes library. I trained a Beta-Geometric/Negative Binomial Distribution (BG/NBD) model to predict the expected number of future purchases and the probability that a customer is still “alive.” I paired this with a Gamma-Gamma model to estimate the expected average profit per transaction.
Serverless Inference API: The trained models were serialized and wrapped in a high-performance FastAPI application.
Cloud Deployment (Vercel): The API is deployed as a serverless function on Vercel. To accommodate Vercel’s strict memory and timeout constraints, the architecture is engineered to dynamically load the pre-trained .pkl model weights into memory during the function’s cold start, enabling sub-second inference times for incoming REST requests.

Business Impact

Optimized Ad Spend: By projecting the 30-day and 90-day future value of specific customer cohorts, marketing teams can definitively cap acquisition costs to ensure profitability.
Dynamic Segmentation: Allows automated platforms to instantly route “high-future-value” customers to VIP retention workflows, even if their historical spend currently looks average.
API-First Integration: Because it is built as a REST API, this engine can be seamlessly integrated directly into existing web storefronts, CRMs, or Power BI streaming datasets.

Live API Demo & Documentation

The inference engine is live and actively processing requests. You can test the endpoint by sending a POST request with an RFM (Recency, Frequency, Monetary) profile to the cloud API.

Live Endpoint URL: https://clvapi.giftwarieta.com.ng/predict
Sample JSON Payload:

{
  "frequency": 5.0,
  "recency": 200.0,
  "T": 300.0,
  "monetary_value": 45.50
}

Tech Stack & Methodologies

Machine Learning: Python, Scikit-Learn, BG/NBD & Gamma-Gamma Models (lifetimes)
Software Engineering: FastAPI, Pydantic (Data Validation), REST API Architecture
Deployment & Cloud: Serverless Functions, Git