Skip to content
Management

WHMCS 9 Upgrade Guide: Moving From 8.13 to 9.1 Safely in 2026

To upgrade to WHMCS 9, move PHP to 8.3 while on 8.13, install ionCube Loader 15, fix Smarty tags, hooks and gateways on staging, then update to 9.1 with a tested backup.

WHMCSPilot Team Published Updated 11 min read
WHMCS 9 Upgrade Guide: Moving From 8.13 to 9.1 Safely in 2026

A WHMCS 9 upgrade moves a self-hosted WHMCS 8.x install to a branch that needs PHP 8.2 or later, a newer ionCube Loader, Smarty 4 compatible templates and code that no longer edits issued invoices. The short answer: move PHP to 8.3 while still on 8.13, install ionCube Loader 15, fix themes, hooks and modules on a staging copy, then update straight to WHMCS 9.1 with a tested backup ready. This guide is for hosting, VPS and IPTV business owners with custom themes, hooks or third-party modules.

Key takeaways

  • WHMCS 9.0 reached general availability on January 20, 2026 and 9.1 on October 20, 2026. Both require PHP 8.2 or later.
  • WHMCS lists December 31, 2026 as the anticipated end of life for both 8.13 and 9.0, so 9.1 (anticipated end of life September 30, 2027) is the version to target.
  • Install ionCube Loader 15.0.0 before you update to 9.1, and update to 9.1 before you move PHP to 8.4.
  • Smarty 4 removes the {php}, {include_php}, {fetch} and {smarty_template.object} tags, and non-Draft invoices become immutable, which breaks hooks and scripts that edit sent invoices.
  • Run the full upgrade on staging first, and treat the file and database backup taken just before the live update as your rollback plan.

What changed in WHMCS 9.0 and 9.1 that affects an upgrade?

WHMCS 9.0 and 9.1 change more than a normal point release. The table lists the changes from the official 9.0 release notes and 9.1 release notes that can block an upgrade or break something after it.

ChangeVersionWhat to check
PHP 8.2 minimum, support for PHP 7.2, 7.3, 7.4 and 8.1 removed9.0Web PHP and cron (CLI) PHP are both 8.2 or later
ionCube Loader 15.0.0 required9.1Loader installed for every PHP version WHMCS uses, before the update
Smarty 4, legacy Smarty tags removed9.0Custom themes, order forms, email templates and module templates
Non-Draft invoices are immutable, credit and debit notes added9.0 (Invoice Immutability setting added in 9.1)Hooks, API scripts and staff habits that change sent invoices
allow_adminarea_invoice_mutation and allow_api_invoice_mutation deprecated9.1Remove both from configuration.php
Direct HTTP requests to crons/cron.php return 403 by default9.0Cron commands that use wget, curl or GET
TrustCommerce and CashU removed; Asiapay, Gate2shop, Inpay and Paypoint dropped from the distribution9.0 and 9.0.5Active payment gateways
Skrill Secret Word and WorldPay Payment Response Password required9.0Gateway settings
Legacy Stripe, Stripe ACH and Stripe SEPA deprecated; PayPal Basic and PayPal Checkout removed from new installs9.1Plan moves to Stripe Dynamic Payments and PayPal Payments
BitPay uses a Point of Sale token instead of an API key9.1BitPay configuration
Google password authentication removed for mail9.0Mail provider and ticket import switched to OAuth2
Plesk server module needs XML API protocol 1.6.9.19.0.9 and 9.1Plesk Onyx 17.8 or later, or Plesk Obsidian 18.0 or later
Language files replaced9.0Custom wording kept in override files, not in the core language files

WHMCS 9.1 also signs out admin Remember Me sessions, enforces a 12-character minimum password length by default, and, if you upload a patch set that includes the install directory, waits for you to finish at install/install.php.

Which WHMCS version should I upgrade to?

WHMCS 9.1 is the version to upgrade to in November 2026, because 9.0 reaches its anticipated end of life on the same day as 8.13. WHMCS lists the supported versions on its Updating Through EOL Versions page:

VersionCurrent tierAnticipated end of life
WHMCS 9.1General AvailabilitySeptember 30, 2027
WHMCS 9.0Long-Term SupportDecember 31, 2026
WHMCS 8.13Long-Term SupportDecember 31, 2026

You can update from 8.13 directly to 9.1, reading the 9.0 release notes as well as the 9.1 notes. If you are on 8.12 or older and jump straight to 9.1, remove or replace PayPal Basic and PayPal Checkout first: PHP 8.2 cannot decode the files older versions installed, and leftovers in modules/gateways/ cause an HTTP 500 error in the Admin Area.

