Creatives

See also: Creatives REST API reference for request/response shapes, status codes, and error semantics.

Overview

A creative is a content variant that defines how a specific offer is rendered on a specific channel. Creatives contain the actual messaging — subject lines, headlines, body copy, images, and calls-to-action — along with personalization variables and A/B test configuration. Each creative links one offer to one channel, allowing the same offer to have different presentations across email, push, web, and other delivery mechanisms.

Field Reference

Field	Type	Required	Default	Description
`name`	string	Yes	—	Internal name for the creative (1–255 chars)
`offerId`	string	Yes	—	The offer this creative presents
`channelId`	string	Yes	—	The channel this creative is delivered through
`placementId`	string	No	`null`	Optional placement slot within the channel
`status`	enum	No	`"draft"`	Lifecycle status: `draft`, `active`, `paused`, `archived`
`templateType`	string	No	`"email_html"`	Content format template (see Template Types below)
`content`	object	No	`{}`	The actual content payload (subject, headline, body, etc.)
`personalization`	array	No	`[]`	Dynamic variable substitutions (up to 500 items)
`constraints`	object	No	`{}`	Frequency caps, cooldown periods, and delivery constraints
`abTestVariant`	string	No	`null`	A/B test variant assignment (e.g., `"control"`, `"variant_a"`, `"variant_b"`)
`weight`	integer	No	`100`	Traffic allocation weight for the variant (0–100)
`metrics`	object	No	`{}`	Performance metrics (impressions, clicks, conversions)

Template Types

Type	Channel	Description
`email_html`	Email	Full HTML email template
`email_text`	Email	Plain text email fallback
`push_notification`	Push	Title + body + optional image
`sms_text`	SMS	Plain text message (160 char recommended)
`in_app_banner`	In-App	Banner with image, headline, CTA
`in_app_modal`	In-App	Full-screen modal overlay
`in_app_card`	In-App	Card-style recommendation
`web_banner`	Web	Website banner ad
`web_overlay`	Web	Popup/overlay
`webhook_payload`	Webhook	Custom JSON payload
`whatsapp_template`	WhatsApp	WhatsApp Business template

Content Object

The content object varies by template type, but common fields include:

{
  "subject": "You're pre-approved for our Premium Card",
  "headline": "Upgrade to 3x Rewards",
  "body": "Hi {{first_name}}, based on your spending patterns...",
  "imageUrl": "https://cdn.example.com/premium-card.png",
  "ctaText": "Apply Now",
  "ctaUrl": "https://example.com/apply?offer={{offer_id}}",
  "deepLink": "myapp://offers/premium-card"
}

Field	Description
`subject`	Email subject line or notification title
`headline`	Primary heading text
`body`	Main message body (supports `{{variable}}` placeholders)
`imageUrl`	URL to hero image or thumbnail
`ctaText`	Call-to-action button text
`ctaUrl`	Click-through destination URL
`deepLink`	Mobile app deep link URI

Personalization Variables

Personalization variables inject dynamic values into the content at delivery time:

{
  "personalization": [
    {
      "variable": "first_name",
      "source": "customer.first_name",
      "fallback": "Valued Customer"
    },
    {
      "variable": "offer_rate",
      "source": "computed.personalized_rate",
      "fallback": "competitive"
    },
    {
      "variable": "offer_id",
      "source": "offer.id",
      "fallback": ""
    }
  ]
}

Field	Description
`variable`	Placeholder name used in content (referenced as `{{variable}}`)
`source`	Data source path — `customer.`, `computed.`, `offer.`, or `attributes.`
`fallback`	Default value if the source is null or unavailable

Use computed.* sources to inject dynamic computed values like personalized rates or custom pricing into creative content.

A/B Test Variants

Creatives support A/B testing by assigning each creative a variant label and traffic weight:

Variant	Description
`control`	The baseline creative (existing or default content)
`variant_a`	First test variant
`variant_b`	Second test variant

Traffic is split according to the weight field on each creative. Weights are relative — if control has weight 50 and variant_a has weight 50, traffic is split 50/50.

[
  { "name": "Email v1 - Control", "abTestVariant": "control", "weight": 50 },
  { "name": "Email v1 - New CTA", "abTestVariant": "variant_a", "weight": 30 },
  { "name": "Email v1 - Short Copy", "abTestVariant": "variant_b", "weight": 20 }
]

A/B Variant Weight Resolution

At runtime, the decision engine normalizes variant weights to select which creative a customer sees:

Collection — All active creatives for the same offer + channel are grouped.
Normalization — Weights are summed and each creative’s probability is calculated as weight / totalWeight. For the example above: control = 50/100 (50%), variant_a = 30/100 (30%), variant_b = 20/100 (20%).
Selection — A deterministic hash of the customer ID is used to pick a variant, ensuring the same customer always sees the same creative across requests.
Fallback — If no abTestVariant is set, the creative is treated as a standalone (no A/B split). If all weights are 0, each creative receives equal probability.

