WF-111: Agency Consolidated Billing

Overview

This workflow manages consolidated billing for agencies and resellers who manage multiple client organizations (child tenants). It aggregates usage across all child tenants, applies agency-specific pricing (markups or discounts), generates consolidated invoices, and provides detailed usage attribution for client billing.

Trigger: Monthly billing cycle (1st of month) + On-demand invoice generation Duration: ~30-60 seconds (depends on child tenant count) Related Workflows: WF-002 (Subscription), WF-024 (Payment Method), WF-025 (Failed Payment)

Prerequisites

For agency consolidated billing:

Agency account with agency_billing_enabled = true
At least one child tenant linked to agency
Agency payment method on file
Billing contact configured

Agency Hierarchy

Agency (Parent Tenant)
├── Client A (Child Tenant)
│   ├── 5 Pro licenses
│   └── 2 Workstations
├── Client B (Child Tenant)
│   ├── 10 Pro licenses
│   └── 1 Workstation
└── Client C (Child Tenant)
    └── 3 Pro licenses

Billing Models

Model	Description	Use Case
Passthrough	Agency pays exactly what clients use	MSP model
Markup	Agency adds percentage markup	Reseller model
Fixed Price	Agency pays fixed per-seat rate	Volume discount
Hybrid	Base + usage with markup	Enterprise reseller

Workflow Diagram

Step-by-Step Narrative

Step 1: Identify Agency Accounts

Node: Agency Scanner
Type: PostgreSQL Query
Schedule: 1st of month, 00:00 UTC
Actions:
- Queries tenants with billing_type = 'agency_consolidated'
- Retrieves agency billing configuration
- Gets list of linked child tenants
- Filters to active agencies only

Step 2: Aggregate Child Tenant Usage

Node: Usage Aggregation
Type: Usage Service
Actions: For each child tenant:
1. License Usage:
  - Count active licenses by type (Pro, Enterprise)
  - Calculate license-days for partial months
  - Track seat utilization percentage
2. Workstation Usage:
  - Sum workstation hours by tier (Standard, Power, AI)
  - Calculate compute costs
3. API Usage:
  - Aggregate API calls by endpoint category
  - Apply tiered pricing if applicable
4. Storage Usage:
  - Calculate document storage (DMS)
  - Calculate workstation persistent storage

Step 3: Calculate Child Subtotals

Node: Per-Client Calculation
Type: Pricing Engine

Actions: For each child tenant:

subtotal = (
  (license_count × license_unit_price) +
  (workstation_hours × hourly_rate) +
  (api_calls_over_quota × per_call_rate) +
  (storage_gb × storage_rate)
)

Stores subtotal for attribution report
Tracks usage breakdown for client billing

Step 4: Apply Agency Pricing

Node: Agency Pricing Rules
Type: Pricing Engine

Actions: Based on agency billing model:

Passthrough Model:

agency_total = sum(child_subtotals)

Markup Model:

agency_total = sum(child_subtotals) × (1 + markup_percentage)

Fixed Price Model:

agency_total = total_seats × fixed_per_seat_rate

Volume Discount Model:

agency_total = sum(child_subtotals) × (1 - volume_discount)

Applies any negotiated discounts
Calculates agency commission (if applicable)

Step 5: Generate Consolidated Invoice

Node: Invoice Generation
Type: PostgreSQL + Stripe
Actions:
1. Create Invoice Record:
  - invoice_type: consolidated
  - billing_period: previous month
  - total_amount: calculated total
  - currency: agency's billing currency
2. Create Line Items:
  - One line item per child tenant
  - Details: tenant name, usage summary, subtotal
  - Reference to detailed usage report
3. Attach Usage Report:
  - PDF with per-client breakdown
  - CSV export for agency's billing system
  - API call logs (optional)

Step 6: Process Payment

Node: Stripe Charge
Type: Stripe API
Actions:
- Creates Stripe invoice with line items
- Applies agency's default payment method
- For large invoices (>$10,000):
  - Sends preview for approval first
  - Waits for confirmation before charging
- Handles payment result:
  - Success: Mark paid, send receipt
  - Failed: Trigger retry workflow (WF-025)

Step 7: Attribution Reporting

Node: Client Billing Report
Type: Report Generator
Actions:
- Generates detailed report for agency:
  - Per-client cost breakdown
  - Usage metrics by category
  - Suggested client invoice amounts (with markup)
- Formats available:
  - PDF summary
  - CSV detailed export
  - JSON for API integration
- Stores in agency's billing portal

Step 8: Notifications

Node: Billing Notifications
Type: Notification Service
Actions:
- To Agency Billing Contact:
  - Consolidated invoice PDF
  - Payment receipt (if successful)
  - Attribution report attachment
- To Agency Admin:
  - Monthly billing summary email
  - Link to billing dashboard
- To Child Tenant Admins (optional):
  - Usage summary (no pricing)
  - Managed by agency preference

Agency Billing Portal Features

Feature	Description
Dashboard	Overview of all child tenant costs
Invoice History	All consolidated invoices with PDFs
Usage Analytics	Charts of usage trends by client
Client Reports	Downloadable reports for client billing
Markup Settings	Configure per-client or global markup
Payment Methods	Manage agency payment methods

Error Handling

Error	Code	Resolution
No Child Tenants	400	Link at least one child tenant
Payment Failed	402	Update payment method, retry
Usage Data Missing	500	Contact support, manual reconciliation
Currency Mismatch	400	All children must use agency currency
Invoice Disputed	409	Submit dispute via support

API Endpoints

Method	Endpoint	Description
GET	`/api/v1/agency/billing/summary`	Current period summary
GET	`/api/v1/agency/billing/invoices`	List all invoices
GET	`/api/v1/agency/billing/invoices/{id}`	Invoice details
GET	`/api/v1/agency/billing/invoices/{id}/pdf`	Download PDF
GET	`/api/v1/agency/billing/attribution`	Per-client breakdown
POST	`/api/v1/agency/billing/preview`	Preview next invoice
PATCH	`/api/v1/agency/billing/settings`	Update billing config

Configuration Options

Setting	Default	Description
`billing_model`	passthrough	Pricing model to use
`markup_percentage`	0	Markup for reseller model
`volume_discount`	0	Discount for volume
`notify_child_admins`	false	Send usage to clients
`auto_charge`	true	Auto-charge on invoice
`large_invoice_threshold`	10000	Require approval above this
`report_format`	pdf	Default export format

Overview​

Prerequisites​

Agency Hierarchy​

Billing Models​

Workflow Diagram​

Step-by-Step Narrative​

Step 1: Identify Agency Accounts​

Step 2: Aggregate Child Tenant Usage​

Step 3: Calculate Child Subtotals​

Step 4: Apply Agency Pricing​

Step 5: Generate Consolidated Invoice​

Step 6: Process Payment​

Step 7: Attribution Reporting​

Step 8: Notifications​

Agency Billing Portal Features​

Error Handling​

API Endpoints​

Configuration Options​

Related Documentation​