What PHP and ionCube versions does WHMCS 9 need?

WHMCS 9 needs PHP 8.2, 8.3 or 8.4 (8.4 from 9.1 only) and an ionCube Loader that matches. The combinations below come from the WHMCS system requirements and release notes for each version.

PHP versionWHMCS 8.13WHMCS 9.0WHMCS 9.1
PHP 8.1Supported (ionCube 12.0.1+)Not supportedNot supported
PHP 8.2Supported (ionCube 13.0.2+)Supported (ionCube 13.0.2+)Supported (ionCube 15.0.0)
PHP 8.3Supported (ionCube 14.4.0+)Supported, recommended (ionCube 14.4.0+)Supported (ionCube 15.0.0)
PHP 8.4Not supportedNot supportedSupported, recommended (ionCube 15.0.0)

PHP 8.3 is the safest version for the move. Both 8.13 and 9.1 run on it, so you change one thing at a time and a rollback needs no PHP change. PHP 8.2 is a poor long-term choice: its security support ends on December 31, 2026, according to the PHP supported versions page. Three ordering rules from WHMCS matter:

  1. Update to WHMCS 8.13 before you move PHP to 8.3.
  2. Install ionCube Loader 15.0.0 before you update to WHMCS 9.1. WHMCS warns of "serious problems" if you reverse this.
  3. Update to WHMCS 9.1 before you move PHP to 8.4.

Apply these to the PHP that runs your cron too. Many servers use a separate command-line PHP with its own php.ini, and a cron left on old PHP or without ionCube stops billing even when the Admin Area loads.

How do I check modules, gateways, themes and hooks for compatibility?

A WHMCS 9 compatibility check covers encoded modules, payment gateways, templates and your own PHP code. Do it on staging and list every item with its fix before you schedule the live upgrade.

Encoded third-party modules

Run a scan at Utilities > System > PHP Version Compatibility. The report sorts ionCube-encoded files into Compatible Encoding, Incompatible Encoding and Encoding Compatibility Unknown for each PHP version. It only checks decoding, not PHP syntax, so ask each vendor whether their current release supports WHMCS 9.x. If no update exists, WHMCS advises removing the module or waiting for the vendor. When a vendor has gone quiet, a legacy module rescue can repair code you own or rebuild the module from its behavior.

Payment gateways

Compare every active gateway at Configuration > System Settings > Payment Gateways with the table above. WHMCS 9.1 adds a Migrate from Legacy Stripe Payment Gateways button and a modules/gateways/stripe_dynamic/bin/migrate.php script that move stored payment methods to Stripe Dynamic Payments without clients re-entering cards. WHMCS says PayPal will end support for PayPal Basic and PayPal Checkout in 2027, after which those payments fail, so move to PayPal Payments now.

Themes, order forms and email templates

Run the Smarty Compatibility Report at Reports > Reports on 8.13. It scans templates, modules, hooks and email templates for {php}, {include_php} and {insert}, but not {fetch} or {smarty_template.object}, so search for those by hand. WHMCS recommends moving template PHP into ClientAreaPage or EmailPreSend hooks that return variables. Keep custom themes in their own directories and compare them with the Six, Twenty-One, Nexus and Standard Cart changes on GitHub.

Hooks and custom code

Review /includes/hooks and every custom module for code that breaks on PHP 8.2 (functions removed in PHP 8.0, dynamic property deprecations), code that changes invoices after they leave Draft, and code that relies on the old mutation variables. In 9.1 the Invoice Immutability setting in the Invoices tab at Configuration > System Settings > General Settings can relax the rule, but WHMCS warns this can make your accounting records inaccurate. Reworking the process around credit and debit notes is the better fix.

How do I upgrade WHMCS 8 to 9 on a staging copy first?

