Skip to main content

​
Volume Constraints

Volume constraints are system-wide delivery caps that automatically block offers when their budget is exhausted. They operate independently of contact policies — contact policies protect individual customers, while volume constraints protect the business from over-delivery.

​
Constraint Scopes

ScopeWhat It ControlsExample
offerCaps delivery of a specific offer”Win-Back: max 20 impressions/day”
categoryCaps all offers in a category”Auto Insurance: max 500/day”
channelCaps all delivery on a channel”Direct Mail: max 50/day”

​
How It Works

  1. Volume constraints are checked during the Contact Policy stage of the decision pipeline
  2. The system queries volume_constraints for the tenant where enabled=true and resetAt > now()
  3. Any constraint where currentCount >= maxVolume adds its scope to the exclusion set
  4. Candidates matching excluded scopes (offer, category, or channel) are filtered out

​
Counter Increment

The currentCount is incremented by the Respond API when an impression outcome is recorded:
  • Only impression-type outcomes increment the counter (clicks/conversions don’t)
  • The increment is atomic (prevents race conditions in concurrent delivery)
  • Counters reset when resetAt passes (configured per constraint)

​
Configuration

Volume constraints are stored in the volume_constraints table:
FieldTypeDescription
namestringHuman-readable name
scopeenumoffer, category, or channel
scopeIdstringID of the offer, category, or channel
maxVolumeintegerMaximum delivery count per period
periodstringReset period: daily, weekly, monthly
currentCountintegerCurrent delivery count (auto-incremented)
resetAttimestampWhen the counter resets
enabledbooleanWhether the constraint is active

​
Best Practices

  • Set channel-level constraints for batch channels (Direct Mail, SMS) to control vendor costs
  • Set offer-level constraints for limited-inventory promotions
  • Monitor currentCount vs maxVolume in the Operations dashboard
  • Use allowPartial in the Group node to gracefully handle exhausted placements