Laravel Hierarchical Billing

A Laravel package for managing hierarchical account billing — supporting subscription, per-event, and sub-account billing models within a single tenant.

Built from real-world experience running a production SaaS platform.

The Problem

Most billing packages handle simple user → subscription flows. But what if your SaaS has:

• A main organization paying a monthly subscription
• Sub-accounts (departments/branches) each with their own billing
• Per-event charges on top of the subscription

No existing package handles this out of the box. This one does.

Features

• ✅ 3 billing models in one package: Subscription, Per-Event, Sub-Account
• ✅ Hierarchical accounts — main accounts with unlimited sub-accounts
• ✅ Polymorphic — attach billing to any model (User, Organization, Team, etc.)
• ✅ Transaction tracking — full audit trail for every charge
• ✅ Trial & Grace periods — configurable out of the box
• ✅ Gateway agnostic — works with any payment gateway
• ✅ Laravel 10, 11, 12 & 13 support

Installation

composer require mahmoud-elboshy/laravel-hierarchical-billing

Publish and run migrations:

php artisan vendor:publish --tag="hierarchical-billing-migrations"
php artisan migrate

Publish config (optional):

php artisan vendor:publish --tag="hierarchical-billing-config"

Usage

1. Add the trait to your model

use MahmoudElBoshy\HierarchicalBilling\Traits\HasBilling;
use MahmoudElBoshy\HierarchicalBilling\Traits\HasSubAccounts;

class Organization extends Model
{
    use HasBilling, HasSubAccounts;
}

2. Subscription Billing

// Subscribe an organization to a plan
$organization->subscribe('plan_pro', [
    'ends_at' => now()->addMonth(),
]);

// Check subscription status
$organization->isSubscribed(); // true

// Cancel subscription
$organization->cancelSubscription();

3. Per-Event Billing

// Charge for a specific event
$billingAccount = $organization->billingAccount;

$billingAccount->billedEvents()->create([
    'event_reference' => 'EVENT-001',
    'event_type'      => 'conference',
    'amount'          => 500.00,
    'currency'        => 'SAR',
    'billed_at'       => now(),
]);

4. Sub-Account Billing

// Create a sub-account under the main organization
$subAccount = $organization->createSubAccount([
    'metadata' => ['department' => 'Marketing'],
]);

// Check sub-account count
$organization->activeSubAccountsCount(); // 1

// Check if limit reached
$organization->hasReachedSubAccountLimit(); // false

5. Billing Status Checks

$organization->isSubscribed();             // true/false
$organization->billingAccount->isActive(); // true/false
$organization->billingAccount->onTrial();  // true/false
$organization->billingAccount->hasExpired(); // true/false
$organization->billingAccount->isSubAccount(); // true/false

Configuration

// config/hierarchical-billing.php

return [
    'default_model'      => 'subscription', // subscription | per_event | sub_account
    'currency'           => 'SAR',
    'sub_account_limit'  => null,           // null = unlimited
    'trial_days'         => 14,
    'grace_period_days'  => 3,
];

Database Schema

Roadmap

• Artisan commands for billing management
• Webhook handling helpers
• Invoice generation
• Usage-based billing model
• Proration support

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

License

MIT License. See LICENSE for details.

Author

Mahmoud El Boshy — Senior Backend Engineer
GitHub · LinkedIn