The staging-first WHMCS 9 upgrade below follows WHMCS's Prepare to Update and Set Up a Test Environment guidance. If you bought your license directly from WHMCS, ask WHMCS Customer Service for a free development license for staging.

  1. Update production to 8.13.7, the latest 8.13 release, which includes the September 2026 security fixes.
  2. Move production PHP to 8.3 with ionCube Loader 14.4.0 or later, for web and cron PHP, and confirm cron runs cleanly for a few days.
  3. Clone files and database to a password-protected staging site, as the development license requires.
  4. Make staging harmless. Update the System URL, turn on Disable Email Sending in the Mail tab, put gateways and registrars in test mode and disconnect production servers. WHMCS also suggests adding extra characters to cc_encryption_hash in the staging configuration.php so it cannot decrypt stored payment data.
  5. Install ionCube Loader 15.0.0 on staging and confirm 8.13 and its cron still work.
  6. Clear the report findings, remove legacy gateways and fix hooks.
  7. Update staging to 9.1 at Utilities > Update WHMCS, the method WHMCS recommends.
  8. Test the money paths. Order each product type, pay with each gateway in test mode, provision and terminate a test account on each server module, register a test domain, pipe a ticket, and check invoices, credit notes and PDFs.
  9. Check automation. Run the cron from the command line, then review Configuration > System Health and Utilities > Automation Status.
  10. Write the runbook, listing every change in order with exact files and settings.
  11. Back up production: the full WHMCS directory, the database and a separate copy of configuration.php. Give the database user full privileges for the update.
  12. Upgrade production in a quiet window. Turn on Maintenance Mode, install ionCube Loader 15, apply your fixes, update to 9.1, then repeat the step 8 tests with real, refundable payments.
  13. Watch the next daily cron run and the Activity Log before you call it done.

The WHMCS 9 upgrade service covers the audit, staging, fixes and live update for you. For a near-stock install, the standard WHMCS upgrade service is the simpler option.

What is the rollback plan if the WHMCS 9 upgrade fails?

WHMCS has no downgrade button, so a WHMCS 9 rollback means restoring the files and database you backed up right before the live update. Plan it before you start:

  • Set a go or no-go deadline. Agree in advance, for example within the first hour, which failures trigger a rollback: checkout errors, failed gateway callbacks, provisioning errors or a cron that will not complete.
  • Leave PHP and ionCube alone. If 8.13 ran on PHP 8.3 and ionCube 15 in staging, a rollback only restores WHMCS. ionCube says newer Loaders can often run files from earlier Encoder versions, so confirm it on staging.
  • Restore files and database together, including the original configuration.php. A database without its matching cc_encryption_hash cannot decrypt stored passwords or card data.
  • Reconcile anything after cutover. Orders, payments and tickets created on 9.1 are lost by a restore, so use your gateway dashboards and Gateway Log export to re-enter payments.

Our WHMCS backup and disaster recovery guide covers backup storage and test restores in more detail.

What if I have to stay on WHMCS 8.13 until December 31, 2026?

Staying on WHMCS 8.13 until its end of life is reasonable when a critical module has no 9.x version yet, but use the time to remove blockers.

  • Run 8.13.7 or later. Earlier versions lack the fix for CVE-2026-67399, which WHMCS says lets an unauthenticated attacker execute code on the server.
  • Move to PHP 8.3 now. PHP 8.1 is out of support and PHP 8.2 security support ends on December 31, 2026.
  • Clear the Smarty Compatibility Report and move template PHP into hooks. This work carries straight over to 9.x.
  • Move gateways off legacy Stripe and PayPal Basic or Checkout.
  • Press vendors for 9.x release dates, and budget for replacing any module without one.
  • Schedule the upgrade before the end of December. After that date WHMCS stops releasing updates for 8.13, including security fixes.

Outdated versions are a common way in for attackers, so cover the waiting period with the tools in our WHMCS security modules hub.

Frequently asked questions

Can I upgrade from WHMCS 8.13 directly to 9.1?

Yes. WHMCS supports updating from 8.13 to 9.1 in one step, as long as you meet the 9.1 requirements first, including PHP 8.2 or later and ionCube Loader 15.0.0, and read the 9.0 release notes as well as the 9.1 notes.

Does WHMCS 9 work on PHP 8.1?

No. WHMCS 9.0 removed support for PHP 7.2, 7.3, 7.4 and 8.1, and the update does not appear at Utilities > Update WHMCS until the server runs a compatible PHP version.

Will my custom WHMCS theme work after upgrading to 9?

A custom theme works only if it has no legacy Smarty tags and includes the 9.x template changes. Run the Smarty Compatibility Report, search for {fetch} and {smarty_template.object} by hand, and test every client area page on staging.

Do I have to switch to the Nexus theme in WHMCS 9?

No. Six and Twenty-One remain available in 9.x. You only need Nexus as the system theme if you want the new Nexus cart, which also requires Nexus Cart as the default order form template.

What happens if I stay on WHMCS 8.13 after December 31, 2026?

Your install keeps running, but WHMCS stops releasing maintenance and security updates for 8.13 after its end-of-life date. Any vulnerability found after that date stays open on your install.

How long does a WHMCS 9 upgrade take?

The live update window is the short part of the job. The preparation takes longer: a near-stock install can be ready in a few days, while installs with custom themes, many hooks or encoded modules that need replacing can take a week or two of staging work.

If old modules or custom code are what stop you from upgrading, see our WHMCS 9 upgrade and compatibility service.