MUST Read Before Launching a WHMCS Site

MUST Read Before Launching a WHMCS Site

Back   Posted on 24 june 2020 / Updated on 21 january 2021
Reading time 15 minutes

I started to use WHMCS in 2008. As I look back and look at the situation today, I know that something isn't quite right. I recall WHMCS as an old-school and durable washing machine. The model we have now is better but has bugs and "features" that do more harm than good.

I don't want to be misunderstood. I still think that WHMCS is the best software to start an hosting business. The alternatives to WHMCS are still mediocre but things can change. Especially if WHMCS keeps shooting itself in the foot with every release.

With this in mind, WHMCS v8 is coming. I have opinions like everyone else. In this post I want to share my thoughts with you. I advise you that my wishlist for WHMCS v8 is unusual. It doesn't include typical requests that range from the App to templates.

I'm a programmer that digs down into the code and faces problems that the average user is not aware of. What's sad is that what I worry about slips under the radar of WHMCS staff and community. Over the years I found critical bugs and issues that are still part of the software. I created WHMCS modules to address them but some issues can't be resolved.

Too many Releases

Let's start our journey. In recent years WHMCS adopted a software development philosophy that emphasized the importance of early and frequent releases. This philosophy aims to increase quality because frequent releases:

  • Help to conform the software to the users' requirements
  • Allow feedback between developers and users
  • Help to provide bug-free releases

In my humble opinion, this doesn't happen in WHMCS. The «release early, release often» approach is a problem for small and medium size enterprises. They can't keep up with this schedule. A release of WHMCS goes from beta to end of life at the speed of light. Even for developers like me staying up to date is difficult.

As for bugs, sometimes it feels like no one is testing new features. WHMCS has gradually accumulated a number of bugs to the point where it's even hard to say if they still exist. The fact that WHMCS pumps out frequent releases to add feature that no one asked for, makes things worse which brings us to our other problem.

Judging from what we see on the official forum and blog, WHMCS cares about users' feedback. I respectfully disagree. Like it or not, they already know what is going to change. Even critical bugs and important requests are forgotten for years. I think they base their job more on their partners' needs than on customers ones.

This all contributes to users having difficulties to upgrade WHMCS. That's why we started to provide upgrading service for WHMCS.

The Problem with Orders

WHMCS doesn't preserve customer details upon order creation. It may not seem a big deal but it is, especially for domain registrations. Let's suppose a customer transfers 100 domains with the following registrant details:

Fiorenza Panicucci
Via Callicratide 24
IT - Italy

As you know, it may take some hours/days before all transfers complete. In the meantime the customer updates his or her details like follows:

Fiorenza Panicucci
Via Callicratide 24
IT - Italy

Soon after, this same customer proceeds to transfer 100 more domains placing a new order. At this point we have 2 orders each one with 100 domain transfers. They're both linked to the same customer. We would all expect WHMCS to process the order as follows:

  • First order uses email address
  • Second order uses

WHMCS has other plans and uses for both. That's because it doesn't store customer details when the order is placed. It means that registrant details are different from what customer expects. Ironically the reason why customer placed two orders was exactly because he had to use different details.

The consequences of this action are distruptive due to the following reasons:

  • Customers have no idea that you are using wrong details
  • Updating registrant details could cost money and precious time
  • You expose your business to potential lawsuits

This was just an extreme example. Image what happens on a daily basis on your WHMCS while you don't suspect anything. Before you think of using sub-accounts, this doesn't solve the issue. It would require a book just to explain the reasons. The problem also extends to API functions. Only WHMCS can implement a solution doing the following:

  • Contact details must be "snapshotted" when the order is placed to preserve changes
  • DomainTransfer and DomainRegister API commands should accept full registrant details (firstname, lastname...) and not just an ID

It's not that difficult but WHMCS staff and community have other priorities. Maybe template updates are more important than preventing lawsuits.

WHMCS Billing Lacking

WHMCS billing is not that good. I'd say that most parts are incomplete while other are completely missing. This has been a hallmark of WHMCS since its first release but that's fine. I know from experience that billing is a whole different story. The rules are always changing and differ even in the same country.

