1. Objective

Use negative GGR on a commission group (GFG) as a free buffer and, through promo campaigns, optimize commission on the remaining groups within the same calendar month.

Buffer flow diagram

2. Roles and responsibilities

Who owns the process, who executes it, and who helps.

Decision matrix

3. Inputs and definitions

Below → every term you'll need going forward.

Entity relationship diagram

4. Negative GGR lifecycle

How we detect negative GGR every day, calculate the buffer, and decide which campaigns to launch.

4.1 Detection algorithm

For each GFG the system checks: if GGR < 0, it tags the group NEGATIVE, adds the size of the minus to the buffer, and sends a Slack alert. The NEGATIVE tag is set immediately; buffer_value is recomputed daily (00:30 UTC) from MTD GGR. The Game Manager and CRM get an instant notification.

Pseudocode and technical details → Section 14

4.2 Daily cycle

• 00:10 UTC → load stakes/payouts (ETL).
• 00:30 UTC → automatic buffer calculation per GFG.
• 01:00 UTC → the system schedules or updates promo campaigns.
• 09:00 local time → Game Manager reviews and adjusts auto-promos; checks responsible-gaming (RG) flags.
• Every hour → a bot posts a GGR heatmap to Slack; alerts if the buffer drops >50% in 24h - except during the burn phase (T3/T4), where the drop is expected (logged as informational; an alarm only if the drop is not explained by an active BUFFER promo).

Full procedure with technical detail → Section 14

4.3 Lifecycle diagram

5. Triggers and timelines

Triggers → events that tell us what to do and by when. The table below shows the trigger code (T1–T5), what happened, under what condition, the reaction time, and the action to take.

5.0 Trigger precedence

If several triggers' conditions hold at once, precedence is T5 > T4 > T3 > T2 > T1. T1 always fires on the first negative day. If fewer days remain in the month than T2 needs (3 consecutive days), T2 is skipped - on entering the final window, T3 applies directly.

5.1 Trigger summary table

5.2 Trigger timeline (diagram)

5.3 Trigger actions

T1 → tag the GFG, calculate the buffer, send a Slack alert. The Game Manager checks the games for anomalies.

T2 → the Game Manager instructs Marketing to turn on a turnover bonus (1.5x points) and move the games to the top row of the lobby. Expected: stakes up ~+20% over 48h.

T3 → free spins (20 FS, max win €100), 5-10% cashback via the Bonus API with wagering restricted to games in the GFG, max bet capped at €5. In parallel, the Game Manager contacts the provider about co-funded campaigns → Section 7

T4 → jackpot tournament (prize pool 50/50 with the provider) and missions. Goal: use ≥ 80% of the remaining buffer before midnight.

T5 → automatically turn off all promos, generate a report, reset tags.

Technical details (fields, flags, tables) → Section 14

6. Operator tools and tactics

The tools the operator uses to manage campaigns and risks.

6.1 Promo mechanics

Every wagering row in the table below must respect the game_ids / provider_id binding when granted via the Bonus API.

6.2 Bonus API checklist (Marketing + Tech Support)

6.3 Technical levers

• Win cap → up to x500 of the bet to limit variance.
• Dynamic banners → automatic rotation of GFG tiles in the lobby.
• Max bet cap → €5 by default; €2 for high-RTP games during the burn phase.
• Wagering whitelist → the Bonus API requires allowed_game_ids and/or allowed_provider_id for every wagered buffer bonus.

6.3.1 Consolidated limits table

6.4 Creating a negative-GGR game category

For operational buffer management, the Game Manager creates a separate category (tag/group) in the casino back-office, into which games from negative-GGR GFGs are placed automatically or manually.

Why the category is needed

• Fast lobby placement → move the whole category into the top row or a featured block (e.g. "Hot Games", "Trending") in a single action.
• Targeted promos → tie free spins, cashback, or a tournament to exactly the games in this category rather than picking them manually.
• Monitoring → a separate category gives a dashboard: how many games are "in the minus," total buffer volume, day-by-day dynamics.
• Automation → when trigger T1 fires, the system automatically adds the game to the category; at month close (T5) it clears it.

Setup

Process

