Usage-Based Billing

Usage-based billing charges organizations based on how much they consume. Metrics are recorded throughout the billing period and reported to the payment gateway for invoicing.

Plan Configuration

Usage billing uses the TYPE_METERED plan type with a meter_key field that identifies which metric drives billing:

Plan::create([
    'name'      => 'Pay As You Go',
    'type'      => Plan::TYPE_METERED,
    'meter_key' => 'api_calls',
]);

UsageRecord Model

Usage data is stored in the usage_records table via the UsageRecord model:

UsageRecord {
    organization_id   // Organization being billed
    metric            // Metric name (e.g. "api_calls", "storage_gb")
    amount            // Numeric quantity recorded
    meta              // JSON object for additional context
    recorded_at       // Timestamp of the usage event
}

Recording Usage

Record usage from anywhere in your application using the static helper:

UsageRecord::record($orgId, 'api_calls', 1);

// With optional metadata
UsageRecord::record($orgId, 'storage_gb', 0.5, [
    'file' => 'report.pdf',
    'action' => 'upload',
]);

Usage API

Organization members can view their usage through the API:

GET /api/usage?period=30d    # Last 30 days
GET /api/usage?period=7d     # Last 7 days
GET /api/usage?period=today  # Today only

The UsageController returns totals per metric and a daily time series for charting:

{
    "totals": {
        "api_calls": 12450,
        "storage_gb": 8.3
    },
    "series": [
        { "date": "2026-03-15", "api_calls": 1200, "storage_gb": 0.2 },
        { "date": "2026-03-16", "api_calls": 980, "storage_gb": 0.1 }
    ]
}

Admin Usage Dashboard

The AdminUsageController provides platform-wide usage visibility for super admins:

• Aggregate usage summary across all organizations
• Filter by organization to view individual consumption
• Top organizations per metric (e.g. highest API call consumers)

GET /api/admin/usage                    # Platform-wide summary
GET /api/admin/usage?org_id=123         # Filter by organization
GET /api/admin/usage/top?metric=api_calls  # Top consumers