Customer Lifetime Value Prediction

Some customers spend a little once and never return, and others quietly become the accounts that carry a quarter. Customer lifetime value predicts how much a customer will spend going forward so a team can invest where the return is, set acquisition budgets against what a customer is worth, and give the accounts most likely to grow the attention that keeps them. This example makes three kinds of lifetime-value prediction: it estimates the revenue a customer will bring over the coming months, it flags the customers about to cross into high-value territory, and it forecasts how often a recently-active customer will buy again. Each one looks ahead from a customer and Kumo Engine learns the pattern from the customer’s own profile and the orders connected to that customer in the graph.

Data and relationships

The example assumes a prepared Kumo Engine graph, a matching snapshot, and these tables:

Table	Required columns	Purpose
`customers`	`customer_id` as the primary key, plus optional profile columns such as `region` and `signup_date`	The customers, and the entity every query scores.
`orders`	`order_id` as the primary key, plus `customer_id`, `order_date`, and `amount`	The purchase log. Each row is one completed order tied to a customer, and `amount` carries the total value of that order.

Connect orders.customer_id to customers.customer_id. Mark order_date as the time column of the orders table. That time column places every order in time, so each prediction is trained and scored using only the orders recorded before the point it looks ahead from. The customers table has no time column of its own, so it is a static entity: each forward-looking window is measured from the scoring time, the moment you run the prediction, rather than from anything on the customer row. Because lifetime value is a property of the customer and not of any single order, every query aggregates the orders child; a query that names a raw order column such as orders.amount for each customer is rejected, because a customer has many orders and Kumo Engine cannot reduce them to one value without an aggregation.

Every query here predicts a future window. The forward window is half-open: it excludes orders at the exact scoring time and includes orders through the end of the window. The window must look forward, so both of its day bounds are zero or positive; a window that reaches into the past is rejected for a prediction target.

Predict the revenue a customer will bring

This query estimates lifetime value directly as the money a customer will spend over the months ahead. SUM(orders.amount, 0, 180, days) adds up the value of every order a customer places over the 180 days that follow the scoring time, so the target is the customer’s forward revenue rather than a category or a flag. A customer with no orders in the window contributes 0.

from kumo.engine import PredictiveQuery
query_text = (
    "PREDICT SUM(orders.amount, 0, 180, days) "
    "FOR EACH customers.customer_id"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # regression

Flag the customers about to become high-value

Ranking by predicted revenue answers “how much,” but sometimes the decision is a yes-or-no one: which customers are about to cross the threshold that earns them a loyalty tier, a dedicated rep, or a retention offer. Comparing the same forward spend to a cutoff turns the estimate into that decision. SUM(orders.amount, 0, 180, days) > 500 labels a customer high-value when their spend over the next 180 days is set to clear 500, so the model learns to separate the accounts that will grow into that band from the ones that will not. Set the cutoff to whatever your business calls high-value.

query_text = (
    "PREDICT SUM(orders.amount, 0, 180, days) > 500 "
    "FOR EACH customers.customer_id"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # binary_classification

Forecast how often an active customer will buy again

Revenue is not the only shape of lifetime value: a subscription or replenishment business often cares about how often a customer will come back, not just how much they spend. COUNT(orders.*, 0, 180, days) counts the orders a customer will place over the next 180 days, so the model predicts purchase frequency. The trailing WHERE COUNT(orders.*, -30, 0, days) > 0 keeps the prediction on customers who ordered in the previous 30 days, because a repeat-purchase forecast is a question about active customers rather than dormant ones; it narrows the scored population to those recently-active accounts.

query_text = (
    "PREDICT COUNT(orders.*, 0, 180, days) "
    "FOR EACH customers.customer_id "
    "WHERE COUNT(orders.*, -30, 0, days) > 0"
)
query = PredictiveQuery(graph, query_text)
query.validate()
print(query.get_task_type())  # regression

Reading the predictions

The first query returns an expected revenue for each customer, which lets a team rank the book by future value, set acquisition budgets against what a customer is worth, and decide where retention spend earns its keep. The second query returns a probability that a customer will clear the high-value cutoff, which is the score to use when the action is a threshold decision such as promoting a customer into a loyalty tier or assigning an account manager. The third query returns an expected number of orders for recently-active customers, which helps a replenishment or subscription team see who is on track to keep buying and who is slowing down.

All three are estimates from past behavior, not guarantees, and each is anchored at the time you run it, so the model uses only orders recorded before that moment and never sees the spend it predicts. The 180-day forward window, the 500 high-value cutoff, and the 30-day recent-activity window are starting points; widen or narrow the window to match how far ahead you plan, move the cutoff to your own definition of high-value, and adjust the recent-activity window to your purchase cycle. Refresh the scores as new orders arrive so each ranking reflects the latest spending.