It is understandable that WHMCS staff is not interested in finding a way through this jungle. Every step you take opens new beginnings and endless possibilities. It's clear that this is not their focus. They don't explicity say so, but action hooks existit to let us create solutions for our billing needs.

It was 2014 when we launched Billing Extension, a module created to address the billing lacks of WHMCS. At the moment of writing, we released 209 updates as we keep implementing new concepts. That's a lot of work that never ends. I'm fine with that but I cannot stand when WHMCS ruins everything making absurd decisions.

Dear WHMCS, if billing is not your focus, will you kindly stop making things worse? There's no solution for the issues I'm going to describe and I'm not someone who gives up easily. I have already reported these bugs to WHMCS but it seems that no one cares. But a thread about the color of a button receives their full attention.

What disturbs me the most, is that such problems are unknown to WHMCS community. They blame WHMCS for not updating the App or for other silly reasons. All that while under their noses there's a billing disaster.

Hopefully one day WHMCS staff will stumble upon this post to fix their software. Frankly this possibility scares me a bit. It is not uncommon for WHMCS to handle problems in ways that make things worse. I kind of lost faith in them when it comes to billing. Sometimes it looks like they have no idea of what they're doing.

Automated Upgrades and Downgrades is Bugged

I'm talking about Upgrades/Downgrades functionality of WHMCS. As the name suggests, it is used by customers for configurable options changes. Sadly the way it works causes billing errors. Before I can describe the issue, first I need to explain a billing concept.

WHMCS doesn't handle "Add Funds" invoices correctly. What it does is considered illegal in most countries. When a customer decides to add funds, WHMCS issues an invoice with no tax causing more than one problem.

Step Description

Add Funds

It's 2020, VAT rate is 22% and WHMCS issues and invoice that looks like follows:

  • Subtotal: 100 €
  • VAT: 0 €
  • Credit: 0 €
  • Total Due: 100 €

The customer pays 100 € and receives a credit balance of 100 €. This causes the first billing error. VAT must be charged every time you receive a payment. An invoice with no VAT applied is an error unless there was a specific reason (eg. VIES)

Credit Usage

Part of this credit is used to renew a service that costs 10 € / year. Here is the resulting invoice:

  • Subtotal: 10 €
  • 22% VAT: 2.20 €
  • Credit: 12.20 €
  • Total Due: 0 €

Now we have another problem. Invoice amount is zero hence no payment is required. In some countries this kind of invoice not only is unnecessary but can't be registered


The remaining balance is 87.80 € that we use for subsequent renewals:

  • In 2021 WHMCS deducts 12.20 € including 22% VAT
  • In 2022 VAT rate changes from 22% to 23% and WHMCS deducts 12.30 €
  • In 2023 WHMCS deducts 12.30 € including 23% VAT

This is wrong on many levels. First off you need to wait 2028 before the VAT charging takes place for a payment that was sent 8 years before. Second. The customer is subjected to different VAT rates, rules and fiscal years for a payment sent in 2020

To overcome this absurde issue, we created a feature to charge VAT on Add Funds invoices. Instead of creating this mess, we issue an "Add Funds" invoice that includes VAT like follows:

  • Subtotal: 100 €
  • VAT: 22 €
  • Credit: 0 €
  • Total Due: 122 €

As for renewals, there's an option that can be used to suppress unnecessary invoices. Now that you know the basics, let's go back to Upgrades/Downgrades. This feature is based on refunding unused resources for the current billing cycle. I know that it sounds complicated so let's make an example.

Today I order a hosting account with backup that costs 50 € / year. Few minutes later I change my mind. I want to get rid of Backup and activate Antispam that has the same price. Here is the resulting invoice:

  • Subtotal: 50 €
  • 22% VAT: 11 €
  • Credit: 50 €
  • Total Due: 11 €

Total Due and VAT are both wrong. This is how it should be:

  • Subtotal: 0 €
  • 22% VAT: 0 €
  • Credit: 50 €
  • Total Due: 0 €

