Limits
Limits protect your promotional budget and prevent abuse before it happens. They operate at two levels: company-wide (a global ceiling across all campaigns) and per campaign (specific caps on a single promotion). The same system applies to both Discount and Points campaigns.
Two evaluation modes — understand this before configuring any limit:
| Mode | How it works | Which limits use it |
|---|---|---|
| ✅ Real time | Checked on every transaction, at the moment the cart is evaluated. Enforced immediately — no overshoot. | Company global cap · Chances to accrue per customer · Max per transaction · Limit of effects |
| ⏱ Background worker (~5 min) | A background job recalculates the counter approximately every 5 minutes and writes it to the database. The streaming engine reads the last written value. If many transactions arrive before the next refresh, the campaign may fire a few extra times. | Chances to accrue (campaign total) · Campaign budget |
For hard financial caps (e.g. "this campaign must not exceed €10,000"), use real-time limits or set the soft limit ~5–10% below the true ceiling to absorb the overshoot window.
Company-wide global limit
Evaluation: real time
Configured in Configuration → Promotions → Points & Wallet → Points → Limits.
This setting defines the maximum monetary value a single customer can accumulate from any campaign in a given period, across the entire company. On every transaction, the engine queries the customer's accumulated total for the current period and compares it to this ceiling. If the ceiling is reached, no further discount or points campaigns apply to that customer's cart until the period resets.
| Setting | What it controls |
|---|---|
| Period | The time window for the cap: daily, monthly (relative or natural), or yearly (relative or natural). |
| Value | Maximum amount in company currency a customer can accumulate in that period. |
| Country | The cap can be configured per country for multi-market companies. |
This is a monetary cap on accumulation — it tracks the total value awarded to the customer across all campaigns, not the number of redemptions. It applies to both discount and points campaigns.
Example: Cap set to €50/month. A customer has already received €47 in discounts this month. At checkout, the engine calculates that the next campaign would give them €8 off — but only €3 of headroom remains. The campaign is skipped entirely (not partially applied). At the start of the next month the counter resets and the cap applies fresh.
Per-campaign limits
Set on each campaign individually in the Limits section of the campaign form — a dedicated accordion block that appears after the Effects section, also accessible when editing an existing campaign.
Chances to accrue — campaign total
Evaluation: soft limit (~5 min refresh)
A cap on the total number of times this campaign can fire across all customers in a period. The engine pre-filters campaigns using a counter column (chance_to_accrue_limit_reached) that a background worker refreshes approximately every 5 minutes. Once that counter reaches the configured limit, the campaign is excluded from evaluation for all customers.
| Period option | Behavior |
|---|---|
| Always | No campaign-wide cap (default). |
| Per day | Resets daily. |
| Per month | Resets monthly (relative or natural month). |
| Per year | Resets yearly (relative or natural year). |
| Total | Lifetime cap — campaign stops permanently once reached. |
Because this is a soft limit, there is a window of up to ~5 minutes where the campaign may continue to fire after the limit is reached. For example, if the limit is 1,000 uses and 10,000 transactions arrive in a short burst, the campaign may fire 1,020–1,050 times before the worker stops it.
Example: Flash campaign limited to 500 uses total. At 08:00, 600 customers transact simultaneously. By 08:05 (next worker refresh), the campaign has fired ~510–530 times before being deactivated. If the limit must be strictly enforced, set it slightly below your target (e.g., 480) to account for the overshoot window.
Chances to accrue per customer
Evaluation: real time
Controls how many times a single customer can benefit from this campaign in a period. On every transaction, the engine queries the database for that customer's previous uses of this specific campaign in the current period. If the limit is reached, the campaign is skipped for that customer only — others are unaffected.
| Period option | Behavior |
|---|---|
| Always | No per-customer cap (default). |
| Per day | Up to N times per customer per calendar day. |
| Per month | Up to N times per customer per month (relative or natural). |
| Per year | Up to N times per customer per year (relative or natural). |
| Total | Maximum N times per customer over the campaign's lifetime. |
- For campaigns targeting All customers, this field is forced to Always — it cannot be changed.
- For Targeted campaigns with a coupon, only Always and Total are available.
Example: "10% off for loyalty members, max 3 times per month." Customer A has used it twice this month. On their third purchase this month, the campaign fires (2 < 3). On their fourth purchase, the engine queries the DB, finds 3 prior uses, and skips the campaign — silently, with no error shown.
Campaign budget
Evaluation: soft limit (~5 min refresh)
A monetary cap on the total value this campaign can award across all customers. Like the campaign-total cap, the engine uses a pre-computed budget_limit_reached counter updated by the same background worker. Once the cumulative awarded value reaches the threshold, the campaign is excluded from evaluation.
| Period option | Behavior |
|---|---|
| Unlimited | No budget cap (default). |
| Per day | Budget resets daily. |
| Per month | Budget resets monthly (relative month). |
| Per year | Budget resets yearly (relative year). |
The budget value is always in the company's base currency.
Same overshoot risk as Chances to accrue — the soft counter may allow a small amount over budget during high-traffic windows before the worker refreshes. For tight budget control, configure the limit ~5–10% below the actual ceiling.
Example: Campaign budget of €10,000 per month. By the 20th of the month, €9,980 has been awarded. Five large carts arrive simultaneously, each generating a €15 discount. The worker hasn't refreshed yet — all five fire, awarding €75 more. The final amount awarded is ~€10,055. The worker then sets the campaign as exhausted, stopping further applications.
Maximum amount per transaction
Evaluation: real time
A hard cap on the value applied in a single transaction, regardless of what the campaign would otherwise calculate. Applied during cart computation — if the calculated discount or points award exceeds this limit, it is reduced to the configured maximum.
- For Discount campaigns: maximum discount amount applied per cart.
- For Points campaigns: maximum points or wallet amount awarded per event.
Example: Campaign gives 5% off on all electronics. A customer buys a €2,000 TV — 5% would be €100. Max per transaction is set to €50. The engine caps the discount at €50 and returns that value. The remaining €50 is not carried forward.
Limit of effects
Evaluation: real time · Configured in: Effects section of the campaign form, not in Limits
The Limit of effects field is part of the Effect configuration — it controls how many times the effect fires within a single transaction. Documented here for completeness because it interacts with the Limits system during evaluation. Particularly relevant for bundle and BOGO mechanics.
| Setting | Behavior |
|---|---|
| 0 / blank | No limit — effect fires as many times as conditions are met. |
| N | Effect fires at most N times per transaction. |
Only available for Cart events with percentage, direct_value, ratio, or combo_price effects.
Example: 2×1 campaign (Buy 2 Coca-Cola, get 1 free), limit of effects = 2. A customer adds 8 Coca-Colas to the cart. Without a limit, the engine would apply the 2×1 three times (3 free units). With limit = 2, it applies twice — 2 free units. The remaining 2 extra units receive no discount.
How limits are evaluated
At the moment a transaction arrives, limits are checked in this order:
- Company global cap (real time) — the engine queries the customer's accumulated value for the current period. If the ceiling is reached, evaluation stops immediately — no campaigns of any type are returned.
- Campaign budget pre-filter (soft) — campaigns where the budget counter ≥ budget value are excluded from the query entirely before evaluation begins.
- Chances to accrue pre-filter (soft) — campaigns where the use counter ≥ the campaign-total limit are similarly excluded at query time.
- Per-customer frequency check (real time) — the engine counts prior uses by this customer for each remaining campaign. Campaigns where the customer has reached their limit are skipped.
- Per-transaction cap (real time) — applied during cart calculation; the awarded amount is capped if it would exceed the configured maximum.
- Effect-level limit (real time) — applied during effect application; caps how many times the effect fires within the transaction.
If a limit is reached at any step, the campaign is skipped silently. No error is shown to the customer.
Summary table
| Limit | Scope | Evaluation | Where to configure |
|---|---|---|---|
| Global accumulation cap | All campaigns, per customer | ✅ Real time | Configuration → Promotions → Points & Wallet → Points → Limits |
| Chances to accrue | Campaign total (all customers) | ⏱ Soft (~5 min) | Campaign → Limits section |
| Chances to accrue per customer | Per customer, per campaign | ✅ Real time | Campaign → Limits section |
| Campaign budget | Campaign total value | ⏱ Soft (~5 min) | Campaign → Limits section |
| Max per transaction | Single transaction | ✅ Real time | Campaign → Limits section |
| Limit of effects | Per evaluation, per effect | ✅ Real time | Campaign → Effects section |
See also: Stackability & Priority to control how multiple simultaneous campaigns combine.