Skip to main content

​
Tutorial: Starbucks NBA Pipeline

This hands-on tutorial walks you through the entire KaireonAI platform using a real Starbucks customer offers dataset from Kaggle. You’ll set up a complete NBA pipeline — from loading data to watching models learn from customer responses. What you’ll learn:
  • How offers, channels, and creatives work together
  • How qualification rules and contact policies filter decisions
  • How to run the Recommend API and interpret results
  • How to record outcomes and see models improve
  • How to read the dashboards and debug eligibility
Time: 15-20 minutes

​
Step 1: Load the Dataset

Navigate to Settings → Sample Data and click Load on the Starbucks Offers dataset.
Sample Data page showing Starbucks Offers dataset
This creates everything you need:
EntityCountWhat it is
Customers100Starbucks loyalty members with age, gender, income, membership tenure
Offers104 BOGO, 4 Discount, 2 Informational — each with different difficulty and reward
Creatives60Each offer × 6 channels = one creative per channel
Channels6Web, Email, Mobile Push, Social, Batch Email, Manual Outreach
Models3Scorecard, Bayesian, Thompson Bandit
Qualification Rules5Age gate, income gate, loyalty gate, plus offer-specific restrictions
Contact Policies5Daily cap, cooldown, post-conversion pause, weekly cap, mutual exclusion
Decision Flow1Full pipeline: inventory → qualify → contact policy → score → rank → response
Interactions500Pre-loaded interaction history so dashboards have data immediately

​
Step 2: Explore the Offers

Go to Studio → Offers. You’ll see 10 offers organized into 3 categories:
Offers page showing 10 Starbucks offers

​
Acquisition (BOGO Offers)

OfferMin SpendPriorityTarget
BOGO — 5 Day Easy$580New customers, low barrier
BOGO — 7 Day Medium$1075Regular visitors
BOGO — 5 Day Hard$2070High-value customers (income ≥ $70K)
BOGO — 7 Day ExtraNone65Lapsed customer re-engagement

​
Retention (Discount Offers)

OfferMin SpendPriorityTarget
Discount — 10 Day Low$785Price-sensitive, high volume
Discount — 7 Day Medium$1080Mid-tier retention
Discount — 10 Day High$2075Loyal customers aged 35+
Discount — 5 Day Quick$570Urgency / immediate visits

​
Engagement (Informational)

OfferPriorityPurpose
Info — 3 Day Brief60Seasonal product awareness
Info — 4 Day Extended55Product launch campaigns
Notice: Each offer has 4 creatives (one per channel) with channel-appropriate content — email has subject lines, mobile has deep links, social has hashtags.

​
Step 3: Understand the Rules

​
Qualification Rules (who can receive offers)

Go to Studio → Qualification Rules to see all 5 rules:
RuleWhat it checksEffect
Min Age 18age ≥ 18Legal requirement — blocks minors
Min Income $30kincome ≥ $30,000Ensures spending power
Loyalty Members Onlymembership_days ≥ 30Only established members
Premium BOGO Gateincome ≥ $70k on BOGO Hard onlyTargets high-value for premium offers
Senior Discount Gateage ≥ 35 on Discount High onlyMature customers with habits

​
Contact Policies (how often / when)

Go to Studio → Contact Policies:
PolicyWhat it does
Max 3 per DayNo more than 3 offers per customer per day
24hr Same-Offer CooldownDon’t repeat the same offer within 24 hours
48hr Post-Conversion CooldownAfter conversion, pause 48 hours
Max 10 per WeekWeekly global cap across all channels
BOGO vs Discount ExclusionDon’t show both types in same session

​
Step 4: Look Up a Customer

Go to Data → Customer Viewer and search for SBX-000042.
Customer Viewer showing SBX-000042 profile and eligibility
You’ll see:
  • Profile card with demographics (age, income, gender, membership days)
  • Eligibility tab showing which of the 10 offers this customer qualifies for
  • Pipeline funnel showing how many candidates survive each stage
  • Rule detail — expand any offer to see exactly which rules passed/failed
Try these customers to see different results:
CustomerAgeIncomeWhat happens
SBX-000042VariesVariesSee the full eligibility breakdown
SBX-00000052$98KQualifies for everything — high-value VIP
SBX-00001018$67KJust barely passes age gate
SBX-00050033$77KBlocked from Discount High (age < 35)

​
Step 5: Run a Recommendation

​
From the API Explorer

Go to Settings → API Explorer and try: 
POST /api/v1/recommend
{
  "customerId": "SBX-000042",
  "decisionFlowKey": "starbucks-decision-pipeline",
  "limit": 5
}
The response shows:
  • decisions — the top 5 offers ranked by score
  • meta — pipeline trace (totalCandidates → afterQualification → afterContactPolicy → count)
  • recommendationId — save this for the next step

​
From curl

curl -X POST http://localhost:3000/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": "SBX-000042",
    "decisionFlowKey": "starbucks-decision-pipeline",
    "limit": 5
  }'

​
Step 6: Record an Outcome

When a customer responds to a recommendation, record it: 
POST /api/v1/respond
{
  "customerId": "SBX-000042",
  "recommendationId": "THE_ID_FROM_STEP_5",
  "rank": 1,
  "outcome": "click"
}
Important: Include the Idempotency-Key header to prevent double-counting. Try recording different outcomes:
  • "click" — customer clicked the offer
  • "accept" — customer accepted/redeemed
  • "dismiss" — customer dismissed it
  • "convert" — customer completed a purchase
After recording a positive outcome, try recommending again — you’ll see the 48hr post-conversion cooldown kick in, suppressing offers temporarily.

​
Step 7: Check the Dashboards

​
Business Dashboard

Go to Dashboards → Business. You’ll see:
Business Dashboard with Starbucks metrics
  • Channel Effectiveness donut chart — which channels drive the most engagement
  • Offer Performance bars — which offers get the most conversions
  • Daily Trend line chart — impression and conversion volume over time
Use the period filter (Today / 7d / 14d / 30d / 90d) to adjust the time window.

​
Operations Dashboard

Go to Dashboards → Operations:
  • Acceptance Rate by Offer — see which offers customers actually respond to
  • Total Decisions — how many recommendations have been made

​
Model Health

Go to Dashboards → Model Health:
  • Select different models from the dropdown to see AUC trends
  • Score Distribution — see how propensity scores are distributed
  • Use the View buttons (All / By Channel / By Offer / By Category) to break down scores

​
Step 8: Explore the Decision Flow

Go to Studio → Decision Flows and click on Full Decision Pipeline.
Decision Flows page showing Starbucks pipeline
This is the heart of the system — a composable pipeline that processes every recommendation request:
  1. Inventory — loads all active offers and their creatives (40 candidates)
  2. Qualification — applies 5 rules, drops ineligible candidates
  3. Contact Policy — applies 5 suppression policies
  4. Score — runs the selected ML model (Scorecard, Bayesian, or Thompson Bandit)
  5. Rank — selects the top N candidates by score
  6. Response — formats the final recommendation
Each stage narrows the candidates. In the Customer Viewer’s Eligibility tab, you can see exactly how many survive each stage.

​
What’s Next?

Now that you’ve explored the Starbucks pipeline, try:
  • Creating your own offer — Studio → Offers → + New Offer
  • Adding a qualification rule — target a specific customer segment
  • Setting up an experiment — Algorithms → Experiments to A/B test models
  • Building a journey — Studio → Journeys for multi-step customer flows
  • Connecting your own data — Data → Connectors to bring in real customer data
For the full API reference, visit docs.kaireonai.com/api-reference.