Knowledgebase

Introduction

Keeping WHMCS up to date is important for security, performance, and compatibility. New releases often include security fixes, bug fixes, improvements, and new features.

This guide explains how to safely update an existing WHMCS installation to the latest stable version.

Before starting, make sure your server meets the requirements of the new WHMCS version. You should also check whether your existing templates, addons, payment gateways, and other modules are compatible with the update.

Follow the steps below to complete the upgrade safely.

1. Check Your Current WHMCS Version

First, identify which WHMCS version is currently installed.

1. Log in to your WHMCS Admin Area.

2. Navigate to the admin dashboard.

3. Check the current WHMCS version, usually displayed in the admin interface or system information.

Write down the current version so you can confirm the upgrade later.

Also identify the version you want to install.

2. Review WHMCS Release Notes and Changelog

Before downloading the new release, review the official WHMCS release notes and changelog.

Official resources:

• Release Notes: https://go.whmcs.com/2733/release-notes

• Changelog: https://go.whmcs.com/2737/change-log

Take a moment to review the changes included in the target release.

Pay attention to:

• New features and improvements.

• Security fixes.

• Bug fixes.

• PHP version requirements.

• Database changes.

• Removed or deprecated functions.

• Changes affecting templates and modules.

• Known issues that may affect your installation.

If you are upgrading from an older or End-of-Life version, check whether WHMCS requires any intermediate upgrade steps.

Do not assume that every older WHMCS version can be upgraded directly to the latest release.

3. Check PHP Version Compatibility

WHMCS requires a supported PHP version. Before upgrading, check whether your current PHP version is supported by the target WHMCS release.

Check PHP version through SSH

Connect to your server and run:

php -v

Check available PHP versions on cPanel/WHM

ls -1 /opt/cpanel/ | grep '^ea-php'

Check available PHP versions on CloudLinux

ls -1 /opt/alt/ | grep '^php'

Check the PHP version assigned to your WHMCS domain

For cPanel/WHM servers:

1. Log in to WHM.

2. Navigate to Software → MultiPHP Manager.

3. Find the domain where WHMCS is installed.

4. Check the PHP version assigned to that domain.

Important: The PHP version shown by the php -v command may be different from the PHP version used by your website.

Always check the actual PHP version assigned to the WHMCS domain.

If your current PHP version is not supported by the target WHMCS release, you may need to upgrade PHP before proceeding.

Check the requirements for the exact WHMCS version you plan to install:

https://docs.whmcs.com/

4. Check ionCube Loader Compatibility

WHMCS uses ionCube-encoded files, so ionCube Loader must be installed and compatible with the PHP version used by your WHMCS installation.

Check ionCube Loader for the default PHP version

php -v | grep -i ioncube

Check ionCube Loader for all cPanel EA-PHP versions

for php in /opt/cpanel/ea-php*/root/usr/bin/php; do
    echo "===== $php ====="
    "$php" -v | grep -i ioncube
done

Check ionCube Loader for CloudLinux Alt-PHP versions

for php in /opt/alt/php*/usr/bin/php; do
    echo "===== $php ====="
    "$php" -v | grep -i ioncube
done

What should you check?

• ionCube Loader is installed for the PHP version assigned to WHMCS.

• The installed Loader version meets the requirements of the target WHMCS release.

• The Loader supports the installed PHP version.

• ionCube is enabled for website PHP.

• ionCube is enabled for CLI PHP if required by WHMCS cron jobs.

Updating ionCube Loader

If your current Loader version is outdated or incompatible:

1. Check which Loader version is required.

2. Download the appropriate Loader from the official ionCube website.

3. Install or update it using the correct method for your server.

4. Verify that the correct PHP configuration loads ionCube.

5. Restart relevant services if necessary.

6. Check again to confirm that ionCube is loaded successfully.

Official download:

https://www.ioncube.com/loaders.php

Important: Updating ionCube Loader does not automatically make every third-party encoded module compatible with a newer PHP version. Check compatibility with each module developer.

5. Check PHP Extensions

Make sure all required PHP extensions are installed and enabled.

Commonly required or recommended extensions include:

• cURL

• GD

• IMAP

• JSON

