Skip to main content

​
Overview

This walkthrough takes you from an empty Kaireon instance to a working decisioning setup. By the end, you will have categories, offers, channels, creatives, a decision flow, and will have called the Recommend and Respond APIs.
This guide assumes you have completed the Quickstart and have Kaireon running locally or on the playground at https://playground.kaireonai.com.

​
Step 1: Create a Business Hierarchy

Start by organizing your offers into a logical hierarchy.
1

Create a category

Go to Studio > Business Hierarchy and click + New Category.
FieldValue
NameCredit Cards
DescriptionConsumer credit card products
Iconcredit-card
Color#6366f1
Add custom fields:
  • annual_fee (number, required)
  • rewards_multiplier (number, required)
  • personalized_rate (computed, formula: 19.99 - customer.loyalty_score * 0.05, output type: decimal)
2

Create a sub-category

With the “Credit Cards” category selected, click + Sub-Category.
FieldValue
NamePremium Cards
DescriptionHigh-rewards premium card products

​
Step 2: Create Offers

Create offers that represent the products you want to recommend.
1

Create your first offer

Go to Studio > Offers and click + New Offer.
FieldValue
NamePlatinum Rewards Card
Short DescriptionEarn 3x points on all purchases
CategoryCredit Cards
Sub-CategoryPremium Cards
PriorityHigh
StatusDraft
Custom fields:
  • annual_fee: 95
  • rewards_multiplier: 3
2

Create a second offer

Create another offer for variety:
FieldValue
NameCash Back Card
Short Description2% cash back on everything
CategoryCredit Cards
Sub-CategoryPremium Cards
PriorityMedium
Custom fields:
  • annual_fee: 0
  • rewards_multiplier: 2
3

Activate both offers

Set both offers’ status to Active so they are eligible for decisioning.

​
Step 3: Create a Channel

Define how recommendations will be delivered.
1

Create an email channel

Go to Studio > Channels and click + New Channel.
FieldValue
NameMarketing Email
Typeemail
Delivery ModeAPI
Impression TrackingExplicit
Add a placement:
  • Name: hero_offer
  • Description: “Primary offer slot in email header”

​
Step 4: Create Creatives

Create content variants that define how each offer looks on the channel.
1

Create a creative for the Platinum card

Go to Studio > Creatives and click + New Creative.
FieldValue
NamePlatinum Card - Email
OfferPlatinum Rewards Card
ChannelMarketing Email
Template Typeemail_html
Content:
{
  "subject": "You're invited, {{first_name}} - Earn 3x Rewards",
  "headline": "Platinum Rewards Card",
  "body": "Start earning 3x points on every purchase with a personalized rate of {{offer_rate}}% APR.",
  "ctaText": "Apply Now",
  "ctaUrl": "https://example.com/apply/platinum"
}
Personalization:
  • first_name -> customer.first_name, fallback: “Valued Customer”
  • offer_rate -> computed.personalized_rate, fallback: “19.99”
2

Create a creative for the Cash Back card

Repeat for the Cash Back Card with appropriate content.

​
Step 5: Create a Decision Flow

Build the pipeline that selects and ranks offers.
1

Create a new flow

Go to Studio > Decision Flows and click + New Flow.
FieldValue
NameCredit Card Recommendations
DescriptionSelects the best credit card for each customer
2

Add an Enrich stage

Add an Enrich stage to load customer data:
  • Schema: customer_profile
  • Key field: customer_id
  • Fields: first_name, loyalty_score, credit_score, income
3

Add a Compute stage

Add a Compute stage to evaluate the personalized_rate computed field for each candidate offer.
4

Add a Filter stage

Add a Filter stage with qualification mode set to Apply All.
5

Add a Score stage

Add a Score stage using the scorecard engine.
6

Add a Rank stage

Add a Rank stage to produce the final ordered list. Set max offers to 2.
7

Save and activate

Save the flow and set status to Active.

​
Step 6: Call the Recommend API

Now test your setup by calling the Recommend API. 
curl -X POST https://localhost:3000/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: your-tenant-id" \
  -d '{
    "customerId": "cust_12345",
    "channelId": "ch_email",
    "decisionFlowId": "df_credit_cards",
    "maxOffers": 2,
    "attributes": {
      "tier": "gold",
      "source": "campaign_q1"
    }
  }'
Expected response: 
{
  "customerId": "cust_12345",
  "recommendations": [
    {
      "offerId": "act_platinum_cc",
      "offerName": "Platinum Rewards Card",
      "rank": 1,
      "score": 0.89,
      "channelId": "ch_email",
      "creativeId": "treat_platinum_email",
      "personalization": {
        "personalized_rate": 17.49
      }
    },
    {
      "offerId": "act_cashback",
      "offerName": "Cash Back Card",
      "rank": 2,
      "score": 0.74,
      "channelId": "ch_email",
      "creativeId": "treat_cashback_email",
      "personalization": {
        "personalized_rate": 18.24
      }
    }
  ],
  "decisionFlowId": "df_credit_cards",
  "traceId": "trace_abc123"
}

​
Step 7: Record Outcomes with the Respond API

After the customer interacts with a recommendation, record the outcome. 
curl -X POST https://localhost:3000/api/v1/respond \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: your-tenant-id" \
  -d '{
    "customerId": "cust_12345",
    "offerId": "act_platinum_cc",
    "channelId": "ch_email",
    "outcomeType": "impression",
    "traceId": "trace_abc123"
  }'
Response (200 OK): 
{
  "id": "int_xyz789",
  "customerId": "cust_12345",
  "offerId": "act_platinum_cc",
  "outcomeType": "conversion",
  "recordedAt": "2026-03-10T15:45:00Z"
}

​
What’s Next?

Computed Values

Learn how to define formula-based fields for per-customer personalization.

API Tutorial

Deep dive into the Recommend and Respond APIs with advanced features.

Contact Policies

Set up frequency caps and suppression rules.

Behavioral Metrics

Create computed metrics from interaction history.