Skip to content
Shahid Malla

WHMCS Custom Reports: Built-In Reports and Writing Your Own

WHMCS ships 37 reports across seven sections. This guide checks them against the WHMCS 9.1 documentation, then covers the /modules/reports file format, a Capsule query, the drawChart call and report permissions.

· Published · 12 min read · 8 steps

A WHMCS custom report is a plain PHP file in /modules/reports/ that fills a $reportdata array, which WHMCS renders as a titled table with an optional chart. WHMCS 9.1 ships 37 reports across General, Billing, Income, Clients, Support, Exports and System, so check that list first, then copy the closest stock file under a new, unique, lowercase name.

A custom report is a report file you add yourself instead of one of the files WHMCS ships. It sits in the same /modules/reports/ directory as the stock reports, sets the same handful of variables, and appears in the Admin Area under Reports as soon as the file is on the server. It is the smallest piece of WHMCS development there is: no module structure, no activation screen, no database table.

Everything below is checked against the WHMCS 9.1 documentation, read on 20 November 2026. The WHMCS documentation home page lists 9.1 as the General Availability release, with 9.0 and 8.13 on Long-Term Support. The Custom Reports page in the 8.13 documentation gives the same file rules and the same report format.

Five-step workflow for a WHMCS custom report: check the shipped reports, copy a file, swap in a Capsule query, add a chart, then limit it by admin role
The order this guide follows, which is the order I build a WHMCS report in. Source: shahidmalla.com.

Which built-in WHMCS reports already answer your question?

Probably one of 37. I counted the Reports page in the WHMCS 9.1 documentation on 20 November 2026: 37 distinct reports in seven sections, at Reports > Reports. Some of the custom report requests I get turn out to be for a number already sitting there under a name the client did not recognize.

Bar chart of the 37 reports WHMCS 9.1 ships by section: Clients 8, Exports 7, General 6, Billing 5, Income 5, Support 5 and System 1
Reports shipped with WHMCS 9.1, counted from the Reports page on 20 November 2026. Source: docs.whmcs.com.
SectionReports shippedWorth knowing about
General6Daily Performance, Monthly Orders, Promotions Usage, SSL Certificate Monitoring, Product Suspensions, Disk Usage Summary
Billing5Aging Invoices, Credits Reviewer, Direct Debit Processing, Sales Tax Liability, VAT Moss
Income5Annual Income Report, Income Forecast, Income by Product, Monthly Transactions, Server Revenue Forecasts
Clients8Top 10 Clients by Income, Customer Retention Time, Client Statement, Clients by Country, Client Sources, New Customers, Affiliates Overview, Domain Renewal Reminder Emails
Support5Support Ticket Replies, Ticket Feedback Scores, Ticket Feedback Comments, Ticket Ratings Reviewer, Ticket Tags
Exports7Filtered exports of clients, domains, invoices, services and transactions, a JSON export of one client, and PDF Batch
System1Smarty Compatibility Report

Sales Tax Liability appears in both the Billing and Income lists; I counted it once. Three reports in that list are worth knowing by name before you commission anything. Income Forecast projects each month on the assumption that every active service and domain renews on its next due date, splitting quarterly, semi-annual, annual and biennial products evenly across the year, and excluding addons and billable items. Customer Retention Time gives the average days between registration and termination by product and billing cycle. Server Revenue Forecasts sets income by billing cycle for each server, in the base currency, against the monthly cost you entered for that server, to estimate the annual gross profit per box.

The Exports section is the other thing people miss. Five of its entries build an export with up to five filters of your own, which covers a good share of the one-off lists asked for as "a custom report". Reports export from the Tools menu in the upper-right corner, as CSV or a printer-friendly view.

Where do WHMCS report files live?

In /modules/reports/ inside your WHMCS directory, shipped unencoded so you can read them. The Custom Reports page states the rules plainly, and they are short:

  • Upload your file to /modules/reports/. There is no install step and no settings screen.
  • The report name must be unique, all lowercase, and contain only letters and numbers, a to z and 0 to 9. It must start with a letter.
  • Your report then appears at Reports > More and in the list at Reports > Reports.
  • This applies to self-hosted installs only. The same page says WHMCS Cloud does not currently support this customization method.

That last point decides the whole project. The page gives no exception and no workaround for Cloud, so a reporting requirement on Cloud becomes an export, a dashboard widget, or an external tool fed by the API.

How do you copy a stock report and change it?