• PDO

• PDO MySQL

• Reflection

• XML

• OpenSSL

• ionCube Loader

Check installed PHP extensions

php -m

Check important PHP settings

php -i | grep -E \
'memory_limit|max_execution_time|max_input_vars|upload_max_filesize|post_max_size'

Make sure the PHP configuration meets the requirements of the target WHMCS release.

You can also check the website's PHP configuration through WHM MultiPHP Manager or CloudLinux PHP Selector.

If necessary, create a temporary phpinfo() file to check the website PHP environment. Remove it immediately after checking.

6. Check Existing Templates, Addons and Modules

Before updating WHMCS, check whether your existing templates, addons, and modules support the new version.

This is especially important if your installation uses custom-developed or third-party extensions.

Client Area Templates

Check:

• Whether the active template supports the target WHMCS version.

• Whether an updated version is available from the template developer.

• Whether custom template modifications are compatible.

• Whether Smarty template changes affect the existing design.

• Whether the client area works correctly with the new version.

Order Form Templates

Check:

• Product configuration.

• Domain search.

• Domain registration.

• Checkout process.

• Order submission.

• Custom order form modifications.

Addon Modules

Review all installed addon modules.

For each addon, confirm that:

• It supports the target WHMCS version.

• It supports the required PHP version.

• The developer provides an updated release if necessary.

• No deprecated WHMCS functions are being used.

Payment Gateway Modules

Check all installed payment gateways.

Make sure the following functions continue to work:

• Payment initiation.

• Payment callbacks and webhooks.

• Transaction verification.

• Invoice status updates.

• Refund processing.

• Recurring payments.

Server Provisioning Modules

Check all server-related modules, including:

• cPanel/WHM.

• DirectAdmin.

• Plesk.

• Virtualizor.

• SolusVM.

• Custom provisioning modules.

Verify that account creation, suspension, unsuspension, termination, and other provisioning actions are supported.

Domain Registrar Modules

Check all installed registrar integrations.

Verify domain registration, renewal, transfer, nameserver updates, and other registrar functions.

Custom Hooks and Integrations

If your WHMCS installation uses custom PHP hooks or external integrations, review them before upgrading.

Check for:

• Deprecated WHMCS functions.

• Changes to WHMCS APIs.

• PHP compatibility issues.

• Changes to database structure.

• Incompatible third-party libraries.

• Custom modifications to WHMCS core files.

Important: If any critical template, addon, payment gateway, or module is incompatible with the target version, obtain an updated version before proceeding.

Do not assume that existing customizations will continue working automatically after the upgrade.

7. Check PHP and Third-Party Module Compatibility

If you also need to upgrade PHP, check all existing integrations before changing the PHP version.

Older PHP versions may still be required by some custom addons or ionCube-encoded modules.

Before upgrading PHP, verify:

1. The target WHMCS version supports the new PHP version.

2. ionCube Loader supports the new PHP version.

3. Existing encoded modules support the new PHP version.

4. Custom hooks and PHP scripts are compatible.

5. Payment gateways and server modules support the new environment.

6. Required PHP extensions are available.

If both WHMCS and PHP need major upgrades, plan the upgrade carefully.

Where possible, test the changes on a staging installation first.

8. Create a Complete Backup

Before upgrading WHMCS, create a complete backup of both the application files and the database.

You can use any of the following methods:

• cPanel Backup Wizard.

• phpMyAdmin.

• cPanel File Manager.

• SSH/CLI.

Make sure the backup is complete and stored somewhere safe before continuing.

Option 1: Full Backup Using cPanel Backup Wizard

This is one of the easiest ways to back up your complete hosting account.

1. Log in to your cPanel account.

2. Navigate to Files → Backup Wizard.

3. Click Back Up.

4. Select Full Backup.

5. Choose the backup destination.

6. Enter an email address for completion notifications, if required.

7. Click Generate Backup.

Wait until the backup process finishes.

Once completed, download the backup archive and store it somewhere safe.

A full cPanel backup can include your website files, databases, email accounts, and other account-related data.

Note: Full account backup generation and restoration options depend on your hosting provider's configuration. Full backups may need to be restored by the hosting provider or server administrator.

