How to Build and Deploy a Customer Churn Prediction Model using Scikit-Learn and FastAPI

Customer churn (customers leaving your product or service) is one of the most expensive problems a business faces. Acquiring a new customer usually costs far more than keeping an existing one, so predicting churn early gives teams a real advantage.

In this machine learning deployment tutorial, you will build an end-to-end project: train a customer churn prediction model with Scikit-Learn, save it, and serve it as a production-ready REST API with FastAPI. By the end, you will have a model that any website, CRM or dashboard can call in real time.

What You Will Learn

• Preparing tabular customer data for machine learning
• Building a reusable Scikit-Learn Pipeline with preprocessing
• Evaluating a classification model
• Serving predictions through a FastAPI endpoint
• Containerizing the API with Docker for cloud deployment

Prerequisites

You need Python 3.10+ and basic familiarity with pandas. Install the dependencies:

pip install pandas scikit-learn fastapi uvicorn joblib

We will use the popular IBM Telco Customer Churn dataset (available on Kaggle). Save it as telco_churn.csv in your project folder.

Step 1: Load and Clean the Data

Real-world data is messy. In this dataset, TotalCharges is stored as text and contains blank values, so we convert it to numeric and drop missing rows.

# train.py
import pandas as pd

df = pd.read_csv("telco_churn.csv")

# Fix TotalCharges and drop rows that couldn't be converted
df["TotalCharges"] = pd.to_numeric(df["TotalCharges"], errors="coerce")
df = df.dropna(subset=["TotalCharges"])

# Target: 1 = churned, 0 = stayed
df["Churn"] = (df["Churn"] == "Yes").astype(int)

NUMERIC = ["tenure", "MonthlyCharges", "TotalCharges"]
CATEGORICAL = ["Contract", "InternetService", "PaymentMethod"]

X = df[NUMERIC + CATEGORICAL]
y = df["Churn"]

We keep a small, meaningful feature set so the API stays simple. Contract type and tenure are among the strongest churn signals in telecom data.

Step 2: Build a Scikit-Learn Pipeline

A Pipeline bundles preprocessing and the model into one object. This is the most important habit for ML model deployment: the exact same transformations run during training and prediction, which prevents training/serving skew.

from sklearn.compose import ColumnTransformer
from sklearn.preprocessing import StandardScaler, OneHotEncoder
from sklearn.pipeline import Pipeline
from sklearn.ensemble import RandomForestClassifier

preprocessor = ColumnTransformer([
    ("num", StandardScaler(), NUMERIC),
    ("cat", OneHotEncoder(handle_unknown="ignore"), CATEGORICAL),
])

model = Pipeline([
    ("preprocess", preprocessor),
    ("classifier", RandomForestClassifier(
        n_estimators=200,
        max_depth=8,
        class_weight="balanced",  # churn data is imbalanced
        random_state=42,
    )),
])

class_weight="balanced" matters because only about a quarter of customers churn. Without it, the model may simply predict "no churn" for everyone.

Step 3: Train, Evaluate and Save the Model

from sklearn.model_selection import train_test_split
from sklearn.metrics import classification_report, roc_auc_score
import joblib

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=42
)

model.fit(X_train, y_train)

preds = model.predict(X_test)
probs = model.predict_proba(X_test)[:, 1]

print(classification_report(y_test, preds))
print(f"ROC-AUC: {roc_auc_score(y_test, probs):.3f}")

joblib.dump(model, "churn_model.joblib")
print("Model saved to churn_model.joblib")

Run it with python train.py. Focus on recall for the churn class and ROC-AUC, not just accuracy. Missing a customer who is about to leave usually costs more than a false alarm.

Step 4: Create the FastAPI Prediction Service

FastAPI is fast, uses Python type hints, and generates interactive API documentation automatically, which makes it ideal for a Python machine learning API.

# app.py
from typing import Literal
import joblib
import pandas as pd
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(title="Customer Churn Prediction API", version="1.0")
model = joblib.load("churn_model.joblib")


class Customer(BaseModel):
    tenure: int = Field(..., ge=0, example=5)
    MonthlyCharges: float = Field(..., gt=0, example=89.5)
    TotalCharges: float = Field(..., ge=0, example=447.5)
    Contract: Literal["Month-to-month", "One year", "Two year"]
    InternetService: Literal["DSL", "Fiber optic", "No"]
    PaymentMethod: str = Field(..., example="Electronic check")


@app.get("/")
def health():
    return {"status": "ok"}


@app.post("/predict")
def predict(customer: Customer):
    data = pd.DataFrame([customer.model_dump()])
    prob = float(model.predict_proba(data)[0, 1])
    return {
        "churn_probability": round(prob, 3),
        "will_churn": prob >= 0.5,
        "risk_level": "high" if prob >= 0.7 else "medium" if prob >= 0.4 else "low",
    }

Pydantic validates every request, so bad inputs (like a negative tenure) are rejected with a clear error before they reach the model.

Step 5: Run and Test the API Locally

uvicorn app:app --reload

Open http://127.0.0.1:8000/docs to see the auto-generated Swagger UI, where you can test predictions in the browser. Or use curl:

curl -X POST http://127.0.0.1:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"tenure": 3, "MonthlyCharges": 95.0, "TotalCharges": 285.0,
       "Contract": "Month-to-month", "InternetService": "Fiber optic",
       "PaymentMethod": "Electronic check"}'

A new, month-to-month fiber customer paying by electronic check should come back as high risk.

Step 6: Deploy with Docker

Containerizing your API lets you deploy the ML model to Render, Railway, AWS, Google Cloud Run or Azure with the same setup.

# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py churn_model.joblib ./
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

# requirements.txt
pandas
scikit-learn
fastapi
uvicorn
joblib

docker build -t churn-api .
docker run -p 8000:8000 churn-api

Pin the same Scikit-Learn version you trained with, since a saved model may not load correctly in a different version. Push the image to your cloud provider of choice, and your churn model is live.

Next Steps

• Tune hyperparameters with GridSearchCV
• Try gradient boosting (XGBoost or LightGBM) for better ROC-AUC
• Add SHAP explanations so business teams understand why a customer is at risk
• Log predictions and monitor for data drift over time

Conclusion

You have built a complete customer churn prediction workflow: cleaning data, training a Scikit-Learn pipeline, evaluating it with the right metrics, and deploying it as a validated, containerized FastAPI service. This same pattern works for almost any tabular machine learning model you want to put into production.

Want to see more data science and machine learning projects like this in action? Explore my live portfolio at DataPulse, where I share end-to-end projects in Python, machine learning and deep learning.