Payout calculator

[VinnyVicious]

Is there a built-in payout calculator? Something that provides the total revenue per ad?

[venediktov]

SSP_Payout_Calculation.md

If approved should be added to cxx23 branch under campaign folder

[venediktov]

SSP Payout Calculation in vanilla-rtb

Overview

This document outlines how the vanilla-rtb framework can be extended to support Supply-Side Platform (SSP) payout calculations. While vanilla-rtb primarily focuses on Demand-Side Platform (DSP) functionality, its existing budget tracking and win notification processing provide an excellent foundation for implementing SSP payment reconciliation.

Current Architecture

The vanilla-rtb framework already implements robust budget tracking and win notification handling, which are the key building blocks needed for SSP payout calculations:

1. Budget Tracking

The framework tracks campaign budgets in examples/campaign/campaign_cache.hpp, which defines:

• CampaignBudget struct with fields for tracking:

  • day_budget_limit (in micro dollars)
  • day_budget_spent (in micro dollars)
  • day_budget_overdraft (in micro dollars)
  • Campaign-specific pricing metrics (CPM, CPC, CPA)

• BudgetManager class that handles budget authorization logic:

  • Checks if campaign has sufficient budget
  • Determines how much can be spent based on campaign metrics
  • Handles different pricing models (CPM, CPC)

The critical method for spend tracking is CampaignBudget::update(types::price) which updates budgets when win notices are received.

2. Win Notification Processing

Win notifications are handled in examples/campaign/notification_service_test.cpp, which:

• Receives win notices with campaign ID and price parameters
• Retrieves campaign budgets from cache
• Updates budgets with the win price
• Tracks total spent amounts
• Broadcasts updates to other system components

The win notification handler is implemented as a CRUD endpoint that matches a configurable URL pattern and processes incoming win notices from exchanges.

Implementing SSP Payout Calculations

To extend vanilla-rtb for SSP payout calculations, we can leverage the existing architecture and add the following components. These components would follow the same patterns used in the existing codebase but focus specifically on tracking SSP payments.

1. SSP Payout Data Structure

Create a new header file (examples/campaign/ssp_payout.hpp) following the pattern of other entity definitions in the project. This would define a structure to track payout information for each SSP, similar to how CampaignBudget is defined in examples/campaign/campaign_cache.hpp.

The structure would track:

• SSP identifier
• Gross spend amount (in micro dollars)
• Platform fee amount (in micro dollars)
• Net payout amount owed to SSP (in micro dollars)
• Impression/win count
• Additional optional fields like currency and time period

Like other structures in vanilla-rtb, it would include serialization support and appropriate operator overloads for logging and debugging.

2. SSP Payout Cache

Create a new cache implementation (examples/campaign/ssp_payout_cache.hpp) following the pattern established in the existing examples/campaign/campaign_cache.hpp file. The cache would:

• Use the same IPC cache architecture from vanilla-rtb's datacache module
• Provide methods to insert, retrieve, and update SSP payout records
• Index records by SSP ID to allow for efficient lookups

3. Extended Win Notification Handler

Extend the existing win notification handler in a new service file based on the pattern in examples/campaign/notification_service_test.cpp. The extended handler would:

1. Receive win notifications (same as the existing handler)
2. Extract SSP information from the win notification
3. Calculate the SSP's share of the win price based on revenue sharing rules
4. Retrieve or create an SSP payout record
5. Update the payout record with the new win information
6. Store the updated record in the SSP payout cache

This follows the same pattern used for campaign budget updates but focuses on SSP payouts.

4. Payout Reporting API

Add API endpoints for SSP payout reporting by extending the CRUD dispatcher pattern seen in the existing services. Following the pattern in examples/campaign/notification_service_test.cpp, add endpoints for:

• Retrieving payout information for a specific SSP
• Getting aggregated payout reports across all SSPs
• Filtering payout data by time period

The implementation would use the CRUD framework already present in vanilla-rtb.

Additional Considerations

1. Payment Period Handling

For real-world use, payout calculations typically need to be aggregated by time periods. This could be implemented by:

• Adding time period fields to the SSP payout structure
• Creating composite keys that combine SSP ID and time period
• Implementing time-based retrieval methods in the payout cache

This approach would follow the pattern of other time-sensitive data in the system.

2. Currency Handling

For international SSPs, you may need to handle multiple currencies by:

• Adding currency fields to the SSP payout structure
• Implementing a currency conversion service
• Storing exchange rates or integrating with external rate providers

3. Reconciliation and Dispute Resolution

Add reconciliation functionality to track discrepancies between your calculated payouts and SSP-reported numbers:

• Create a reconciliation record structure
• Add methods to compare platform-calculated amounts with SSP-reported amounts
• Implement workflow states for reconciliation (pending, approved, disputed)
• Add reporting endpoints for reconciliation status

Conclusion

The vanilla-rtb framework provides a strong foundation for implementing SSP payout calculations through its existing budget tracking and win notification handling. By extending the system with SSP-specific data structures and processing logic, you can create a complete payment reconciliation system that accurately tracks what you owe to your supply partners.

The key advantages of building on vanilla-rtb for this purpose include:

1. Existing Win Notification Processing: The framework already handles the critical step of processing win notices with price information.

2. Robust Budget Tracking: The CampaignBudget structure and update mechanisms provide a pattern for tracking financial metrics.

3. IPC Cache Architecture: The existing cache architecture can be reused for storing and retrieving SSP payout records.

4. Distributed Architecture Support: Built-in communication mechanisms allow for real-time distribution of payout information across system components.

By implementing the extensions described in this document, you can transform vanilla-rtb into a system that not only manages DSP campaigns but also accurately tracks and reports SSP payouts.

---

Document created: March 30, 2025 | Generated by AI code analysis