Option 2: Database Backup Using phpMyAdmin

If you only need to back up the WHMCS database, you can use phpMyAdmin.

1. Log in to cPanel.

2. Navigate to Databases → phpMyAdmin.

3. Open phpMyAdmin.

4. Select the database used by WHMCS.

5. Click the Export tab.

6. Select Quick as the export method.

7. Choose SQL as the format.

8. Click Export or Go.

Your database will be downloaded as an SQL file.

For larger databases, use the Custom export method and choose compression if needed.

Important: Make sure you select the correct WHMCS database before exporting.

You can find the database name in your existing configuration.php file.

Option 3: Backup WHMCS Files Using cPanel File Manager

To back up the WHMCS application files:

1. Log in to cPanel.

2. Open Files → File Manager.

3. Navigate to your WHMCS installation directory.

For example:

/home/USERNAME/public_html/

4. Select the WHMCS files and directories.

5. Click Compress.

6. Select Zip Archive or Tar Archive.

7. Enter a backup filename, such as:

whmcs-files-backup.zip

8. Click Compress Files.

9. Download the generated archive to your computer or secure external storage.

Make sure the backup includes:

• configuration.php

• WHMCS application files.

• Templates and custom modifications.

• Addon modules.

• Payment gateway modules.

• Server and registrar modules.

• Custom hooks.

• Attachments and downloads.

• Custom cron scripts.

• Any external storage directories used by WHMCS.

If WHMCS stores attachments or other data outside the document root, back up those directories separately.

Option 4: Backup Using SSH/CLI

Advanced users can also create backups through SSH.

Database backup:

mysqldump -u root -p whmcs_database > /root/whmcs-db-backup.sql

WHMCS files backup:

cd /home/USERNAME/

tar -czf /root/whmcs-files-backup.tar.gz public_html/

Replace whmcs_database and USERNAME with your actual database and account details.

Verify Your Backups

Before continuing, make sure:

• The database backup was generated successfully.

• The database backup is accessible.

• All WHMCS application files have been backed up.

• configuration.php is included.

• Custom templates and modules are included.

• Attachments and external storage directories are backed up.

• The backup archives are not corrupted.

• At least one backup copy is stored outside the hosting server.

Recommendation: For a production WHMCS installation, use cPanel Backup Wizard for a complete account backup and optionally export the database separately through phpMyAdmin.

Never keep your only backup copy on the same server.

9. Download the Latest WHMCS Release

Once compatibility checks and backups are complete, download the required WHMCS release package.

9.1 Review Release Notes Before Downloading

Check the official release notes and changelog again if necessary.

• Release Notes: https://go.whmcs.com/2733/release-notes

• Changelog: https://go.whmcs.com/2737/change-log

Confirm that you are downloading the correct version for your upgrade plan.

9.2 Download Untouched WHMCS Files

Use the following cPanelCentral download API endpoints to obtain the WHMCS release package.

Download the latest available release:

https://endorse.cpanelcentral.com/api/download?ver=latest

Download a specific WHMCS version:

Use this URL format:

https://endorse.cpanelcentral.com/api/download?ver=VERSION

For example, to download WHMCS version 7.10.3:

https://endorse.cpanelcentral.com/api/download?ver=7.10.3

Replace 7.10.3 with the required version.

9.3 Important Download Notes

• Use ver=latest for the latest available release.

• Use a specific version when you need a controlled upgrade.

• Download the original, untouched WHMCS release package.

• Check that the downloaded archive is complete and not corrupted.

• Preserve your existing configuration.php and custom data.

The download endpoint is provided as a package download source. Always verify the release version, package integrity, and applicable WHMCS licensing requirements independently.

9.4 Extract the Downloaded Package

After downloading:

1. Extract the ZIP archive into a temporary directory.

2. Check the extracted folder structure.

3. Make sure the WHMCS application files are present.

4. Confirm that the archive was extracted successfully.

5. Prepare the files for uploading.

Do not replace the existing production files until you are ready to perform the upgrade.

10. Prepare Your WHMCS Installation

Before replacing the existing files:

1. Schedule a maintenance window.

2. Enable maintenance mode where appropriate.

