How to Design a Configurable Bonus Engine

A bonus engine has to answer a question that a campaign editor rarely shows: what happens to this player's entitlement when the same deposit arrives twice, a qualifying bet is voided, or the campaign changes before the bonus finishes? If the answer depends on whichever rule is currently published, the engine cannot explain its own decisions.

For product managers and engineers designing an iGaming platform, the useful starting point is one accepted offer with a stable rule version, a traceable award and a reconciled financial outcome. This article follows that path. The calculations and state names below are design examples, not an offer to players or a statement that the promotion is lawful in every market.

Make the offer a contract that the system can enforce

Separate the campaign definition, the player's accepted offer, the individual bonus instance and the wallet postings. A campaign says what can be offered. Acceptance records what was shown and agreed. The instance records progress and decisions. The wallet records money. A segment label or a campaign's current configuration must not stand in for any of these records.

Define a small, typed vocabulary rather than letting marketers execute arbitrary code. A deposit-match template might require:

• Scope: operator, market, currency, product, eligible accounts and campaign window.
• Award: qualifying deposit definition, match rate, cap, rounding rule, per-player limit and campaign budget unit.
• Play: eligible games, contribution weights, stake limits, funding order and the treatment of voids, partial refunds and unsettled rounds.
• Exit: acceptance and play deadlines, completion rule, conversion amount, voluntary cancellation and expiry consequences.
• Evidence: configuration version, terms version and language, acceptance time, decision reasons and approving staff.

Compile the same reviewed definition into execution rules and a player-facing explanation; human review must still catch omissions and misleading wording. State which balance is withdrawable, which is conditional, how progress is measured and what cancellation does. Reject a configuration if the interface cannot express its material conditions.

Market policy belongs above campaign tuning. For Great Britain, Gambling Commission code 5.1.1 caps bonus wagering at ten times and restricts mixed-product incentives. Its official explanation dates the new requirements to 19 January 2026. Other markets require their own review. Encode approved market constraints as non-overridable publication checks, not optional fields in a campaign form.

Evaluate eligibility before reserving an award

Keep offer targeting, permission to contact a player and permission to award a bonus as separate decisions. A player in a marketing segment is not automatically entitled to receive communications or a reward. Recheck the applicable account and player-protection restrictions when accepting and activating the offer, rather than trusting a segment export created yesterday.

A deterministic evaluation order makes conflicts visible:

1. Validate the trigger: authenticate its source, resolve operator and account, verify currency and final deposit status, and identify any previous processing of that trigger.
2. Apply mandatory restrictions: market, account, verification and player-protection policy. If a necessary check is unavailable, record a pending decision without granting spendable value.
3. Check the offer: accepted version, window, qualifying activity, previous awards and exclusions.
4. Resolve competing campaigns: apply an approved stacking rule and deterministic priority with a stable tie-breaker. Do not let response speed select the winner.
5. Reserve capacity: atomically claim the per-player allowance and campaign budget before requesting a wallet credit.

Repeat the decisive conditions at reservation under a transaction or equivalent concurrency control. Two workers must not both see the last available allowance and grant it. Give the reservation a unique award identity, an owner and a recovery procedure. Define whether the budget counts awarded face value, reserved exposure or another approved measure; these are different quantities. Reserve and release in that same unit.

Return structured reasons such as account restricted, offer already used, budget exhausted or decision pending. Support needs an explanation; the player interface need not reveal fraud detection details. Shared devices or addresses are signals for proportionate investigation, not automatic proof of abuse. Provide a review route and never let a campaign priority bypass a mandatory restriction.

Separate bonus states from money movements

Use the bonus instance to coordinate the offer, not to pretend that an external wallet operation has already succeeded. One workable model is:

• Reserved: eligibility and capacity are recorded, but there is no usable bonus yet.
• Activation pending: a durable credit request exists; retries refer to that same award.
• Active: the wallet confirms the credit and the player can use the bonus under its accepted rules.
• Closing: completion, cancellation or expiry has started. Stop new bonus-funded play, drain already accepted operations according to policy and reconcile the closing balance.
• Completed, cancelled or expired: the corresponding financial outcome is confirmed and the closing reason is recorded.

