Documentation
Back to App

Usage Tracking and Overage

Usage Tracking and Overage

✅ Implemented - Usage tracking for SCORM sessions is implemented and accessible via the billing summary endpoint.

Learn how AllureLMS tracks usage, calculates overage, and manages metered billing for features like SCORM.

Overview

This guide covers:

  • Understanding usage tracking
  • Metered billing model
  • Viewing usage data
  • Overage calculations
  • Usage reports

Prerequisites

  • Active subscription with metered billing
  • Admin or super_admin role
  • Understanding of billing model

Understanding Usage Tracking

Metered Billing

AllureLMS uses metered billing for certain features:

  • Base Fee: Monthly subscription fee
  • Included Units: Units included in base fee
  • Overage: Additional units charged separately
  • Meter: What is being measured (e.g., SCORM sessions)

Current Metering

SCORM Sessions:

  • Each SCORM package launch = 1 unit
  • Tracked per tenant
  • Reset monthly with billing cycle

Viewing Usage

Via Web UI

  1. Navigate to Admin → Billing
  2. View usage dashboard
  3. See current period usage
  4. View overage (if any)

Via API

✅ Implemented - Usage data is included in the /api/billing/summary response from the scorm_tenant_usage table.

curl -X GET https://your-domain.com/api/billing/summary \
  -H "Authorization: Bearer <your-jwt-token>"

Requirements:

  • Admin or super_admin role required
  • Valid authentication token

Response:

{
  "plan": {
    "slug": "starter",
    "name": "Starter Plan",
    "meter": "scorm_sessions",
    "monthly_fee": 99.00,
    "included_units": 1000,
    "overage_unit_cost": 0.10
  },
  "status": "active",
  "usage": {
    "tenant_id": "tenant-uuid",
    "current_period_units": 1250,
    "included_units": 1000
  }
}

Note: Usage data comes from the scorm_tenant_usage table and tracks SCORM session launches per tenant.

Usage Calculation

How Usage is Tracked

SCORM Sessions:

  1. User launches SCORM package
  2. Session created in SCORM API
  3. Usage incremented in scorm_tenant_usage table
  4. Usage aggregated per billing period

Usage Aggregation

Usage is aggregated:

  • Per Tenant: All users in tenant contribute to usage
  • Per Period: Reset each billing cycle
  • Real-time: Updated as usage occurs

Overage Calculation

Overage Formula

Overage Units = Current Period Units - Included Units
Overage Cost = Overage Units × Overage Unit Cost

Example

Plan:

  • Monthly Fee: $99
  • Included Units: 1,000 SCORM sessions
  • Overage Cost: $0.10 per session

Usage:

  • Current Period: 1,250 sessions
  • Overage: 1,250 - 1,000 = 250 sessions
  • Overage Cost: 250 × $0.10 = $25.00

Total Bill:

  • Base Fee: $99.00
  • Overage: $25.00
  • Total: $124.00

Usage Reports

Current Period Usage

curl -X GET https://your-domain.com/api/billing/summary \
  -H "Authorization: Bearer <your-jwt-token>"

Historical Usage

# Note: Historical usage may require additional endpoints
# Check API reference for current implementation

SCORM Usage Details

✅ Implemented - The /api/scorm/packages/usage endpoint provides detailed SCORM usage statistics.

curl -X GET https://your-domain.com/api/scorm/packages/usage \
  -H "Authorization: Bearer <your-jwt-token>"

Requirements:

  • Admin or super_admin role required
  • Valid authentication token

Response:

{
  "usage": {
    "total_sessions": 1250,
    "current_period_sessions": 1250,
    "by_package": [
      {
        "package_id": "package-uuid",
        "package_title": "SCORM Package 1",
        "sessions": 500
      }
    ]
  }
}

Note: This endpoint aggregates SCORM session data from the scorm_sessions table.

Managing Usage

Monitoring Usage

  1. Regular Checks: Check usage weekly
  2. Set Alerts: (If available) Set usage alerts
  3. Track Trends: Monitor usage trends
  4. Plan Ahead: Anticipate usage spikes

Reducing Usage

  1. Optimize Content: Use fewer SCORM packages
  2. Combine Activities: Combine related content
  3. Cache Sessions: Reuse sessions when possible
  4. Review Necessity: Remove unused SCORM packages

Upgrading Plans

If consistently hitting limits:

  1. Review usage patterns
  2. Calculate overage costs
  3. Compare to next tier pricing
  4. Upgrade if cost-effective

Best Practices

Usage Management

  1. Monitor Regularly: Check usage weekly
  2. Set Budgets: Set usage budgets
  3. Track Trends: Understand usage patterns
  4. Optimize: Optimize content to reduce usage

Cost Optimization

  1. Right-Size Plan: Choose plan matching usage
  2. Minimize Overage: Stay within included units
  3. Review Periodically: Review plan quarterly
  4. Factor Overage: Include overage in budget

Troubleshooting

Usage Not Tracking

Problem: Usage not updating

  • Solution: Check SCORM session creation
  • Check: Verify usage tracking is enabled
  • Try: Review SCORM API logs

Incorrect Usage Count

Problem: Usage count seems wrong

  • Solution: Review usage calculation logic
  • Check: Verify session counting
  • Try: Contact support for audit

Overage Not Calculated

Problem: Overage not showing

  • Solution: Check billing period dates
  • Check: Verify overage calculation
  • Try: Wait for next billing cycle

Related Documentation

Next Steps

Next: Webhook Setup → Learn how to configure Stripe webhooks