3. Temporarily pause WHMCS cron executions if needed.

4. Make sure no important administrative operations are running.

5. Confirm that your backup is available.

6. Check that enough disk space is available.

7. Make sure the database server is working properly.

If your WHMCS installation uses custom storage directories outside the document root, make sure those directories are also backed up.

11. Upload and Replace WHMCS Files

Once everything is ready, upload the new WHMCS application files.

1. Open cPanel File Manager or connect through FTP/SFTP.

2. Navigate to your existing WHMCS installation directory.

3. Upload the extracted files from the new release.

4. Replace the existing WHMCS application files.

5. Keep the existing configuration.php file unchanged.

6. Preserve custom templates, addons, modules, hooks, and other required custom files.

7. Review any custom modifications to WHMCS core files before applying them again.

8. Check file ownership and permissions.

Important:

Do not overwrite configuration.php.

Do not remove attachments, downloads, custom storage directories, or other important application data.

Follow the official instructions for the exact WHMCS release when replacing application files.

12. Complete the Database Upgrade Through Your Browser

After replacing the WHMCS application files, you need to complete the database upgrade.

Do not run the installer upgrade script through SSH or CLI. Complete this step through your web browser.

Follow these steps:

1. Open your WHMCS installation domain in a browser.

2. Visit the installation directory:

https://yourdomain.com/install/

3. If necessary, open the installer upgrade page directly:

https://yourdomain.com/install/install.php

4. The installer should detect your existing WHMCS installation.

5. Follow the instructions shown on the screen.

6. Review the upgrade information.

7. Confirm the database upgrade.

8. Wait until the process finishes.

9. Check for the successful upgrade message.

Replace yourdomain.com with your actual WHMCS domain.

Important

• Do not close the browser while the upgrade is running.

• Do not refresh the page unnecessarily.

• Do not interrupt the upgrade process.

• Make sure the database user has the required privileges.

• Do not manually modify WHMCS database tables.

If an error appears, stop and investigate it before continuing.

13. Remove the Installation Directory

Once the upgrade has completed successfully, check whether the installation directory still exists.

If it does, remove it.

For example:

cd /home/USERNAME/public_html

rm -rf install/

You can also remove the directory through cPanel File Manager.

Make sure the database upgrade has completed successfully before deleting the directory.

The installation interface must not remain publicly accessible after the upgrade.

14. Check File Ownership and Permissions

After uploading the new files, verify that the file ownership and permissions are correct.

For cPanel servers, files should generally belong to the corresponding cPanel account user.

Example:

chown -R USERNAME:USERNAME /home/USERNAME/public_html

Do not run this command blindly if your installation uses different ownership requirements.

Also check:

• configuration.php

• Writable directories.

• Attachments.

• Downloads.

• templates_c.

• Custom storage directories.

Follow the WHMCS security recommendations for file and directory permissions.

15. Test WHMCS After the Upgrade

Once the database upgrade is complete, test your WHMCS installation before returning it to normal operation.

Admin Area

Check:

• Admin login.

• Dashboard.

• Administrator permissions.

• System Health.

• System Logs.

• Activity Logs.

Client Area

Check:

• Client login.

• Client registration.

• Profile management.

• Invoice viewing.

• Support ticket submission.

• Service management.

• Domain management.

Products and Ordering

Test:

• Product listing.

• Product configuration.

• Order submission.

• Pricing.

• Recurring billing.

• Coupon codes.

Payment Gateways

Test your payment integrations using appropriate test transactions.

Check:

• Payment initiation.

• Callback handling.

• Webhooks.

• Transaction verification.

• Invoice status updates.

• Refund functionality.

• Recurring payments.

Server Modules

Test the provisioning functions you use:

• Account creation.

• Account suspension.

• Account unsuspension.

• Account termination.

• Password changes.

• Service upgrades.

Domain Registrar Modules

Test:

• Domain registration.

• Domain renewal.

• Domain transfer.

• Nameserver updates.

• Registrar synchronization.

Templates and Addons

Make sure:

• Your active client-area template loads correctly.

• Order forms work properly.

• Addon pages are accessible.

• Payment gateways work.

