Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Tutorial: Cross-Sell

This tutorial walks through a cross-sell flow that recommends a second product to existing customers. The system needs to know what each customer already owns, what they’re likely to buy next, and how much incremental revenue each candidate offer brings (not just what they’d buy anyway). Business scenario: a bank’s existing-customer base owns one or more of: checking, savings, credit card, mortgage, brokerage. Marketing wants to recommend the next product per customer — and avoid recommending one they already have, one their tier doesn’t qualify for, or one they’d convert on without prompting (sleeping dogs). What you’ll build:
  • A Customer schema that tracks current product holdings
  • 4 cross-sell offers with eligibility tied to existing holdings
  • A flow that uses uplift modeling (T-learner) so the system optimizes incremental revenue, not raw conversion
  • Channel-aware ranking so the right offer surfaces on the right surface (email vs. in-app vs. branch)
Prerequisites: A running KaireonAI instance, an admin API key. Time: 25–30 minutes.

​
1. Define the schema with product holdings

curl -X POST $BASE/api/v1/schemas \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "name": "Customer",
    "fields": [
      { "name": "tenureMonths", "type": "integer" },
      { "name": "tier", "type": "string" },
      { "name": "hasChecking", "type": "boolean" },
      { "name": "hasSavings", "type": "boolean" },
      { "name": "hasCreditCard", "type": "boolean" },
      { "name": "hasMortgage", "type": "boolean" },
      { "name": "hasBrokerage", "type": "boolean" },
      { "name": "avgMonthlyBalance", "type": "decimal" }
    ]
  }'
These boolean holding fields are the gate — qualification rules will use them to exclude offers the customer already owns.

​
2. Define cross-sell offers with holding-aware qualification

# Savings: only for checking-only customers
curl -X POST $BASE/api/v1/offers -d '{
  "name": "High-yield savings",
  "category": "Cross-Sell",
  "priority": 70,
  "businessValue": 40,
  "qualificationRules": [
    { "field": "hasChecking", "op": "==", "value": true },
    { "field": "hasSavings", "op": "==", "value": false }
  ]
}'

# Credit card: not for customers who already have one
curl -X POST $BASE/api/v1/offers -d '{
  "name": "Rewards credit card",
  "category": "Cross-Sell",
  "priority": 80,
  "businessValue": 90,
  "qualificationRules": [
    { "field": "hasCreditCard", "op": "==", "value": false },
    { "field": "tenureMonths", "op": ">=", "value": 6 }
  ]
}'

# Brokerage: only for premium-tier with significant balance
curl -X POST $BASE/api/v1/offers -d '{
  "name": "Wealth-management account",
  "category": "Cross-Sell",
  "priority": 95,
  "businessValue": 250,
  "qualificationRules": [
    { "field": "hasBrokerage", "op": "==", "value": false },
    { "field": "tier", "op": "in", "value": ["premium", "private"] },
    { "field": "avgMonthlyBalance", "op": ">=", "value": 50000 }
  ]
}'

# Mortgage: only for non-mortgage holders with strong tenure
curl -X POST $BASE/api/v1/offers -d '{
  "name": "Mortgage pre-approval",
  "category": "Cross-Sell",
  "priority": 90,
  "businessValue": 500,
  "qualificationRules": [
    { "field": "hasMortgage", "op": "==", "value": false },
    { "field": "tenureMonths", "op": ">=", "value": 24 }
  ]
}'
The eligibility rules are the safety net. Even if the propensity model says “this customer would love a credit card”, the rule hasCreditCard == false keeps the platform honest.

​
3. Configure the cross-channel routing

Cross-sell often runs across email, in-app, and (for high-value offers) branch. The Channel entity captures each. 
curl -X POST $BASE/api/v1/channels -d '{ "name": "email", "couplingMode": "partial" }'
curl -X POST $BASE/api/v1/channels -d '{ "name": "in_app",  "couplingMode": "partial" }'
curl -X POST $BASE/api/v1/channels -d '{ "name": "branch",  "couplingMode": "partial" }'
partial coupling means a placement that can’t be filled doesn’t cascade-empty its sibling placements in the same channel — useful when the cross-sell flow runs at the channel level and you want each placement decided independently.

​
4. Wire the cross-sell decision flow