The Total Due is zero hence the invoice should be suppressed since it is unnecessary. Let's make another example. This time instead of -50 € and +50 € we have -10 € and +50 €. This is what WHMCS does:

  • Subtotal: 50 €
  • 22% VAT: 11 €
  • Credit: 10 €
  • Total Due: 51 €

While it should have been this:

  • Subtotal: 40 €
  • 22% VAT: 8.8 €
  • Credit: 10 €
  • Total Due: 38.8 €

As if it wasn't enough, calculations are inconsistent. This is what happens when I upgrade my service.

WHMCS says that I have to pay 68.93 €. Let's click continue to get the invoice.

What the actual f***? Total Due is now 92.40 €. There's a difference of 23.47 €. How is it possible? Simple. WHMCS calculates "Total Due" using two different formuals for the same purpose.

Upgrade Formula Invoice Formula
Total Due = (Total Debited - Total Credited) + 22% Total Due = (Total Debited + 22%) - Total Credited
(163.2 - 106.7) + 22% = 68.93 (163.2 + 22%) - 106.7 = 92.40

There are no action hooks to correct numbers, you can trust me. The only solution is to turn off this buggy feature. WHMCS knows this problem. I opened a thread and reported the bug in a ticket. They say it will be fixed someday in the future but after so many years the bug still exists.

Subscription-Based Overpayments

The problem with recurring payments causing overpayments is frustrating. Here is another table to describe what we have.

Step Description


It's 2020, VAT rate is 22% and I register a domain for 12.20 € (10 € + 2.20 € VAT)

I decide to pay the resulting invoice creating a subscription payment. Invoice number is #2020-500


Now it's 2021. I can't even remember what I ate yesterday. How can I remember after 12 months that the domain will be renewed automatically? I don't want to risk losing my domain so I send the payment manually


PayPal or any other payment gateway doesn't know that I have already sent the payment. The subscription payment arrives as normal few days later. As the invoice is already paid, the subscription payment is an overpayment, and so is credited to my account

This is a billing horror. First off WHMCS adds the overpayment on the invoice of the previous year meaning that invoice #2020-500 moves from 2020 to 2021! Not only it moves an invoice from a fiscal year to another but it also changes the amount. That's crazy.

Invoice balance is now 20 € but there is still VAT to charge. WHMCS assumes that every year VAT rate is the same. It also assumes that customers never change their entity type (individual, sole proprietorship, company etc.). Every country of the world disagree.

Things get worse in case the customer doesn't use his/her credit balance (the overpayment) before next renewal. WHMCS in fact automatically renews all subsequent invoices with such credit. This doesn't stop PayPal from sending the subscription payment that every year results in a new overpayment.

I've seen WHMCS installation where the same invoices were moving from 2012 to 2013, 2014, 2015 etc. It's a never ending loop that never stops till someone removes the credit or kills the subscription. The good news is that Billing Extension can issue invoice for overpayments. This way WHMCS doesn't change and move invoices from previous years.

The bad news is that there's a type of overpayment you can't stop and correct. Read next chapter to learn more.

Invoice Items Disappearing

In past in WHMCS it was possible for customers to accidentally renew domains tiwice. On one hand there was WHMCS issuing the proforma for renewal X days before domain expiration. On the other the customer was free to place a renewal order.

Today it is still possible to have two proforma concerning the renewal of the same domain. The difference is that once a proforma is paid, WHMCS removes the domain from the other proforma. This can cause the following problem.

What we have here is an invoice that can't be explained. Amounts are wrong and your accountant can't register the invoice. How can a customer send a payment that is higher than total due? Simple. Originally this proforma had two invoice items:

  • Silver -
  • Domain Renewal -

The amount of "Domain Renewal" was exactly 12.20 € (10 € + 2.20 € VAT). What is happening is that WHMCS removed this item from invoice because the customer renewed the domain from another proforma (the one customers generate from Domains > Renew Domains).