1. Initial setup → the Game Manager creates the category in the back-office; Tech Support configures the automatic rule (a webhook adds games when a GFG's status turns NEGATIVE).
2. On T1 → the system automatically populates the category with games from negative-GGR GFGs.
3. On T2–T4 → the Game Manager surfaces the category (or part of it) in a lobby block; Marketing ties promos to this category.
4. On T5 → the system clears the category; the lobby block is hidden until the next trigger.

Technical tool fields (code-level) → Section 14

7. Joint campaigns with the provider

When a GFG's GGR goes negative, the Game Manager initiates talks with the provider about co-funded promos: splitting the cost lowers the operator's spend and strengthens the partnership.

7.1 When to engage

• T2 and later → with a stable negative GGR on the group (3+ consecutive days).
• T3–T4 → when ≤ 3 days remain in the month and buffer > 0 (T3), then the second-to-last day (T4); especially ahead of jackpot tournaments and missions.

7.2 Types of joint campaigns

7.3 Arguments for the provider

• Volume → joint promos boost turnover on their slots.
• Visibility → games land in the top row of the lobby, banners, mailers.
• Balance → negative GGR means low commission for the provider too; the shared goal is to bring interest back to the group.
• Longevity → joint campaigns stabilize metrics and strengthen the partnership.

7.4 Process

• Step 1. Negative GGR detected (T1/T2) → the Game Manager sees a Slack alert.
• Step 2. Assessment → buffer size, days remaining in the month, the group's history.
• Step 3. Contact the provider → an email/call with justification and a co-funded promo proposal (tournament, free spins, missions).
• Step 4. Agreement → formats, timelines, cost split, limits (max bet, max win); for wagered bonuses — game_ids / provider_id whitelist in the Bonus API.
• Step 5. Launch → Marketing configures the promo and grants bonuses via the Bonus API with wagering tied to GFG games (see → Section 6).
• Step 6. Results → include the joint campaign's results in the Provider_Fee_Optimization_Report.

7.5 Provider outreach template

Subject: Joint campaign for GFG [ID] - negative GGR for [month]

Hello,

Group [GFG ID / name] recorded negative GGR of €[X] for [month]. We're planning a promo to bring activity back to this group before month end.

We'd like to propose a joint campaign:
- Type: [tournament / free spins / missions]
- Proposed split: [e.g. 50/50]
- Timeline: through [date]
- Wagering: wagered bonuses — restricted to your games in this GFG only (Bonus API whitelist)

Expected effect: increased turnover on your slots and stabilized metrics. Happy to discuss details and integration formats.

Best regards,
[Game Manager]

7.6 Escalation

If the provider doesn't respond within 48 hours or declines the proposal → the Game Manager logs the decision in #financial-ops and continues working the buffer with in-house promos (no co-funding).

8. Automation and integration

The system automatically fires trigger actions through a webhook to the promo engine and a cron job for hourly recalculation.

8.1 How it works

• Webhook → when a trigger fires (T1–T4), the system automatically sends a request to the promo engine with campaign parameters (type, multiplier, validity period, game_ids / provider_id for the Bonus API).
• Cron → a script runs every hour to recalculate the buffer and update GFG statuses.
• Escalation → if an automated promo isn't spending down the buffer, the system notifies the Game Manager for a manual review and extra measures.

Technical details (endpoint, JSON, cron command, escalation schema) → Section 14

9. Metrics and KPIs

The metrics that tell us the buffer and promos are working as intended. Below → the formula, target value, and why we track it.

10. Risks and mitigations

The main risks when working with the buffer and promos → and how we mitigate them.

11. Message templates

Channels: #promo_ops - automated T1-T4 trigger alerts (tag, buffer, promo launch); #financial-ops - operator notes, escalations, commission reports, and co-funded decisions.

Sample Slack alerts:

12. Contacts and escalation

Who to contact and within what timeframe for buffer and promo questions.

Short explanations for every section - gathered in one place for quick review. Full summaries remain at the end of the corresponding sections 1–12 (except section 8, which has no separate summary).

14. Technical block

All technical details, code, API integrations, and data schemas are gathered in this section.

14.1 Negative GGR detection algorithm (pseudocode)

for provider in providers:
    for gfg in provider.gfgs:
        if gfg.ggr < 0:
            gfg.tag = "NEGATIVE"
            gfg.buffer_value = abs(gfg.ggr)
            send_slack(
                channel="#promo_ops",
                msg="🛑 NEGATIVE GGR detected: {gfg.id} -> €{gfg.ggr:,.2f}"
            )

14.2 Webhook (e.g. SoftSwiss / GameAggregator)

Endpoint: POST /api/v1/promotions/trigger

Content-Type: application/json

{
  "gfg_id": "12345",
  "event": "NEGATIVE_GGR",
  "buffer": 1587.32,
  "action": "TURNOVER_BOOST",
  "multiplier": 1.5,
  "valid_until": "2026-07-31T23:59:59Z",
  "meta": {
    "trigger_id": "T2",
    "initiator": "auto_buffer_bot"
  }
}

14.2.1 Bonus API (wagered bonuses)

Endpoint: POST /api/v1/bonuses/grant (or the platform's equivalent). Required wagering-restriction fields:

{
  "player_id": "uuid",
  "gfg_id": "12345",
  "amount": 50.00,
  "currency": "EUR",
  "wager_multiplier": 10,
  "allowed_game_ids": ["game_a", "game_b"],
  "allowed_provider_id": "provider_xyz",
  "valid_until": "2026-07-31T23:59:59Z",
  "meta": {
    "trigger_id": "T3",
    "promo_tag": "BUFFER"
  }
}

Specify either allowed_game_ids (a narrow binding to GFG slots) or allowed_provider_id (all of that GFG's provider's games). Leaving both fields empty is not allowed for buffer promos.

14.3 Cron (hourly recalculation)

# Runs every hour
0 * * * * /opt/ops/ggr_optimizer.sh --month $(date +%Y-%m)

14.4 Data tables

14.5 Escalation schema

14.6 Daily schedule (UTC)

14.7 Detailed action sheets (technical fields)

T1 → Base tag and buffer

• Automation: set the NEGATIVE flag in the gfg_status table; save buffer_value = |GGR−|.
• Operator: check the game list for anomalies (e.g. a spike in refunds); leave a short note in #financial-ops.

T5 → Close and reset

• Automatically turn off all promos tagged BUFFER.
• Generate the Provider_Fee_Optimization_Report (PDF); save to S3; send to Finance, CRM, and RG.

14.8 Promo tool fields

14.9 Technology stack

A summary of the components the Playbook can't run end-to-end without. Specific vendors (SoftSwiss, GameAggregator, etc.) are examples of a white-label platform; when integrating on a different stack, keep the same roles and data contracts from 14.1-14.8.

Minimal MVP stack: ETL → GGR_Snapshot → buffer job → gfg_status → Slack alert (T1) → manual promo launch in the back-office. Full automation adds cron, webhook, Bonus API with a whitelist, and the month-end T5 pipeline.