Setting Budgets and Constraints

This guide explains how to apply strict financial controls to your promotions. Without proper limits, the cost of a popular campaign can quickly spiral. This feature allows you to enforce caps on resource allocation, ensuring your promotional activities stay within budget.
By assigning budgets and limits, you can:

• Set maximum daily, weekly, or monthly usage caps per reward.
• Prevent overuse or abuse of promotions during a campaign.
• Control your total promotional spend across multiple campaigns and tiers.

If a configured cap is reached, any further promo code activations will automatically fail, protecting your budget.

Prerequisites

Before you begin, you will need:

• An existing promotion created in Promotions.
• The promotionId of the promotion you wish to modify.

Understanding a Promotion's Limits

Promotions offers two distinct ways to control spending. It's important to understand the difference:

• Publishing Budget: These are defined only at the individual promotion level. You can set these limits in two ways:

  • Audience Cap: Limit the number of customers who can participate in the promotion.
  • Reward Budget: Limit the total reward amount or number of items granted throughout the promotion (e.g., "This promotion cannot exceed a total budget of £5,000" or "Do not grant more than 10,000 free spins in total").

  Valid timeframe Values

  The timeframe field in the Set Publishing Budgets API accepts the following values:

  Value	Resets	Typical use
  DAILY	Midnight at the start of each calendar day in the tenant's configured timezone (defaults to UTC)	Daily free-spin or cashback limits
  WEEKLY	Start of each tenant-local week (day determined by the tenant's firstDayOfWeek setting; defaults to Sunday). Time is midnight in the tenant's configured timezone.	Weekly prize pools or challenge budgets
  MONTHLY	Midnight on the 1st of each calendar month in the tenant's configured timezone (defaults to UTC)	Monthly promotional budgets
  LIFETIME	Never — total cap across the full lifetime of the promotion	One-time reward caps, total spend ceilings

  Each budget entry pairs a timeframe with exactly one budget type. Choose the type that matches your reward:

  Amount-based budgetUnit-based budgetCap budget

  PATCH /v1/promotions/{promotionId}/publishingBudgets
  {
    "budgets": [{
      "timeframe": "WEEKLY",
      "amountRewardBudget": {
        "amountCents": 1000000,
        "amountRewardTypeId": "cashback_usd"
      }
    }]
  }

  PATCH /v1/promotions/{promotionId}/publishingBudgets
  {
    "budgets": [{
      "timeframe": "WEEKLY",
      "unitRewardBudget": {
        "unitCount": 10000,
        "unitRewardTypeId": "free_spin"
      }
    }]
  }

  PATCH /v1/promotions/{promotionId}/publishingBudgets
  {
    "budgets": [{
      "timeframe": "WEEKLY",
      "capBudget": {
        "cap": 500
      }
    }]
  }

  When the total reward issued within the current period reaches the configured budget, the promotion auto-pauses for new validation requests. It resumes automatically at the start of the next period (except LIFETIME, which is permanent).

• Reward Constraints: These are defined at the reward setting level, meaning they apply globally to all promotions that use that specific reward. However, you can override these global limits for an individual promotion if needed.

  

Monitoring Budget Consumption

The Promotion Query API returns a reward_consumption object on each promotion, allowing you to monitor real-time budget usage without waiting for the promotion to auto-pause.

Response Structure:

GET /v1/promotions/{promotionId}

{
  "reward_consumption": {
    "amount_cents": {
      "<amountRewardTypeId>": {
        "daily":    0,
        "weekly":   620000,
        "monthly":  0,
        "lifetime": 620000
      }
    },
    "unit_count": {
      "<unitRewardTypeId>": {
        "daily":    0,
        "weekly":   50,
        "monthly":  0,
        "lifetime": 200
      }
    },
    "cap": {
      "daily":    0,
      "weekly":   95,
      "monthly":  0,
      "lifetime": 95
    }
  }
}

Structure

Each entry contains all four timeframe counters:

To calculate remaining budget for a given period, subtract the relevant counter from the budget you configured. When a counter reaches the configured budget, the promotion auto-pauses for new validation requests.

When to use this:

• Build a real-time prize-pool progress indicator ("£3,800 remaining this week")
• Alert your team before a budget is exhausted
• Audit reward issuance per period without pulling full campaign reports

API Reference

Next Steps

• Learn how to add custom data fields to your promotions: ➡️ Adding Custom Properties