A payment gateway like PayPal doesn't know anything about how WHMCS hanles invoices. It only knows that it must send a subscription payment. That's how you end up with an invoice that makes no sense. In other words, WHMCS "solved" the issue of customer paying twice by creating a new problem that is even worse.

There's more. WHMCS removes Domain Renewal item even from invoices that have no other item. That means the resulting invoice will be empty with no invoice item, Subtotal and Total Due... but it is still a real invoice with a real payment.

This "feature" can't be turned off and doesn't leave any trace apart from an entry in Activity Log. Long story short, we moved from customers risking to send duplicated payments to billing errors. What's sad is that duplicated payment can still occur. It makes no sense.

Weird Calculations

The following invoice is about a payment and a full refund. Numbers are wrong.

12.20 plus -12.20 equals zero. WHMCS has a different opinion. The result is negative balance of 12.20 €. Ironically if invoice status changes to Unpaid, the customer owes you 12.20 €.

This scenario is reproducible by simply adding a negative transaction to invoice. It's not an hack but something that is fully supported by WHMCS. Sadly it doesn't consider the sign. Amounts are summed together as absolute numbers as if the "-" doesn't mean anything. How the heck am I supposed to deal with negative amounts?

Inconsistent workflow

WHMCS has no idea of how to properly deal with things like VIES and ignores concepts like Split Payment and Business Type. That's fine as long as they give us tools to add all the missing pieces but sometimes we have to face problems that make no sense. Let me give you an example involving Tax Exempt.

Tax Exempt is a very important billing concept that depends on a wide variety of checks that WHMCS ignores. We managed to "teach" WHMCS how to deal with Tax Exempt performing all the necessary checks with Billing Extension via "ClientEdit" action hook every time a client is edited but here's the thing.

Changing Tax Exempt status from Profiles tab triggers "ClientEdit" hook as normal. If you do the same from Yes/No toggle of the above screenshot, the hook doesn't run hence we can't perform any check. This will result into billing errors. The good news is that we reported the problem to WHMCS and it will be fixed in v8 Beta 4 but there are so many other problems still open.

SEO and CMS functionalities

Here we go again with WHMCS staff messing up things that are not their focus. Let me make one thing perfectly clear. It's alright to improve the software but WHMCS has a strange way of doing it.

The world evolved to Structured Data but WHMCS still lacks a sitemap that was first introduced in 2005. News and blog existed even before WordPress was released in 2003. What do we have in WHMCS? Announcements and KB that seem to come from the 90's. In 2020 WHMCS is celebrating image uploads in KB articles but we still miss things like:

You can't improve anything at this speed. It's like trying to carry water in a sieve. When WHMCS introduces a new SEO or CMS functionality, technology has already surpassed the improvement by years. As if it wasn't enough, these very little accomplishments fail in production. Let me give you an example.

WHMCS implemented SEO-Friendly URL aiming to improve WHMCS SEO but they achieved the opposite. Their version of SEO-Friendly URLs causes duplicate content and penalties on search results.

In conclusion they are slow, always behind in tech and don't have a great knowledge of SEO and CMS. Why wasting time to add features that make things worse? Leave this matter to any CMS like WordPress or to a WHMCS integration.

Navbar and Sidebar

I'm not the best developer in the world but certain things in WHMCS are tortuous. If you want a taste of it, look at the following flowchart for action hooks. It's a little ironic but this is what I'm subjected to on a daily basis to solve problems.

But I'm not complaining about action hooks. They let you change the way WHMCS works so it is understandable that they are complex to use. What I dislike is when complexity reaches areas that should be simple. I'm talking about navbar and sidebars.

It's not acceptable that the average WHMCS-user should be learning PHP to customize navigation and sidebars. This is something that should be done from an editor with a GUI or at least via template. I don't get why adding a menu requires a developer.

Welcome, Wrong Name

Let's say you have an account with the following sub-accounts.

Now try to log in to clientarea with Mark White sub-account and this is how WHMCS welcomes you.

No matter what sub-account you use. For WHMCS you are always "Anna", the first sub-account in the list.

Comments (0)

Speak Your Mind Cancel Reply