Skip to main content

pcLTV (Transactional) — Reference

The Predicted Customer Lifetime Value (pcLTV) model estimates the future economic value a customer will generate over a chosen horizon. The transactional variant leverages purchase transactions (frequency, value, recency) enriched with user attributes and behavioural data. It is a predictive model.

Input data: see AI Model Data Requirements → pcLTV for the transaction event table, basket JSON format, and minimum volumes.

Key concepts​

  • Transactions as events — the model requires an event table of transactions, one row per purchase, with user, date, monetary value, and basket composition.
  • User enrichment — user-level attributes (demographics, segmentation, engagement) can be joined to improve predictions.
  • Output — one row per user with the predicted LTV for the configured horizon, linked to bpp_user_id.

JSON configuration reference​

FieldTypeDescriptionExample / best practice
clientSTRINGClient/project identifier."ExampleClient"
data_src.regionSTRINGCloud region (auto-populated)."europe-west8"
dataset_idSTRINGBigQuery dataset with input tables (auto-populated)."bpp_tables"
project_idSTRINGGCP project ID (auto-populated)."audience-ai-dev"
user_id_columnSTRINGUser identifier column."bpp_user_id"
data_time_rangeINTHistorical window in days used for training.90
output_table_idSTRINGOutput prediction table name (auto-populated)."pcltv_bpp"
source_table_idSTRINGTransaction event table (a *_bpp table)."event_transactions_bpp"
behavioural_dataOBJECTOptional enrichment joined from a user/lead table.Join CRM/lead data to transactions
extra_src_tablesARRAYOptional extra user-level features from other tables.gender, client_type
output_dataset_idSTRINGDataset for the output table (auto-populated)."bpp_tables"
product_id_columnSTRINGField with the product or product category."products"
monetary_value_columnSTRINGField with the transaction monetary value."total_price"
transaction_id_columnSTRINGUnique transaction ID. Recommended for reconciliation & value bidding."transaction_id"
product_id_json_configOBJECTBasket JSON parsing config (price, quantity, category).See example
transaction_date_columnSTRINGTransaction timestamp column (UTC)."transaction_date"
transaction_status_columnSTRINGField indicating transaction state."transaction_status"
transaction_status_allowed_valuesARRAYStatuses to include.["CONFIRMED"]

Example configuration​

{
  "client": "ExampleClient",
  "data_src": {
    "region": "europe-west8",
    "dataset_id": "bpp_tables",
    "project_id": "example-project",
    "user_id_column": "bpp_user_id",
    "data_time_range": 90,
    "output_table_id": "pcltv_bpp",
    "source_table_id": "event_transactions_bpp",
    "behavioural_data": {
      "table_id": "crm_leads_bpp",
      "include_columns": ["Lead_Role", "Lead_Source", "Lead_State", "Lead_Segment"],
      "join_column_behavioural": "bpp_user_id",
      "join_column_transactions": "bpp_user_id"
    },
    "extra_src_tables": [
      { "event_transactions_bpp": ["gender", "client_type"] }
    ],
    "output_dataset_id": "bpp_tables",
    "product_id_column": "products",
    "monetary_value_column": "total_price",
    "transaction_id_column": "transaction_id",
    "product_id_json_config": {
      "price": "product_price",
      "quantity": "quantity",
      "product_id": "product_category",
      "category_level_max": null,
      "category_separator": "||",
      "product_id_is_category": "True"
    },
    "transaction_date_column": "transaction_date",
    "transaction_status_column": "transaction_status",
    "transaction_status_allowed_values": ["CONFIRMED"]
  }
}

Feature engineering suggestions​

The more relevant features you provide, the more accurate pcLTV predictions become. Examples by industry:

E-commerce / Retail — average basket size, distinct categories purchased, interpurchase time, checkout speed, distinct devices/browsers, geographic diversity.

Subscription (SaaS / Media) — contract length, login frequency, time since last login, distinct devices, support-ticket ratio, premium-feature usage.

B2B / CRM-driven — lead source & campaign, company size & sector, contacts per account, average deal-cycle length, event participation, nurturing engagement.

Travel / Hospitality — average booking value, booking lead time, destinations booked, seasonality, group size, distinct payment methods.

Finance / Insurance — policy type distribution, claim frequency & value, payment timeliness, renewal rate, average premium, cross-sold products.

Best practices​

  • Transaction ID — not required for modelling, but strongly recommended for reconciliation in value-based bidding.
  • Basket JSON — follow the structure strictly; product_id, price, and quantity must always be present.
  • Time window — provide at least 3× the prediction horizon (e.g. 9 months of history to predict 3 months).
  • Data quality — exclude cancelled/refunded orders via transaction_status_allowed_values.
  • User enrichment — aggregate behavioural data into user tables for easier joins (Fields Builder helps here).
Last updated on