Update a custom WHMCS theme alongside the application release it supports. Keeping an old theme unchanged can hide new controls or break checkout even when the core upgrade completes successfully.
01 Prepare the compatibility review
- Identify the active system theme, default order form, product-group templates and custom hooks that alter their output.
- Obtain the theme vendor's compatible release or compare your custom files with the corresponding WHMCS base version.
- Back up the current files and record your intentional customisations.
- Apply the candidate update in a private test environment with external actions isolated.
- Review changed templates and merge the required vendor changes without blindly replacing new files with the old customised copies.
- Test login, user switching, services, invoices, support and the complete cart, including mobile layouts.
02 Check WHMCS 9.0 changes
Review the release notes and Smarty Compatibility Report for legacy constructs in custom templates and email content. Unsupported PHP execution tags and removed Smarty behavior need a supported code or template change, not an error-suppression setting.
Verify the theme and cart as a compatible pair. A product-group comparison page can look correct while the system-default checkout template fails later in the same purchase.
Common questions
Should the old template directory be copied over the new release?
Keep it as a backup, then merge intentional changes against compatible files. Overwriting the release with the old directory can restore the defect the upgrade was meant to fix.
When should the template cache be cleared?
Use the supported System Cleanup cache action when needed after template changes. Verify that the compiled-template directory remains writable.
What if only the custom theme fails?
Compare the affected task with a compatible stock theme in the test environment, then isolate the custom template or hook before changing unrelated billing settings.
Retain a tested rollback package and a record of the exact theme version deployed.