Billing, Lifecycle & Subscriptions

Web Hosting integration in StackConsole CMP connects server-level cPanel operations with commercial billing rules. This page documents the complete service lifecycle: subscription tracking, invoice generation, plan upgrades with proration, overdue suspensions, unsuspensions, and service termination.

---

1. Subscriptions & Billing Integration

Customer Portal Path: /app/billing/summary and /app/billing/subscriptions

CMP tracks every active Web Hosting account as an independent commercial subscription:

• Service Name: Listed under the primary domain name (e.g., mybusiness.com).
• Active Subscriptions: Displays the hosting plan, billing cycle, renewal date, and recurring fee.

• Cost Reports: To review Web Hosting spend specifically, filter the cost breakdown by the WHM Cloud Provider. (Note: Filtering by CloudStack will display $0 for Web Hosting spend).

Commercial vs. Provisioning Distinction

CMP maintains a strict distinction between initial ordering and plan upgrades:

Action	Billing & Orchestration Order	Notes
Initial Purchase	validate_account → Generate Initial Invoice → Dispatch Async CreateHostingAccountJob	The commercial record is generated first; WHM infrastructure creation follows asynchronously.
Plan Upgrade	Validate Proration Delta → Call WHM changepackage → Generate Upgrade Invoice on Success	The infrastructure upgrade must succeed on WHM before the customer is invoiced for the prorated difference.

---

2. In-Place Plan Upgrades

Customer Portal Path: /app/web-hosting/{slug}/settings
Permission Required: hosting.accounts.upgrade-plan

Customers can upgrade their hosting plan at any time without data migration or downtime.

Upgrade Rules & Restrictions

1. Active State Only: The hosting account must be in Active status. Suspended or creating accounts cannot be upgraded.
2. Quota Comparison (Strict Upgrade Only): CMP only permits selecting a destination plan whose disk_quota_gb is strictly greater than the current plan's disk quota.
   • Selecting a plan with a lower or equal quota is blocked in the UI.
   • Attempting to submit a downgrade via API returns an HTTP 403 Forbidden response.
3. Proration Preview: Before confirming, the customer clicks Review & Upgrade to preview the prorated cost:

   POST /api/billing/summary/change-plan-preview

   • CMP calculates the unused balance of the current cycle and applies it toward the higher tier.
4. Execution Workflow:
   • The customer confirms the upgrade via POST /api/hosting/accounts/{slug}/upgrade-plan.
   • UpgradeHostingAccountQuotaJob is dispatched to the virtual-machine queue.
   • The worker calls WHM's changepackage API to update the cPanel account's package and quotas.
   • Upon successful infrastructure confirmation from WHM, CMP creates the prorated upgrade invoice, updates the subscription record, and pushes a real-time socket notification to the UI.

---

3. Disciplinary & Overdue Suspension

CMP enforces automated suspension policies when subscription renewal invoices remain unpaid.

Trigger	CMP Internal Action	WHM API Action	Visible Result
Overdue Invoice past Grace Period	invoke_suspension() dispatches SuspendHostingAccountJob	Calls suspendacct on WHM	Account status changes to Suspended. Portal displays a warning banner. Web server displays cPanel suspended page. SSO is disabled.
Invoice Paid / Balance Restored	revoke_suspension() dispatches UnsuspendHostingAccountJob	Calls unsuspendacct on WHM	Account status returns to Active. Banners clear. cPanel SSO and web traffic resume immediately.

Suspension Sequence

---

4. Cancellation & Service Termination

Customers and administrators can terminate a hosting service from the Customer Portal or Admin Client Management screens.

Cancellation Options

When a user initiates cancellation, CMP presents two options:

1. Immediate Termination:

   • The customer or admin requests immediate destruction of the hosting account.
   • The portal submits DELETE /api/hosting/accounts/{slug}.
   • CMP sets hosting_accounts.state = terminated.
   • TerminateHostingAccountJob is dispatched to the queue.
   • The worker invokes WHM's removeacct API, permanently deleting the cPanel virtual host, databases, emails, and /home/{user} directory.
   • The account is removed from the active hosting list.

2. End-of-Billing-Period Cancellation:

   • The service remains active and fully functional until the current paid billing cycle expires.
   • CMP flags the subscription as pending cancellation; automated renewal invoices are suppressed.
   • At the end of the billing period, the automated lifecycle cron triggers TerminateHostingAccountJob to destroy the account on WHM.

---

5. Billing Activity & Invoices

Every financial event associated with a Web Hosting service generates a formal invoice:

• Initial Setup: Invoiced at time of purchase.
• Recurring Renewal: Invoiced at the beginning of each billing cycle (e.g., monthly or annually).
• Plan Upgrades: Invoiced immediately for the prorated difference between plans.

Customers can download PDF receipts and view itemized statements directly from /app/billing/summary.

---

Next Steps

• Troubleshooting & Recovery
• General Billing & Rate Cards Documentation
• Disciplinary Policies