Copy the file under a new name, then edit the copy. WHMCS published the worked example itself in a post titled Customizing WHMCS Reports, dated 15 February 2021, turning the stock Top 10 report into a Top 25:

  1. Find top_10_clients_by_income.php in /modules/reports/.
  2. Copy it to a new filename, top_25_clients_by_income.php.
  3. Change $reportdata["title"] and $reportdata["description"] to match.
  4. Change the line that limits the result set, ->take(25), which in that file was line 28.
  5. Save and reload the Reports page.

Copying matters more than it looks. Updating WHMCS lists WHMCS-supplied modules under ~/whmcs/modules/ among the files an update overwrites, and says directly that editing those files means updating overwrites your changes. The documented method is a uniquely named copy of any module you customize. An edit made in place survives until the next update, then goes away, often unnoticed until month-end. My WHMCS upgrade and update guide covers the rest of that check.

How do you write a WHMCS custom report from scratch?

Set six variables. The documentation gives the full skeleton, and everything else in a report file is ordinary PHP that fills $reportdata["tablevalues"].

VariableWhat it does
$reportdata["title"]The report title, shown at the top of the page and in the report list
$reportdata["description"]The description under the title
$reportdata["headertext"]Text displayed above the table of data, and where a chart is placed
$reportdata["tableheadings"]An array of column headings
$reportdata["tablevalues"][]One array per row, with values matching the headings
$data["footertext"]Text displayed below the table of data

Note the last row. The sample on the Custom Reports page writes the footer as $data["footertext"], not $reportdata["footertext"]. I have copied it as published; if your footer never appears, that line is the first one to compare against a shipped report.

For the data itself, use Capsule. The Interacting with the Database page says the older select_query(), update_query(), insert_query() and full_query() helpers are deprecated and may be removed in a later version, and asks third-party developers to use Capsule for all new database work. Plenty of older tutorials still use the old helpers, so a report copied from one can be built on functions that are on the way out.

<?php

use WHMCS\Database\Capsule;

$reportdata["title"] = "Clients Added This Month";
$reportdata["description"] = "Counts client accounts created in the current month, grouped by country.";
$reportdata["tableheadings"] = array("Country", "Clients");

try {
    $rows = Capsule::table('tblclients')
        ->selectRaw('country, count(*) as total')
        ->whereRaw('YEAR(datecreated) = YEAR(CURDATE())')
        ->whereRaw('MONTH(datecreated) = MONTH(CURDATE())')
        ->groupBy('country')
        ->orderBy('total', 'desc')
        ->get();

    foreach ($rows as $row) {
        $reportdata["tablevalues"][] = array($row->country, $row->total);
    }
} catch (\Exception $e) {
    $reportdata["headertext"] = "Report query failed: " . $e->getMessage();
}

Three things in there are deliberate. Capsule throws an exception on failure, so the documentation asks you to wrap calls in try/catch; without it a bad column name gives staff a blank page instead of a message. Capsule escapes input, so no manual slashes. And Capsule select calls return rows as stdClass objects, which is why the loop reads $row->country and not an array key.

Table and column names are the part to be careful with. The Custom Reports page tells you to work from a current stock report file, so confirm a column name against the stock file that already touches the same data rather than trusting any example, including this one.

How do you add a chart to a WHMCS report?

Call drawChart and assign the result to the header text. WHMCS uses the Google Charts API to generate graphical reports, and the Custom Reports page gives the call and its argument order:

$reportdata["headertext"] = $chart->drawChart('Pie', $chartdata, $args, '300px', '100%');

The arguments, in order, are the chart type, the data, the configuration that defines the visual display such as color or legend position, then height and width. Height defaults to 300px and width to 100%, so the last two are optional.

Add a chart when the reader needs a shape rather than a number: a trend over months, or a split across products. For a ranked list of 25 clients it adds nothing. Build the table first, then draw the chart from the same data.

Who can see a WHMCS report, and how do you limit that?

By default, any admin role group whose permissions include View Reports can open every report in the system. The Reports page also says you can configure admin roles to view only selected reports, at Configuration > System Settings > Administrator Roles.

Do that before a new report goes live. Access is granted per report, not per row, so a file written for the owner is readable by every role that holds View Reports unless you restrict it. Two cases deserve the extra minute:

  • Money. Income by Product, Server Revenue Forecasts and Top 10 Clients by Income tell a support agent what the business earns and from whom.
  • Personal data. The Client export builds a JSON export for one client, and you pick the data points, up to and including notes and the activity log. Treat that as a data protection control, not a reporting convenience.

How do you test a custom report before staff rely on it?