• Server modules work.

• Registrar modules work.

• Custom hooks execute without errors.

• External integrations remain functional.

16. Check WHMCS Cron Jobs

After upgrading, verify that your WHMCS cron jobs are still working.

Check the configured cron jobs:

crontab -l

Make sure:

• The cron path is correct.

• The PHP binary is correct.

• The selected PHP version is supported.

• ionCube Loader is enabled if required.

• Cron execution is successful.

If you changed PHP versions during the upgrade, update the cron configuration accordingly.

17. Monitor Errors After the Upgrade

Once WHMCS is working, monitor the installation for any unexpected errors.

In WHMCS, check:

Configuration → System Logs

Also review:

• Activity Logs.

• PHP error logs.

• Web server error logs.

• Cron execution logs.

• Payment gateway logs.

• Module-specific logs.

Keep an eye on the installation for at least 24 hours after upgrading.

If everything works correctly, disable maintenance mode and allow normal operations to resume.

18. Common Upgrade Problems

WHMCS Shows an Error After Updating

Possible reasons:

• Incompatible addon.

• Unsupported PHP version.

• Missing PHP extension.

• Incorrect file permissions.

• Broken custom hook.

• Incompatible template.

What to do:

Check PHP and web server error logs. Review recently updated modules and test suspected customizations on a staging copy.

ionCube Loader Error

Possible reasons:

• ionCube Loader is missing.

• Loader version is outdated.

• Incorrect PHP configuration.

• Loader is enabled for a different PHP version.

What to do:

Check the website PHP version and install the correct ionCube Loader for that PHP version.

Database Upgrade Failed

Possible reasons:

• Insufficient database permissions.

• Database connection problems.

• Interrupted upgrade.

• Database server issues.

What to do:

Do not repeatedly run the upgrade without understanding the error. Review the error message, check database connectivity, and restore the backup if necessary.

Payment Gateway Is Not Working

Possible reasons:

• Incompatible payment module.

• Deprecated API functions.

• PHP compatibility issues.

• Outdated module version.

What to do:

Contact the payment module developer and obtain an updated version compatible with your WHMCS release.

Client Area Template Is Broken

Possible reasons:

• Outdated template.

• Incompatible Smarty code.

• Changed template variables.

• Custom template modifications.

What to do:

Temporarily switch to a compatible default template for testing. Update your custom template before using it again.

19. Rollback: Restore the Previous WHMCS Version

If the upgrade causes serious problems that cannot be resolved, you may need to restore the previous installation.

Before restoring, remember that database changes made after the backup may be lost.

Restore Using cPanel

If you created a full cPanel backup, contact your hosting provider or server administrator to restore the account if the backup requires server-level restoration.

If you created separate file and database backups, restore both.

Restore WHMCS Files

Using cPanel File Manager:

1. Rename or move the failed installation directory.

2. Upload your previous WHMCS files.

3. Extract the backup archive.

4. Restore the original configuration.php.

5. Check file ownership and permissions.

Restore the Database Using phpMyAdmin

1. Log in to cPanel.

2. Open phpMyAdmin.

3. Select the WHMCS database.

4. Make sure you are restoring to the correct database.

5. Import the previously exported SQL backup.

6. Wait until the import completes successfully.

Alternatively, if you have SSH access:

mysql -u root -p whmcs_database < /root/whmcs-db-backup.sql

After Restoring

Check:

• Admin Area login.

• Client Area login.

• Database connectivity.

• PHP compatibility.

• ionCube Loader compatibility.

• Payment gateway functionality.

• Cron jobs.

• File permissions.

Important: Do not restore an old database without considering new orders, invoices, payments, support tickets, and other transactions created after the backup.

Final Recommendation

Do not rush a WHMCS upgrade, especially on a production billing system.

First, review the release notes, check PHP and ionCube compatibility, and make sure all existing templates, addons, and modules support the new version.

Create a complete backup before replacing any files. Download the required WHMCS release, preserve your existing configuration and customizations, and complete the database upgrade through the browser.

Finally, test the Admin Area, Client Area, payment gateways, server modules, domain integrations, and cron jobs.

Once everything is working correctly, return the installation to normal operation.