SaaS Billing & Subscription Management

1. Overview

The SaaS Billing module transforms Deprixa Plus from a single-tenant application into a fully managed multi-tenant platform. It enables the platform owner (Super Admin) to define subscription plans, manage organization wallets, and automate the entire billing lifecycle while organizations (Org Admins) subscribe to plans, recharge their wallets, and consume platform resources within their plan limits.

Core Business Model

The billing model follows a wallet-based subscription pattern:

• Organizations subscribe to plans that define their resource limits (shipments, users, branches, storage, API calls).
• Organizations recharge their wallets using Stripe, PayPal, or Paystack. The wallet acts as a prepaid balance.
• The system auto-debits the wallet when subscriptions renew. If auto-renewal is enabled and the wallet has sufficient balance, the subscription renews automatically with no manual intervention.
• If insufficient balance, the organization enters a grace period, then moves to read-only mode until the wallet is recharged and the subscription is renewed.

Role Responsibilities

2. SaaS Plans

Path: Admin > SaaS Dashboard > Plans

Route: /admin/billing/plans

Plans define the resource limits and feature access for each tier. The Super Admin creates, edits, and toggles plans from the SaaS Dashboard. Each plan can be activated or deactivated without deleting it — deactivated plans are hidden from the pricing page and cannot be assigned to new subscriptions, but existing subscribers remain on their plan until renewal.

Default Plans

Plan Feature Flags

Beyond numeric limits, each plan includes boolean feature flags that gate access to premium capabilities:

Billing Cycles

Each plan supports four billing cycles. Longer cycles offer savings that can be configured per plan:

Managing Plans

• Create: Click "New Plan" in the Plans section. Fill in name, slug, description, pricing per cycle, limits, and feature flags. Save to make the plan available.
• Edit: Click the edit icon on any plan row. Changes to limits apply to new subscriptions only; existing subscribers keep their current limits until renewal.
• Toggle: Use the active/inactive switch to hide a plan from the pricing page without deleting it. Existing subscriptions on a deactivated plan continue to function.

3. Wallet System

Path (Admin): Admin > SaaS Dashboard > Wallets

Path (Org): My Billing > Recharge

Routes: /admin/billing/wallets (Admin), /my-billing/recharge (Org)