A/B test results are analyzed in the Algorithms module under Experiments. KaireonAI calculates statistical significance using z-tests on conversion rates.

Constraints

Field	Type	Description
`frequencyCap`	number	Maximum total impressions of this creative per customer
`cooldownHours`	number	Minimum hours between consecutive impressions to the same customer

These creative-level constraints work alongside contact policies which apply broader rules across offers, channels, and categories. Once your creatives are configured, set up decisioning gates to control which customers are eligible to see them.

Creating a Creative

Navigate to Creatives

Go to Studio > Creatives in the sidebar.

Click Create Creative

Click the + New Creative button.

Select offer and channel

Choose the offer this creative presents and the channel it will be delivered through. Optionally select a placement slot.

Choose template type

Select the appropriate template type for the channel (e.g., email_html for email, push_notification for push).

Write content

Fill in the content fields: subject, headline, body, image URL, CTA text, and CTA URL. Use {{variable}} placeholders for dynamic content.

Configure personalization

Add personalization variables that map placeholders to data sources with fallback values.

Set A/B variant (optional)

If running an experiment, assign a variant role (control, variant_a, variant_b) and traffic weight.

Set constraints (optional)

Configure frequency cap and cooldown hours for this creative.

Save

Save the creative. It is available for use in Decision Flows immediately.

API Reference

Create a Creative

POST /api/v1/creatives
Content-Type: application/json

Request body:

{
  "name": "Premium Card - Email HTML",
  "offerId": "act_abc123",
  "channelId": "ch_mktg_email",
  "placementId": "pl_header",
  "status": "active",
  "templateType": "email_html",
  "content": {
    "subject": "You're pre-approved, {{first_name}}!",
    "headline": "Upgrade to 3x Rewards",
    "body": "Based on your spending of {{monthly_spend}}, you qualify for our Premium Card at {{offer_rate}}% APR.",
    "imageUrl": "https://cdn.example.com/premium-card.png",
    "ctaText": "Apply Now",
    "ctaUrl": "https://example.com/apply?offer={{offer_id}}"
  },
  "personalization": [
    { "variable": "first_name", "source": "customer.first_name", "fallback": "Valued Customer" },
    { "variable": "monthly_spend", "source": "customer.avg_monthly_spend", "fallback": "" },
    { "variable": "offer_rate", "source": "computed.personalized_rate", "fallback": "19.99" },
    { "variable": "offer_id", "source": "offer.id", "fallback": "" }
  ],
  "abTestVariant": "control",
  "weight": 60,
  "constraints": {
    "frequencyCap": 3,
    "cooldownHours": 72
  }
}

Response (201 Created):

{
  "id": "crv_xyz789",
  "name": "Premium Card - Email HTML",
  "offerId": "act_abc123",
  "channelId": "ch_mktg_email",
  "placementId": "pl_header",
  "status": "active",
  "templateType": "email_html",
  "abTestVariant": "control",
  "weight": 60,
  "constraints": {
    "frequencyCap": 3,
    "cooldownHours": 72
  },
  "createdAt": "2026-03-10T14:30:00Z",
  "updatedAt": "2026-03-10T14:30:00Z"
}

List Creatives

GET /api/v1/creatives

Filter by offerId or channelId using query parameters.

Update a Creative

PUT /api/v1/creatives

Pass the creative id in the JSON body alongside the fields to update.

Delete a Creative

DELETE /api/v1/creatives?id=<creativeId>

Next Steps

Offers

Define the offers that creatives present to customers.

Channels

Configure the delivery mechanisms for your creatives.

Decisioning Gates

Control who is eligible to receive each offer.

Decision Flows

Build pipelines that select and rank creatives for delivery.

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Overview

Field Reference

Template Types

Content Object

Personalization Variables

A/B Test Variants

A/B Variant Weight Resolution

Constraints

Creating a Creative

API Reference

Create a Creative

List Creatives

Update a Creative

Delete a Creative

Next Steps

Offers

Channels

Decisioning Gates

Decision Flows

​Overview

​Field Reference

​Template Types

​Content Object

​Personalization Variables

​A/B Test Variants

​A/B Variant Weight Resolution

​Constraints

​Creating a Creative

​API Reference

​Create a Creative

​List Creatives

​Update a Creative

​Delete a Creative

​Next Steps

Offers

Channels

Decisioning Gates

Decision Flows

Overview

Field Reference

Template Types

Content Object

Personalization Variables

A/B Test Variants

A/B Variant Weight Resolution

Constraints

Creating a Creative

API Reference

Create a Creative

List Creatives

Update a Creative

Delete a Creative

Next Steps