Skip to main content

​
Overview

An offer (also called an action) is the fundamental unit of Kaireon’s decisioning engine. It represents something you can recommend to a customer — a product, promotion, message, or next-best-action. Offers belong to a business hierarchy (category and sub-category) and carry configuration for priority, budget, scheduling, and qualification.

​
Key Fields

FieldTypeDescription
namestringDisplay name of the offer
shortDescstringBrief description shown in recommendations
categoryIdstringParent category ID
subCategoryIdstringParent sub-category ID
priorityenumExecution priority level
mandatorybooleanIf true, bypasses ALL rules (qualification, contact policies, budget)
statusenumLifecycle state of the offer
tagsstring[]Freeform tags for filtering and grouping
customFieldsobjectKey-value pairs defined by the parent category schema

​
Priority Levels

Priority determines how aggressively an offer competes in arbitration. Higher priority offers receive a scoring boost during the ranking stage.
LevelScoreUse Case
Critical90Regulatory requirements, compliance notices
High70Strategic initiatives, time-sensitive promotions
Medium50Standard product recommendations
Low25Exploratory or filler offers
Setting an offer as mandatory causes it to bypass ALL qualification rules, contact policies, and budget checks. Use this only for regulatory or compliance-critical communications.

​
Status Lifecycle

Offers progress through a defined lifecycle: 
draft → active → paused → archived
StatusDescription
draftBeing configured; not available for decisioning
activeLive and eligible for recommendation
pausedTemporarily removed from decisioning; can be reactivated
archivedPermanently retired; preserved for reporting history
Only offers with active status are considered by decision flows. Draft and paused offers are excluded from candidate selection.

​
Qualification Config

Control which customers are eligible to receive this offer:
FieldTypeDescription
propensityThresholdnumber (0-1)Minimum model score required
recencynumber (days)Minimum days since customer last received this offer
requiredSegmentsstring[]Customer must belong to all listed segments
modelReferencestringScoring model to use for propensity evaluation

​
Budget Config

Set spend and impression limits to control offer distribution:
FieldTypeDescription
maxImpressionsnumberTotal lifetime impression cap
maxDailyBudgetnumberMaximum spend per day
costPerActionnumberCost attributed per impression or conversion
When an offer’s budget is exhausted, it is automatically excluded from decisioning until the budget resets or is increased. The budget_exhausted contact policy rule type can also enforce this.

​
Schedule Config

Restrict when an offer is eligible for recommendation:
FieldTypeDescription
startDateISO 8601 dateEarliest date the offer can be recommended
endDateISO 8601 dateLatest date the offer can be recommended
daysOfWeeknumber[]Allowed days (0=Sunday through 6=Saturday)
timeWindowobjectStart and end time within allowed days

​
Creating an Offer

1

Navigate to Offers

Go to Studio > Offers in the sidebar.
2

Click Create Offer

Click the + New Offer button in the top-right corner.
3

Fill in basic info

Enter the offer name, description, and select a category and sub-category from the business hierarchy.
4

Set priority and status

Choose the priority level and set the initial status to draft.
5

Configure qualification (optional)

Set propensity thresholds, required segments, and recency rules.
6

Configure budget (optional)

Set impression caps, daily budget limits, and cost-per-action.
7

Configure schedule (optional)

Set start/end dates, allowed days of the week, and time windows.
8

Fill custom fields

Populate any custom fields defined by the parent category, including computed field formulas.
9

Save and activate

Save the offer as a draft, review the configuration, then set the status to active when ready.

​
API Reference

​
Create an Offer

POST /api/v1/actions
Content-Type: application/json
Request body: 
{
  "name": "Premium Credit Card Upgrade",
  "shortDesc": "Upgrade to our premium rewards card with 3x points",
  "categoryId": "cat_credit_cards",
  "subCategoryId": "sub_premium",
  "priority": "high",
  "mandatory": false,
  "status": "draft",
  "tags": ["rewards", "upgrade", "q1-campaign"],
  "qualification": {
    "propensityThreshold": 0.65,
    "recency": 30,
    "requiredSegments": ["high_value", "credit_eligible"],
    "modelReference": "model_propensity_cc_v3"
  },
  "budget": {
    "maxImpressions": 50000,
    "maxDailyBudget": 2500.00,
    "costPerAction": 1.50
  },
  "schedule": {
    "startDate": "2026-03-15T00:00:00Z",
    "endDate": "2026-06-15T23:59:59Z",
    "daysOfWeek": [1, 2, 3, 4, 5],
    "timeWindow": {
      "start": "08:00",
      "end": "20:00"
    }
  },
  "customFields": {
    "base_rate": 19.99,
    "annual_fee": 95,
    "rewards_multiplier": 3
  }
}
Response (201 Created): 
{
  "id": "act_abc123",
  "name": "Premium Credit Card Upgrade",
  "shortDesc": "Upgrade to our premium rewards card with 3x points",
  "categoryId": "cat_credit_cards",
  "subCategoryId": "sub_premium",
  "priority": "high",
  "mandatory": false,
  "status": "draft",
  "tags": ["rewards", "upgrade", "q1-campaign"],
  "createdAt": "2026-03-10T14:30:00Z",
  "updatedAt": "2026-03-10T14:30:00Z"
}

​
List Offers

GET /api/v1/actions
Returns all offers for the current tenant, with optional query parameters for filtering by status, categoryId, and tags.

​
Update an Offer

PUT /api/v1/actions/:id
Content-Type: application/json
Accepts the same body as the create endpoint. Only provided fields are updated.

​
Delete an Offer

DELETE /api/v1/actions/:id
Deleting an offer removes it permanently. If the offer has historical interaction data, consider archiving it instead to preserve reporting integrity.