curl -X POST $BASE/api/v1/decision-flows -d '{
  "name": "Cross-Sell",
  "config": {
    "nodes": [
      { "id": "inv", "type": "inventory", "config": { "category": "Cross-Sell" } },
      { "id": "enr", "type": "enrich", "config": { "schema": "Customer" } },
      { "id": "qual", "type": "qualify" },
      { "id": "cp", "type": "contact_policy" },
      { "id": "score", "type": "score", "config": { "method": "propensity", "model": "bayesian" } },
      { "id": "rank", "type": "rank", "config": {
          "profile": "uplift-aware",
          "weights": { "Wp": 0.30, "Wr": 0.15, "Wi": 0.25, "We": 0.10, "Wu": 0.20 }
      }},
      { "id": "out", "type": "response" }
    ]
  }
}'
The key is Wu: 0.20 in the ranking weights. This activates the uplift dimension of PRIE-U — the platform looks up the per-customer CATE estimate and downweights offers the customer would have converted on anyway (sure things) while boosting offers that move the needle (persuadable).

​
5. Train the uplift model

PRIE-U needs an uplift signal. The platform ships T-learner and X-learner endpoints — see Uplift Modeling for the full math. For each candidate offer: 
curl -X POST $BASE/api/v1/algorithms/uplift/train \
  -H "Content-Type: application/json" \
  -d '{
    "offerId": "off_credit_card",
    "method": "t_learner",
    "treatmentArm": "exposed",
    "controlArm": "holdout",
    "windowDays": 90
  }'
The training pulls decision_traces + interactions from the last 90 days, fits two propensity models (one on treated, one on holdout), and stores per-customer CATE estimates that the runtime can look up at decision time. You need at least 30 days of decision.made.v1 + interaction.recorded.v1 events with a holdout group before the uplift signal becomes reliable.

​
6. Get a recommendation

For a 36-month-tenure premium customer with no credit card: 
curl -X POST $BASE/api/v1/recommend -d '{
  "customerId": "cust_42",
  "channel": "in_app",
  "flow": "Cross-Sell"
}'
Sample response: 
{
  "decisions": [
    {
      "offerId": "off_credit_card",
      "name": "Rewards credit card",
      "score": 0.79,
      "rank": 1,
      "trace": {
        "qualified": true,
        "prie": { "P": 0.62, "R": 0.85, "I": 0.65, "E": 0.80, "U": 0.71 },
        "upliftSegment": "persuadable",
        "cate": 0.18
      }
    },
    {
      "offerId": "off_savings",
      "name": "High-yield savings",
      "score": 0.58,
      "rank": 2,
      "trace": {
        "upliftSegment": "sure_thing",
        "cate": -0.04
      }
    }
  ]
}
Notice that savings is rank-2, not rank-1, even though its raw propensity is reasonable. The CATE estimate is negative (-0.04) — the customer would have opened a savings account anyway, so the platform’s uplift dimension suppresses it in favor of the credit card where the offer actually moves the needle. This is the cross-sell game: don’t pay attribution dollars for conversions you’d get for free.

​
7. The four uplift segments

The platform classifies every (customer × offer) pair into one of four buckets via the CATE estimate:
SegmentCATEBehavior
Persuadable> +0.05Offer moves the needle; surface it
Sure thing-0.05 to +0.05Will convert anyway; deprioritize
Lost cause< -0.05, low baseWon’t convert; suppress
Sleeping dog< -0.05, high baseWould have converted but offer backfires; suppress strongly
Sleeping dogs are the dangerous one. A retention discount sent to a customer who would have renewed at full price loses you money on both sides — the conversion you would have gotten + the lost margin.

​
8. What’s next

  • Layer contact frequency — add a customer_total_cap contact policy (max 4 contacts per customer per month across cross-sell + other categories) so the program doesn’t crowd out service messages.
  • Add an A/B holdout — run a 10% holdout that gets no cross-sell. The platform’s uplift z-test computes the incremental revenue, not just the conversion rate.
  • Per-channel ranking — the same offer at rank-1 on email may not be rank-1 on in-app. Channel preferences live in the Channel entity and PRIE’s R dimension picks the surface match.
  • Multi-step sequencing — for high-value cross-sells like mortgages, wire a multi-step Journey so the email lead is followed (after qualifying response) by a branch appointment offer.
See Churn Prevention for the retention scenario, Industry Templates for ready-made starter kits, or Uplift Modeling for the CATE math.