On a staging copy, against numbers you can verify another way. A report that is quietly wrong is worse than no report, because nobody checks it twice. This is the list I work through:

  • Run php -l yourreport.php before uploading. A parse error in /modules/reports/ shows up as a broken page, not a helpful message.
  • Check the file name against the rules: lowercase, letters and numbers only, starting with a letter.
  • If the page is blank, enable Display Errors in the Other tab at Configuration > System Settings > General Settings, per Enable Error Reporting, reproduce it, then turn it off again. That page warns the setting shows verbose errors to anyone on the system, customers included.
  • Reconcile one period against a stock report. If your month does not match Monthly Transactions or Income by Product, find out why before anyone reads it.
  • Cap the rows, and time the query on production-sized data rather than a demo database with 40 clients.
  • Export it to CSV from the Tools menu and confirm the columns survive the trip.

The Blank or Partially-Rendered Pages page attributes blank pages to a fatal PHP error, missing files or ionCube Loader, and names syntax errors in custom modules, hooks and templates among the causes. It also suggests removing custom files temporarily and adding them back one at a time, which is how you prove a new report is the culprit.

When should you not write a custom report?

When the answer belongs somewhere other than the Reports page. A report file is a good fit for a table staff open on demand and a poor fit for everything else.

Decision flow: use the stock report if it exists, no report files on WHMCS Cloud, build a widget for the dashboard, use the API, otherwise write a report file
The four questions I ask before adding a file to /modules/reports/. Source: shahidmalla.com, from my own scoping routine.

In words: if a shipped report already answers it, use that. If the install is WHMCS Cloud, a report file is not available. If the number should greet staff on the dashboard, build a widget. If another system needs the same data, go through the API. Only what is left needs a report file.

What you needWhat to buildWhy
A table or chart staff open when they want itA report file in /modules/reports/No install step, exports to CSV, restricted by admin role
A figure visible on the Admin DashboardA widget on the AdminHomeWidgets hookWidgets extend AbstractWidget and support caching through $cache and $cacheExpiry, plus a $requiredPermission
The same data inside another systemThe WHMCS API, internal or externalThe API Index lists no action that runs a report; GetClients, GetInvoices, GetOrders and GetTransactions return the data
A filtered one-off list for a spreadsheetThe Exports section at Reports > ReportsUp to five filters of your own, with no code to maintain

Two more limits. A report runs as an Admin Area page request, so a query across years of invoice rows meets PHP's execution time and memory limits like any other page; aggregate in SQL instead of summing rows in PHP. And the Reports documentation describes no way to run a report on a schedule or email it, so "the owner gets revenue by product every Monday" is a cron task, not a report file. My WHMCS hooks guide and WHMCS API guide cover those routes.

What else do people ask about WHMCS custom reports?

Can I create custom reports on WHMCS Cloud?

No. The Custom Reports page says the information applies to self-hosted installations only, and that WHMCS Cloud does not currently support this customization method. On Cloud, use the shipped reports and the Exports section, or pull the data out through the API.

Will a WHMCS update overwrite my custom report?

A uniquely named file of your own is not a WHMCS-supplied file, but an edited stock report is. The Updating WHMCS page lists WHMCS-supplied modules under ~/whmcs/modules/ among the files updates overwrite. Copy under a new name, keep the file in version control, and check it after each update.

Why does my custom report not appear in the list?

Check the file name first: unique, all lowercase, letters and numbers only, starting with a letter, and in /modules/reports/. If the name is right and the page loads blank, that is a fatal PHP error rather than a missing report, so enable Display Errors and read the message.

Can I export a WHMCS report to CSV?

Yes. Open the report, click Tools in the upper-right corner, and choose the CSV export or the printer-friendly view. The documentation gives this for the reports list as a whole, and your own report appears in that list, so test the export on it once before staff rely on it.

Is there an API command to run a WHMCS report?

Not in the published list. I read the API Index on 20 November 2026 and no action in it runs a report file. For an external dashboard, query what the report queries, using the actions that return clients, invoices, orders and transactions.

If you want a report built, reviewed for correctness, or turned into something your billing team can trust, that is WHMCS custom module development work, and it sits alongside the rest of my WHMCS development services with a free scoping call of about 30 minutes and a written quote within one business day.

Last reviewed 20 November 2026. Disclosure: I am a freelance WHMCS developer and I sell custom WHMCS report and module development, so I am not neutral. I am CTO at ElySpace, a freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI. File paths, variable names, report lists and permissions come from the WHMCS 9.1 documentation, the WHMCS developer documentation and the WHMCS blog as I read them on that date.

Share this article

Shahid Malla

Written by

Shahid Malla

Freelance WHMCS developer and web designer with 13+ years of client work. CTO at ElySpace, freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.

Got a project like this?

Tell me what you need and I will send a written quote within one business day.