Profitability & Revenue Reports

Overview

The profitability system tracks revenue, internal costs, and margins at both the agency and client level. It pulls client revenue from billing data and internal costs from usage history to calculate profit per client and per agent.

Agency-Level Profitability

The platform-wide P&L aggregates all active clients for a given period.

Endpoint: GET /admin/profitability?period=YYYY-MM

Returns:

Field	Description
`totalClients`	Number of active clients in the period
`totalMinutes`	Total call minutes across all clients
`totalInternalCost`	Sum of all internal costs (telephony, AI usage, etc.)
`totalRevenue`	Sum of `clientRevenue` from all client billing records
`profit`	`totalRevenue - totalInternalCost`
`profitMargin`	Profit as a percentage of revenue
`byClient`	Per-client breakdown with minutes, cost, revenue, and profit

Example Response

{
  "success": true,
  "data": {
    "period": "2025-06",
    "totalClients": 12,
    "totalMinutes": 3420,
    "totalInternalCost": 1840.50,
    "totalRevenue": 8500.00,
    "profit": 6659.50,
    "profitMargin": 78,
    "byClient": {
      "client_abc": {
        "minutes": 450,
        "internalCost": 225.00,
        "revenue": 1200.00,
        "profit": 975.00
      }
    }
  }
}

Per-Client Profitability

Endpoint: GET /admin/profitability/:clientId?period=YYYY-MM

Returns the same structure scoped to a single client, plus an byAgent breakdown:

Field	Description
`clientId`	The client identifier
`period`	`YYYY-MM` or `all-time` if no period specified
`totalMinutes`	Total call minutes for the client
`totalInternalCost`	Total internal cost
`clientRevenue`	Revenue from the client's billing record
`profit`	`clientRevenue - totalInternalCost`
`profitMargin`	Profit as a percentage of revenue
`byAgent`	Per-agent breakdown of minutes and internal cost

Cost Tracking

Internal costs come from the usageHistory array on each client document. Each usage record tracks:

Period — the billing cycle (YYYY-MM)
Total minutes — call minutes consumed
Total internal cost — calculated from telephony rates, AI token usage, and other operational costs

The cost-calculator utility aggregates these records and reconciles them with billing revenue to produce profitability reports.

Margin Analysis

Profit margins are calculated as:

profitMargin = (revenue - internalCost) / revenue × 100

Key metrics to monitor:

Per-client margin — identifies clients where costs are eating into revenue
Per-agent cost — shows which agents consume the most resources relative to the bookings they generate
Platform margin — your overall agency health across all clients

If clientRevenue is not set on a client's billing record, profitability calculations will show 0 revenue and negative profit. Make sure each active client has billing.clientRevenue configured.

Ledger Reconciliation

The lifetime ledger on each BillingAccount is the reconciliation layer between Stripe events and local reporting:

Webhook-driven updates — Every charge, refund, and payment event refreshes the ledger in real time.
Daily reconciliation — An Agenda job queries Stripe for any events that may have been missed and repairs mirror/ledger drift.

If you notice ledger discrepancies:

node scripts/test-billing-engine.mjs --phase ledger

This verifies the billing engine's ledger logic without making live changes.

Setting Client Revenue

To ensure profitability reports are accurate, set the clientRevenue field on each client's billing record:

Open the client in Admin.
Go to the Billing tab.
Set the monthly revenue value.
This value is used in all profitability calculations.

Revenue can be updated at any time. The profitability endpoints recalculate on each request from the latest data.

Profitability & Revenue Reports

On this page