Keep review holds and dependency failures as separate flags or substates. A suspended active bonus still has an active lifecycle and a financial balance; calling it simply failed loses that distinction. A campaign paused for new awards need not cancel bonuses already accepted. Define both controls explicitly.

For an active bonus, entering closing is a durable decision with an expected instance version. Completion and an expiry worker must not both win. The decision records its reason, accepted rule version, relevant event boundary and ledger references. After closure, a delayed event does not silently reactivate the bonus. It enters the documented correction process.

Specify both when a bet qualifies and how long its settlement can remain unresolved. For example, an approved policy might evaluate the play deadline at bet acceptance, stop new qualifying bets at that deadline and wait for those already accepted to settle before final closure. Another policy may differ. Choose and disclose the rule before launch; do not invent it when a delayed provider response arrives. The wager history and wallet settlement must use the same boundary.

Calculate wagering from an explainable history

Define wagering progress as a sum of eligible contributions, with reversals linked to their original contributions. Record the bonus instance, provider transaction and round identities, eligible stake amount, currency, contribution weight and rule version. State whether progress is earned at bet acceptance or settlement. For the following example, it is earned only after settlement, refunded stakes do not count, and voids remove the contribution previously recorded.

Hypothetical calculation: a player deposits 100 units and receives a 20-unit bonus. The approved requirement is five times the bonus amount, so the target is 20 × 5 = 100 units of weighted wagering. The deposit is not part of that calculation. This is a progress example; it does not calculate player winnings or a withdrawable balance. Contribution weights affect the actual amount of play needed. A nominal multiplier alone does not establish compliance with a market cap; the whole offer needs review.

1. A settled eligible stake of 10 units with a 100% contribution adds 10 units of progress.
2. A settled eligible stake of 30 units with a 20% contribution adds 6. Progress is now 16.
3. The first stake is voided. Its linked reversal removes 10, leaving 6.
4. A new settled eligible stake of 12 units with a 100% contribution adds 12, giving 18. Its duplicate callback adds nothing. The remaining requirement is 100 − 18 = 82.

Use integer minor units or exact decimals with an explicit rounding rule. Do not repeatedly round the displayed percentage and then use it as accounting input. For a partially refunded bet, reverse the corresponding contribution once; retain the original and correction records so support can reproduce the result. Disallow an unsupported game, currency or contribution weight before play instead of discovering it at withdrawal.

The displayed counter may stop at the target, but retain the underlying contributions. Completion means both that the approved wagering condition is satisfied and that the relevant financial obligations can close safely. A qualifying bet can reach the target while its wallet operations are still unresolved. Keep conversion pending until the required settlements are confirmed. A later correction to an already completed bonus needs a separately reviewed financial adjustment; do not secretly rewrite the requirement or automatically seize cash.

When a stake uses both cash and bonus funds, record the split at placement and apply the accepted payout-attribution rule at settlement. Do not infer the funding source from the balance left afterwards. A reversal must restore the correct balance buckets. Define explicitly which conditional funds lapse on cancellation or expiry; an instance state alone is not authority to remove unrelated cash.

Keep deposited money and conditional bonus funds distinct. The CMA's UK enforcement history addresses withdrawal barriers affecting players' own money and unfair changes to accepted promotions. As a design rule, never derive the deposit balance's withdrawal status from the bonus progress counter.

Make wallet uncertainty an explicit operational state

Give every award, conversion and cancellation a stable operation identity. Namespace provider event identities by operator, provider and event type so unrelated transactions cannot collide. A timeout after a credit request means the outcome is unknown, not that no credit happened. Query the authoritative wallet or retry the same operation under its idempotency contract. Never create a fresh credit identifier merely because the response was lost.

The Amazon Builders' Library explains request tokens, parameter mismatch checks and retention for late retries. Apply that principle to bonus operations: store the intent with the identity, reject reuse with a different amount or currency, and retain deduplication evidence for the supported replay horizon. A deduplication cache that expires before a delayed callback is not sufficient evidence that an award is new.

If bonus state and wallet postings share a database and ownership boundary, a local transaction may be the simplest way to commit them together. If the wallet is external, persist the intent and track acknowledgements; treat reconciliation as part of the workflow. An outbox can commit a local state change and its outgoing event together. It does not remove duplicate delivery or make a remote wallet update atomic.

