A major WHMCS update involves more than accessing new features. It can affect existing modules, server requirements, and everyday hosting operations. Therefore, understanding the changes before upgrading is essential.
WHMCS 9.1 introduces several improvements, including invoice immutability, credit and debit note management, unattended automatic updates, PHP 8.4 support, and a preview of the new Iris Admin Area theme.
The release also comes at an important time for users still running WHMCS 8.13, as its approaching End-of-Life date makes upgrade planning more urgent. In this guide, we’ll explore what’s new in WHMCS 9.1, its compatibility requirements, potential upgrade challenges, and the steps to follow for a smooth transition without unnecessary downtime or disruptions.
What’s New in WHMCS 9.1?
WHMCS 9.1 is a General Availability release introduced on October 20, 2026. It brings changes to billing, payment processing, security, administration, and software maintenance.
Here are the major updates worth understanding before upgrading.
1. Invoice Immutability and Credit/Debit Notes
One of the most important additions in WHMCS 9.1 is the new Invoice Immutability setting. Previously, businesses could manage invoice adjustments through different billing actions. The new release provides a more structured approach to preserving published invoices and recording financial changes.
The setting is available under:
Configuration > System Settings > General Settings > Invoices
Administrators can select from three compliance options:
- Full compliance: Published invoices cannot be edited, and credit and debit notes are generated to record adjustments.
- Immutability disabled, billing notes enabled: Administrators can edit published invoices while continuing to generate credit and debit notes.
- Both disabled: Published invoices can be edited, but the system does not generate credit and debit notes.
The default setting is Full compliance. WHMCS 9.1 also introduces a dedicated credit and debit note management interface. Administrators can manage these records under Billing > Credit and Debit Notes, while clients can view and download their notes through the Client Area.
A new sortable Balance column also makes it easier to identify the remaining balance on invoices. For hosting businesses, these changes are particularly relevant when managing refunds, cancellations, applied credits, and accounting records. However, administrators should review their existing invoicing processes before changing the compliance setting.
2. Unattended Automatic Updates
Keeping WHMCS updated can become another administrative task, particularly for businesses managing multiple installations.
WHMCS 9.1 introduces unattended automatic updates for maintenance releases. Administrators can schedule updates weekly or monthly and choose a suitable day and time.
The feature also includes:
- An Update History table under Utilities > Update WHMCS.
- Automatic backups of the files being replaced.
- Restoration of those files if an update fails.
- Email notifications to administrators after each update attempt.
There is one important distinction: unattended updates apply to maintenance releases only. Major and minor version upgrades still require a manual update. This gives administrators more control over routine maintenance without removing the need to plan larger upgrades.
3. New Iris Admin Area Theme (Preview)
WHMCS 9.1 introduces Iris, a preview of its new Admin Area template. The theme features a modernised interface and improved navigation. However, it is important to understand that Iris is currently a technology preview, not a mandatory replacement for the existing Admin Area theme.
Administrators can try it by navigating to:
Account > My Account > Template > Iris
WHMCS has indicated that Iris is planned to become the default Admin Area template in a future release. For now, businesses can explore the new interface without treating it as a compulsory part of their upgrade.
4. Automatic Market Connect Account Registration
WHMCS 9.1 also changes how installations connect with a WHMCS Marketplace account. If an existing installation is not linked to a Marketplace account, WHMCS now attempts to create one automatically during the upgrade. Eligible upgrades also receive a $50 starter credit.
Administrators with the Full Administrator role receive a message in the Admin Area and an email explaining the registration outcome. For new installations, connecting a WHMCS Marketplace account is now required before accessing the Admin Area for the first time. The Getting Started Wizard no longer allows users to skip these MarketConnect steps.
5. Stripe Dynamic Payments Improvements
The release makes migrating from older Stripe payment gateway modules easier. Businesses can migrate stored payment methods from the legacy Stripe, Stripe ACH, and Stripe SEPA modules to Stripe Dynamic Payments without requiring customers to enrol again.
The migration option is available under:
Configuration > System Settings > Payment Gateways
WHMCS 9.1 also supports redirect payment methods through Stripe Dynamic Payments for authenticated clients. These include PayPal, Amazon Pay, iDEAL, Bancontact, and BLIK. The older Stripe, Stripe ACH, and Stripe SEPA gateway modules are deprecated, so businesses using them should review their migration plans.
6. Improved Password Requirements
Security is another area receiving attention in WHMCS 9.1. The release introduces stronger password requirements for administrators and clients:
- Passwords must contain at least one letter and one number.
- The default minimum password length is 12 characters.
- The system prevents users from reusing their most recent four passwords by default.
Administrators can adjust the minimum password length and password reuse limit through the Security tab under General Settings.
Configuration → System Settings → General Settings → Security
These changes help businesses strengthen account security while making password policies easier to manage.
WHMCS 8.13 EOL: Short Notice and Community Feedback
The WHMCS 8.13 End-of-Life announcement became an important discussion among existing users, particularly those who had not yet moved to WHMCS 9.x. The concern was not simply about another version reaching its support deadline. It was also about the time available to prepare for the transition.
A WHMCS Community discussion highlighted that users had previously seen the 8.13 support date listed as TBD. When the date changed to December 1, 2026, some users reported that they had received roughly one month’s notice.
Users also raised concerns about unresolved issues in WHMCS 9 and requested more time to prepare. Following this feedback, WHMCS staff responded in the community discussion and extended WHMCS 8.13 support until December 31, 2026.
What Does This Mean for Existing WHMCS Users?
As of November 2026, the official WHMCS support schedule lists:
| WHMCS version | Support tier | Anticipated EOL |
| WHMCS 9.1 | General Availability | September 30, 2027 |
| WHMCS 9.0 | Long-Term Support | December 31, 2026 |
| WHMCS 8.13 | Long-Term Support | December 31, 2026 |
This means WHMCS 8.13 users still have a limited window to plan their upgrade. However, rushing into a new release without checking compatibility can create more problems than it solves.
If you are still using WHMCS 8.13, start by reviewing your server requirements, payment gateways, custom modules, and themes. You should also test the upgrade in a separate environment before changing your live installation.
Remember, once a version reaches EOL, WHMCS no longer maintains it or releases updates for it. Staying on a supported version is important for receiving bug fixes, security updates, and technical assistance.
Our recommendation: Hosting providers should avoid delaying their upgrade planning until the final days of the support lifecycle. Proper compatibility testing and migration preparation take time, particularly for installations with extensive customizations.
WHMCS 9.1 Compatibility Requirements
Before upgrading, check whether your existing hosting environment meets the WHMCS 9.1 requirements. A server that runs an older WHMCS version successfully may not necessarily be ready for 9.1. According to the official release documentation, the requirements for self-hosted installations are:
| Dependency | Minimum requirement | Recommended |
| PHP | 8.2 | 8.4 |
| ionCube Loader | 15.0.0 | 15.0.0 |
| MySQL | 5.2 | 8.0 |
Two requirements deserve particular attention:
- Upgrade ionCube Loader to version 15.0.0 before upgrading WHMCS to 9.1.
- Upgrade WHMCS to 9.1 before moving your server to PHP 8.4.
Changing this order can cause serious problems during the upgrade. Also, check the PHP extensions required by WHMCS and confirm that your server configuration meets the official system requirements.
Important Consideration for Older Installations
If you are upgrading directly from WHMCS 8.12 or an earlier version, there is an additional payment gateway consideration. WHMCS 9.1 does not include PayPal Basic and PayPal Checkout. Older installations may still contain these gateway files.
If you upgrade directly from 8.12 or earlier to 9.1, you must remove or replace these modules first. Otherwise, PHP 8.2 and higher may be unable to decode the older encoded files, resulting in an HTTP 500 error in the Admin Area.
WHMCS also recommends reviewing the upgrade path for older EOL versions rather than treating every upgrade as a direct version jump.
Modules, Themes and Order Forms Compatibility
System requirements are only one part of upgrade preparation. Your existing WHMCS modules, themes, and order forms also need attention.
Many hosting providers rely on third-party extensions for server provisioning, payment processing, domain management, billing automation, and customer experience. If even one important extension stops working after an upgrade, it can interrupt regular business operations.
Here is what to check.
1. WHMCS Modules
Start by identifying all the modules currently installed in your WHMCS environment.
Pay particular attention to:
- Provisioning modules: Check whether server creation, suspension, termination, and service upgrades work correctly.
- Payment gateway modules: Verify payment processing, callbacks, refunds, and recurring billing.
- Domain registrar modules: Test domain registration, renewal, transfer, and synchronisation.
- Addon modules: Review custom billing tools, reporting extensions, notifications, and administrative functions.
Do not assume that a module compatible with WHMCS 9.0 will automatically work with 9.1. Check the developer’s compatibility statement and available updates before proceeding.
2. WHMCS Themes
Custom themes can also require attention during an upgrade. If your business uses a customised client area, compare its templates with the changes introduced in WHMCS 9.1.
Check whether the theme developer has released an updated version. Also, remember that Iris is an optional Admin Area preview. It is separate from your customer-facing theme.
3. Order Form Templates
Order forms influence how customers browse products, configure services, and complete purchases.
After upgrading, test your existing order forms for:
- Product and service selection.
- Configurable options and pricing.
- Shopping cart functionality.
- Checkout and payment processing.
- Service upgrades and cancellations.
WHMCS recommends keeping custom themes and order form templates in their own directories rather than modifying default templates directly. Updates can overwrite changes made to default files.
A practical tip: Maintain a compatibility checklist for every important extension. Record its installed version, developer confirmation, required update, and testing status. This makes future WHMCS upgrades considerably easier to manage.
Step-by-Step Upgrade Guide
Now that you understand the changes and compatibility requirements, let’s look at the actual upgrade process. WHMCS recommends preparing your installation before starting an update. The following steps are particularly useful for self-hosted installations.
Step 1: Review the WHMCS 9.1 Release Notes
Before making any changes, read the official WHMCS 9.1 Release Notes. Pay attention to:
- New features and functionality.
- Removed or deprecated modules.
- Changes to payment gateways.
- PHP and ionCube requirements.
- Template and API changes.
If you are upgrading from an older version, also review the release notes for intermediate versions. This helps identify changes that might affect your existing configuration.
Step 2: Check Server Compatibility
Next, verify your current PHP version, ionCube Loader, MySQL version, and required PHP extensions. Make sure ionCube Loader 15.0.0 is installed before starting the WHMCS 9.1 upgrade.
If you plan to move to PHP 8.4, complete the WHMCS upgrade first. You can also use the PHP Version Compatibility interface under Utilities > System to check whether your encoded files are compatible with PHP 8.4.
Step 3: Check Modules and Customisations
Create an inventory of your installed modules, themes, and custom code. Contact the respective developers if compatibility information is unavailable. Pay special attention to payment gateways and provisioning modules because they directly affect customer transactions and service delivery. Do not remove or replace working extensions without understanding their role in your current setup.
Step 4: Create a Complete Backup
This is one step you should never skip. Before upgrading, create backups of:
- Your complete WHMCS installation directory.
- Your WHMCS database.
- Custom modules and themes.
- Custom templates and configuration files.
Store the backups somewhere separate from your live installation. A complete backup gives you a recovery option if something goes wrong during the upgrade.
Step 5: Test the Upgrade in a Staging Environment
Avoid testing a major update directly on your production installation. Set up a testing environment that closely matches your live WHMCS installation. Use it to check:
- Admin and client login.
- Product ordering and checkout.
- Payment gateway operations.
- Invoice generation and credit adjustments.
- Domain registration and management.
- Automated provisioning and cron jobs.
- Support ticket submission.
- Custom module functionality.
If something breaks, you can investigate it without affecting your customers.
Step 6: Upgrade to WHMCS 9.1
Once everything is ready, you can proceed with the upgrade. The recommended method is the Automatic Updater. Follow these steps:
- Log in to your WHMCS Admin Area.
- Navigate to Utilities > Update WHMCS.
- Click Check for Updates if necessary.
- Review the available update.
- Select Update Now.
- Follow the instructions displayed during the update.
- Allow the update and database operations to finish.
WHMCS displays a maintenance notice during an automatic update. Customers and other administrators are informed that an upgrade is in progress.
The updater also has certain technical requirements, including at least 128 MB of PHP memory, 250 MB of free disk space, and the necessary PHP configuration settings.
Step 7: Verify the Installation
Once the upgrade is complete, do not assume everything is working just because the Admin Area opens. Perform a complete functionality check. Log in as an administrator and a test client. Place a test order, check invoice generation, verify payment gateway connections, and test important provisioning functions. Also verify that domain registration and renewal processes, automated provisioning and suspension, cron job execution, email notifications, custom hooks and integrations, and client area themes and order forms are functioning correctly after the upgrade.
Also, review Configuration > System Health for warnings or errors.
Monitor your installation for at least the next 24 hours, paying attention to cron execution, payment callbacks, and customer activity.
Common Upgrade Issues
Even after careful preparation, some installations may experience issues during or after an upgrade. Here are a few situations worth watching.
| Common issue | What to check |
| HTTP 500 error | Check PHP compatibility and legacy PayPal gateway files. |
| ionCube errors | Confirm that ionCube Loader 15.0.0 is installed. |
| Update not appearing | Verify that the server uses a compatible PHP version. |
| Module functionality breaks | Check developer compatibility and module updates. |
| Theme display issues | Review customised templates and updated theme files. |
| Payment problems | Test gateway configuration, callbacks, and payment methods. |
| Upgrade remains incomplete | Review updater errors, file permissions, and database access. |
A Few More Things to Remember
- Log in to your WHMCS Admin Area.
- Navigate to Utilities > Update WHMCS.
- Click Check for Updates if necessary.
- Review the available update.
- Select Update Now.
- Follow the instructions displayed during the update.
- Allow the update and database operations to finish.
For more complicated issues, consult the official WHMCS documentation or contact technical support with the relevant error details.
How WGS Can Help?
Upgrading WHMCS is not always a straightforward process, especially when your installation depends on multiple custom modules, integrations, and themes. This is where technical assistance can make the transition easier.
WHMCS Global Services (WGS) provides WHMCS-related modules, themes, integrations, and custom development services for hosting businesses.
Depending on your requirements, its services can help with the following:
- Custom WHMCS Development: Adapt existing functionality or develop custom solutions around your business requirements.
- Module Development: Develop and extend WHMCS modules for provisioning, automation, payment processing, and other operational requirements.
- Theme Development: Customise WHMCS themes and improve the customer-facing experience.
- Order Form Development: Build or redesign WHMCS order forms templates to support your checkout requirements.
WGS also offers ready-made WHMCS products, including server automation modules, billing extensions, and client area themes. If you are planning an upgrade to WHMCS 9.1, you can discuss your existing setup and compatibility requirements before making changes to your live installation.
Explore the available solutions at WHMCS Global Services.
Conclusion
WHMCS 9.1 brings several valuable improvements to billing management, security, payment processing, and routine maintenance. Features such as invoice immutability and unattended automatic updates can simplify administration and help hosting businesses manage their operations more efficiently.
However, upgrading requires careful preparation. Hosting providers should review their existing modules, themes, payment gateways, and server configurations to avoid compatibility issues. With WHMCS 8.13 approaching its EOL, planning the transition early is equally important.
A well-prepared upgrade helps businesses maintain smooth operations, minimise disruptions, and take full advantage of the improvements WHMCS 9.1 offers.
Reference:
https://docs.whmcs.com/releases/9-1/9-1-release-highlights/
https://docs.whmcs.com/releases/9-1/9-1-release-notes/