Frequency caps

​

What this solves

1. “Don’t over-contact this customer on a given offer/channel.” A per-day cap on how often one offer is shown.
2. “Cap total touches to a customer,” or “cap a whole category.” These need different rule types — see the important note below.

​

The pattern

​

Recipe 1 — Global per-day cap (3 touches/day, all channels, all categories)

curl -X POST https://playground.kaireonai.com/api/v1/contact-policies \
  -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "name": "Global 3/day",
    "ruleType": "frequency_cap",
    "config": { "maxPerDay": 3 },
    "scopes": [{ "scope": "global", "scopeId": null }],
    "status": "active"
  }'

​

Recipe 2 — Per-category cap (Cards category 5/week)

curl -X POST https://playground.kaireonai.com/api/v1/contact-policies \
  -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "name": "Cards 5/week",
    "ruleType": "frequency_cap",
    "config": { "maxPerWeek": 5 },
    "scopes": [{ "scope": "category", "scopeId": "<cards-category-id>" }],
    "status": "active"
  }'

​

Recipe 3 — Per-channel cap (Email 2/day, push unlimited)

curl -X POST https://playground.kaireonai.com/api/v1/contact-policies \
  -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "name": "Email 2/day",
    "ruleType": "frequency_cap",
    "config": { "maxPerDay": 2 },
    "scopes": [{ "scope": "channel", "scopeId": "<email-channel-id>" }],
    "status": "active"
  }'

​

Recipe 4 — Per-offer cooldown (don’t show the same offer twice in 24h)

curl -X POST https://playground.kaireonai.com/api/v1/contact-policies \
  -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "name": "24h cooldown",
    "ruleType": "cooldown",
    "config": { "cooldownHours": 24 },
    "scopes": [{ "scope": "offer", "scopeId": "<platinum-card-id>" }],
    "status": "active"
  }'

​

What the trace will show

contactPolicyResults[
  {
    "offerId": "<premium-card-id>",
    "offerName": "Premium Card",
    "blocked": true,
    "eligible": false,
    "reason": "Weekly frequency cap reached: 5/5",
    "policyId": "<id>"
  }
]

​

Gotchas

• Caps only count impressions that are recorded. Channels default to impressionMode: "explicit", which means an impression is counted only when your client POSTs /respond. If you test a cap by hammering /recommend alone (no /respond), no impressions accrue and the cap looks like it’s being ignored — the same offer returns every call. Either set the channel to impressionMode: "implicit" (the engine auto-records an impression per returned result) or send /respond impression events.
• Under implicit mode, impressions are per creative. The cap aggregates by (offer, channel), but each returned (offer, creative, channel) result records its own impression. If an offer has two active creatives on the same channel (e.g. an A/B creative test), a single /recommend records two impressions toward that offer×channel cap — a maxPerDay: 2 can trip in one call. Keep one active creative per offer per channel for exact cap arithmetic, or account for the creative count.
• A scoped rule with a null scopeId matches nothing useful. If a frequency_cap has scope: "category" but scopeId: null, the scope check compares null to the candidate’s category id, so it only ever matches candidates that themselves have no category — it does not fall back to global. Always set scopeId when scope is anything other than global.
• metric_condition is a different beast. That ruleType reads behavioral metricValue rows (e.g. impression_count_30d > 10), not raw interaction summaries. Use it when you want windowed-aggregate-driven caps.
• Windows are fixed calendar periods, not rolling. maxPerDay counts within the current UTC calendar day (resets at UTC midnight), maxPerWeek uses the ISO week, maxPerMonth the calendar month, and maxTotal is alltime. There is no lookbackHours / rolling-window option on frequency_cap.

​

Proof reference