• Credit confirmed, activation response lost: recover the original credit and activate the existing instance once.
• Credit outcome unresolved: retain the reservation and investigate; do not release capacity while an award might already exist.
• Expiry races with a placed bet: use the recorded acceptance boundary and closing workflow, not callback arrival order.
• Conversion confirmed, completion event delayed: reconcile against the conversion posting; do not issue another conversion.

Reconciliation should compare bonus instances, award reservations and wallet postings by their identities. Flag active instances without confirmed credit, unmatched credits, duplicate conversion attempts and closing instances with outstanding operations. For each exception define who can inspect it, what evidence closes it and which correction is allowed. Manual adjustments need a reason, scoped authority and an audit trail, with separate approval where policy requires it.

Give configuration the discipline of a software release

A configuration is executable financial behaviour. Validate its type, value ranges, compatible currencies and games, market constraints, conflicting priorities and references before publication. Reject contradictory combinations, such as a product-specific award coupled to an incompatible wagering rule, rather than silently dropping one condition.

Separate draft, reviewed, scheduled and published versions. Record who changed what and who approved it. Snapshot the accepted terms and all execution inputs needed to reproduce an award. A version number alone is useless if it points to a mutable row; retain the immutable definition, referenced game weights and evaluation code version.

Changing a contribution weight from 20% to 100% must not recalculate previously recorded bets with the new value. A new campaign version should govern new acceptances, while existing instances retain their approved terms. A genuinely necessary correction needs an explicit affected-instance plan, legal and product review, player communication where required, and reconciled adjustments. Restoring an earlier campaign configuration does not undo credits already posted.

Use permissions suited to the consequences: a campaign editor can propose rules; the publication process enforces required review; support can view a decision without gaining the ability to invent wallet credits. Provide separate controls for stopping new awards and responding to an incident affecting active instances. If an emergency disables play, preserve records and give operations a way to resolve each existing entitlement.

Start with a few constrained templates that cover real promotions. Add a new rule type only when its calculation, explanation, reversals, testing and support handling are defined. Unlimited combinations may shorten the first campaign setup while making every later dispute harder to resolve.

Launch with a replayable acceptance pack

Before enabling a campaign, run its evaluator against a fixed, privacy-controlled set of representative events with wallet writes disabled. Replay is useful only if time, segment inputs, account facts, game mappings and rule versions are fixed too. Do not present results using today's account state as an explanation of yesterday's award.

Compare expected and actual award identities, reasons, reservations, weighted contributions and closing outcomes. Include duplicate deposits, simultaneous claims for the last allowance, callback reordering, partial refunds, provider unavailability, the exact deadline and a campaign change mid-bonus. Check the player-facing terms and progress explanation in every supported language against the same accepted definition.

Then exercise the financial path in a controlled environment: activation, play, reversal, conversion, expiry and recovery after a lost acknowledgement. Replay without wallet writes cannot prove the posting contract. Set an initial exposure cap and rollout scope based on an approved risk assessment, not an invented universal safe number. Make stopping new awards operationally accessible.

Measure unresolved credit outcomes, the age of reservations and closing instances, contribution reversals, reconciliation exceptions and support disputes. Evaluate these alongside campaign results; faster issuance alone says little about reliability or player value. Avoid rewarding teams for increased gambling by restricted players or for aggressive expiry. The launch decision should rest on explainable awards, controlled exposure and demonstrably recoverable failures.

For the surrounding design, see wallet and transaction ledger architecture, back-office roles and auditability, and player verification workflows. Virtual economy architecture covers a related reward model whose currencies and redemption assumptions need a separate assessment. For implementation scope, see bonus and loyalty development and platform integration services.

• A support specialist can reconstruct one accepted offer from its terms, eligibility inputs, reservation, award and rule version without using the current campaign configuration.
• Duplicate and concurrent triggers cannot create a second award or overspend the approved reservation budget; unknown credit outcomes remain recoverable.
• Wagering examples reproduce exactly across settlement, void and partial-refund cases; the deposit withdrawal decision stays separate from bonus progress.
• Completion and expiry produce one confirmed financial outcome, with a documented route for late corrections and a working control to stop new awards.