Every organization has exactly one wallet. The wallet holds a monetary balance (in the platform's base currency) that is used to pay for subscriptions. The wallet is the central financial account for each tenant — all subscription payments are debited from the wallet, and all recharges credit the wallet.

How the Wallet Works

• Recharge: Organizations add funds via Stripe, PayPal, or Paystack. The payment gateway processes the charge and the system credits the wallet upon successful payment confirmation.
• Auto-Debit: When a subscription renews (either manually or via the daily cron), the subscription price is debited from the wallet balance.
• Manual Adjustments: Super Admins can manually credit or debit any organization's wallet from the admin panel (e.g., courtesy credits, corrections, refunds).

Wallet Transaction Types

All wallet movements are recorded in the saas_wallet_transactions table with full traceability:

Wallet Admin Panel

From /admin/billing/wallets, the Super Admin can:

• View all organization wallets with current balances
• Search and filter by organization name or balance range
• Click into a wallet to view the full transaction history
• Credit or debit a wallet with a reason/note (recorded in the transaction log)
• Export wallet transaction reports

4. Subscriptions

Path: Admin > SaaS Dashboard > Subscriptions

Route: /admin/billing/subscriptions

Subscriptions link organizations to plans with a defined billing cycle, start date, and expiration date. The Super Admin assigns, upgrades, downgrades, and cancels subscriptions from the admin panel.

Subscription Lifecycle

Every subscription moves through a well-defined lifecycle. The statuses are:

Lifecycle Flow Diagram

Trial ──expires──▶ Active (if paid)
                       │
                   expires_at reached
                       │
              ┌────────┴────────┐
              │                 │
        auto_renew=true    auto_renew=false
              │                 │
     wallet has funds?     ──▶ grace_period
       │           │               │
      YES          NO         grace days expire
       │           │               │
    renew ──▶   grace_period  ──▶ read_only
   (new cycle)     │
              grace days expire
                   │
              read_only

Auto-Renewal Process

The system runs a daily cron job at 01:00 server time via the Artisan command:

php artisan saas:check-subscriptions

This command performs the following checks for every active subscription:

• If expires_at has passed and auto_renew = true: Checks the organization's wallet balance. If sufficient, debits the wallet for the plan price, generates a new invoice, sets a new expires_at date, and sends a renewal confirmation notification.
• If expires_at has passed and wallet balance is insufficient: Moves the subscription to grace_period status. The grace period duration is configurable (default: 7 days). Sends an "insufficient balance" notification.
• If in grace_period and grace days have expired: Moves the subscription to read_only status. Sends a "subscription expired" notification.
• If auto_renew = false and expires_at has passed: Moves directly to grace_period, then to read_only after grace days expire.

Read-Only Mode Restrictions

When a subscription is in read_only status:

• Users can log in and browse all existing data (shipments, invoices, reports, etc.)
• Users cannot create new shipments or any new records
• Users cannot edit, update, or delete any existing records
• Users can access billing pages to recharge their wallet and reactivate
• Users can access their profile and log out
• A persistent banner is displayed explaining the read-only state and linking to the billing page

Admin Subscription Management

From /admin/billing/subscriptions, the Super Admin can:

• Assign: Select an organization, choose a plan and billing cycle, set the start date. The wallet is debited immediately.
• Upgrade/Downgrade: Change the plan for an active subscription. Prorated credit is calculated for the remaining days on the current plan.
• Cancel: Immediately ends the subscription and moves the organization to read-only status.
• Extend: Manually extend the expires_at date without charging (courtesy extension).

5. Invoices

Path: Admin > SaaS Dashboard > Invoices

Route: /admin/billing/invoices

SaaS invoices are automatically generated for every financial event — wallet recharges and subscription payments both produce invoices. The Super Admin can also generate manual adjustment and refund invoices.

Invoice Types

Invoice Statuses

Manual Payment Recording

The Super Admin can mark any invoice as paid manually from the invoice detail view. This is useful for wire transfers, cash payments, or other offline payment methods. When marking as paid, the admin provides:

• Payment date
• Payment method (free text, e.g., "Wire Transfer", "Cash", "Check")
• Reference number (optional)
• Notes (optional)

6. Payment Gateways (Wallet Recharge)

Organizations recharge their wallets through integrated payment gateways. Each gateway follows a redirect-based flow: the user initiates a recharge, is redirected to the gateway's hosted checkout, completes the payment, and is redirected back. The system verifies the payment via callback/webhook and credits the wallet.

Stripe Integration

PayPal Integration

Paystack Integration

Idempotency & Double-Credit Prevention

Every recharge transaction is assigned a unique reference ID before the user is redirected to the payment gateway. When the callback or webhook fires, the system checks whether a wallet transaction with that reference ID already exists. If it does, the credit is skipped. This prevents double-crediting in scenarios where both the redirect callback and the webhook fire for the same payment.

# Example reference ID format
saas_recharge_{org_id}_{timestamp}_{random}
# e.g., saas_recharge_42_1716825600_a1b2c3

Webhook Security Summary

7. Plan Limits Enforcement

Plan limits are enforced in real time whenever users attempt to create resources that are capped by their subscription plan. The enforcement is handled by the SaasUsageService class.

How Enforcement Works

• Shipment creation: Before a new shipment is saved, the system checks the organization's max_shipments limit against their current usage count for the active billing cycle. If the limit is reached, the creation is blocked with a clear error message: "You have reached your plan's shipment limit (X/X). Please upgrade your plan to create more shipments."
• User creation: Same pattern for max_users when inviting or creating new users.
• Branch creation: Same pattern for max_branches when adding new branches.
• API calls: API rate limiting enforced per day based on api_calls_daily. Returns HTTP 429 with a descriptive message when exceeded.
• Storage: File uploads checked against storage_gb. Upload rejected if total storage would exceed the plan limit.

Usage Reset Cycle

Shipment usage counters reset at the beginning of each billing cycle (based on the subscription's starts_at date). For example, if a subscription starts on January 15 with a monthly cycle, the shipment counter resets on February 15, March 15, and so on.

Usage Dashboard

The SaaS Dashboard shows a usage summary for each organization, including:

• Current shipment count vs. plan limit (with progress bar)
• Active users vs. plan limit
• Active branches vs. plan limit
• Storage used vs. plan limit
• API calls today vs. daily limit

# SaasUsageService check example (pseudo-code)
$usage = SaasUsageService::check($organization, 'shipments');
# Returns: { allowed: true, current: 342, limit: 500, remaining: 158 }
# Or:      { allowed: false, current: 500, limit: 500, remaining: 0 }

8. Subscription Status Middleware

The CheckSubscriptionStatus middleware is applied to all authenticated routes (except excluded paths). It enforces subscription-based access control at the HTTP level.

Middleware Behavior

Excluded Routes

The following routes are always accessible regardless of subscription status, even in read-only mode:

• GET * — All read operations (browse, view, export, download)
• /my-billing/* — All billing pages (recharge wallet, view invoices, manage subscription)
• /profile/* — User profile management
• /logout — Logout action
• /notifications/* — View notifications

Super Admin Bypass

Super Admin users bypass the CheckSubscriptionStatus middleware completely. They are never restricted by subscription status, as they are platform-level administrators, not organization-level users.

# Middleware registration in app/Http/Kernel.php
'check.subscription' => \App\Http\Middleware\CheckSubscriptionStatus::class,

# Applied to route groups
Route::middleware(['auth', 'check.subscription'])->group(function () {
    // All authenticated tenant routes
});

9. Notifications

The SaaS module sends automated notifications at every subscription lifecycle transition. Notifications are delivered via two channels: email (SMTP) and in-app (database notification with real-time push via WebSocket).

Notification Events

Email Templates

Each notification event has a corresponding email template using Laravel's Mailable system. Templates include the organization logo, plan details, action buttons (e.g., "Recharge Now"), and a direct link to the billing page.

10. Audit Logging

Every SaaS administrative operation is recorded in the audit_logs table, providing a complete audit trail for compliance and debugging purposes.

Logged Admin Operations

Logged System Events (Cron)

The saas:check-subscriptions cron command also logs its actions with the actor recorded as system:

# Audit log entry structure
{
  "event_type": "saas.wallet.credited",
  "actor_type": "user",        // or "system" for cron
  "actor_id": 1,
  "organization_id": 42,
  "payload": {
    "amount": 100.00,
    "reason": "Courtesy credit for downtime",
    "new_balance": 329.50
  },
  "ip_address": "192.168.1.100",
  "created_at": "2026-05-10T14:30:00Z"
}

11. Pricing Page

Route: /pricing (public, no authentication required)

The pricing page is a public-facing page that displays all active SaaS plans with their features, limits, and pricing. It serves as the primary marketing and conversion tool for the platform.

Page Behavior

• Unauthenticated visitors: See all active plans with a "Get Started" button that links to the registration page.
• Authenticated users (Org Admin): See all active plans with their current plan highlighted (badge: "Current Plan"). Other plans show "Upgrade" or "Downgrade" buttons linking to /my-billing.
• Billing cycle toggle: Users can switch between Monthly, Quarterly, Semiannual, and Annual pricing views. Prices update dynamically.
• Feature comparison: A feature comparison table at the bottom shows all plan limits and feature flags side by side.

Customization

The pricing page content is driven entirely by the saas_plans table. To customize:

• Edit plan names, descriptions, and pricing from the Admin Plans page
• Toggle plans active/inactive to show or hide them
• Set a plan as "recommended" to highlight it with a special badge
• Customize the page heading and subheading from Settings

12. Database Tables

The SaaS module introduces five dedicated tables plus leverages two existing tables for configuration and notifications.

saas_plans

Stores all subscription plan definitions.

saas_subscriptions

Tracks each organization's subscription to a plan.

saas_wallets

One wallet per organization, holding the prepaid balance.

saas_wallet_transactions

Complete ledger of all wallet credits and debits.

saas_invoices

Invoice records for all SaaS financial events.

Related Existing Tables

13. Permissions

The SaaS module defines five granular permissions that control access to different areas of the SaaS admin panel. These permissions are assigned to roles from the Users & Roles settings page.

SaaS Permission Matrix

Default Role Assignments

14. Configuration

The SaaS Billing module requires specific configuration in both the environment file and the edition configuration.

Environment Variables (.env)

# Edition (must be Plus for SaaS features)
APP_EDITION=Plus

# Stripe Configuration
STRIPE_KEY=pk_live_xxxxxxxxxxxx
STRIPE_SECRET=sk_live_xxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

# PayPal Configuration
PAYPAL_CLIENT_ID=AxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxB
PAYPAL_SECRET=ExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxF
PAYPAL_MODE=live   # or "sandbox" for testing

# Paystack Configuration
PAYSTACK_PUBLIC_KEY=pk_live_xxxxxxxxxxxx
PAYSTACK_SECRET_KEY=sk_live_xxxxxxxxxxxx

# SaaS Settings
SAAS_GRACE_PERIOD_DAYS=7
SAAS_TRIAL_DAYS=14
SAAS_DEFAULT_PLAN=free

Edition Configuration (config/edition.php)

Both feature flags must be set to true for the SaaS module to be active:

// config/edition.php
return [
    // ... other edition flags ...
    'saas_billing' => true,   // Enables SaaS plans, subscriptions, invoices
    'saas_wallet'  => true,   // Enables wallet system and payment gateways
];

Cron Job Setup

The subscription lifecycle cron must be registered in your server's crontab or in Laravel's task scheduler:

# Option 1: Direct crontab entry
0 1 * * * cd /path-to-your-project && php artisan saas:check-subscriptions >> /dev/null 2>&1

# Option 2: Laravel Scheduler (in app/Console/Kernel.php)
$schedule->command('saas:check-subscriptions')->dailyAt('01:00');

# Then ensure the Laravel scheduler itself runs every minute:
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Configuration Checklist

• Set APP_EDITION=Plus in .env
• Set saas_billing and saas_wallet to true in config/edition.php
• Configure at least one payment gateway (Stripe, PayPal, or Paystack) in .env
• Run database migrations: php artisan migrate
• Run the SaaS seeder: php artisan db:seed --class=SaasPlansSeeder
• Register the cron job: saas:check-subscriptions daily at 01:00
• Assign SaaS permissions to admin roles from Users & Roles settings
• Create or verify default plans exist in the Plans section
• Test the pricing page at /pricing to confirm plans are visible
• Test a wallet recharge flow end-to-end with the configured payment gateway