The WHMCS cron job is the quiet engine behind your whole billing system. It creates renewal invoices, sends payment reminders, suspends unpaid services and keeps your domains in sync. When it stops, nothing breaks right away. Invoices just stop going out, and you often don’t notice until a client asks why they were never billed. This guide shows how to set up the WHMCS cron job in cPanel, how to check that it’s really running, and the proven fixes for the problems that stop it.
What the WHMCS Cron Job Does
WHMCS can’t do anything on a schedule by itself. It only runs when something asks it to. The cron job is that something: a server task that runs WHMCS’s cron.php file on a timer. Each time it runs, WHMCS checks which tasks are due and runs them.
That includes:
- Invoicing: creating renewal invoices the right number of days before each due date.
- Reminders: sending unpaid and overdue notices.
- Suspensions and terminations: acting on unpaid services according to your settings.
- Domain sync: checking domain status and transfers with your registrar every hour.
- Ticket escalations: moving tickets according to your escalation rules.
- Addon tasks: anything a module schedules, such as uptime checks or reports, and code attached to the
DailyCronJobhook.
Every one of the settings in our WHMCS automation guide depends on this one job. If you’re new to the platform, what is WHMCS covers the bigger picture.
Signs Your WHMCS Cron Job Has Stopped
A broken WHMCS cron job rarely announces itself. Watch for these clues:
- Renewal invoices that should have gone out this week are missing.
- Clients with overdue invoices are still active instead of suspended.
- Domain expiry dates and statuses haven’t changed in days.
- The admin dashboard shows a warning that the cron hasn’t run recently.
- Scheduled reports and addon emails have gone quiet.
If you see any of these, jump to the checks in Step 3 before anything else.
How Often Should the WHMCS Cron Job Run?
WHMCS recommends running the cron every five minutes, and it needs to run at least once an hour. If it hasn’t run in the past two hours, WHMCS shows a warning on the Automation Status page. Five minutes is the right choice for almost everyone: it keeps domain syncing and module tasks current without putting real load on the server, because most runs finish in seconds when nothing is due.
Daily tasks like invoicing still only happen once a day. You choose the hour under the automation settings, and WHMCS runs them on the first cron run after that time. Most hosts pick an early-morning hour, when their own team is about to start work and can check the results.
Step 1: Find Your Cron Command in WHMCS
Don’t guess the path. WHMCS shows the exact command for your install. In the admin area, go to Configuration → System Settings → Automation Settings. The command is shown at the top of the page. It looks something like this:
php -q /home/username/crons/cron.phpThe path depends on where your crons folder lives. Many installs move it outside public_html for security, which is one of the steps in our WHMCS security checklist. If you’ve moved it, the command WHMCS shows will already reflect that.
Step 2: Add the WHMCS Cron Job in cPanel
- Log in to cPanel and open Cron Jobs under Advanced.
- Under Common Settings, choose Once Per Five Minutes. That fills in
*/5for the minute and*for everything else. - Paste the command from WHMCS into the Command box.
- Click Add New Cron Job.
The full line ends up as:
*/5 * * * * php -q /home/username/crons/cron.phpcPanel’s own Cron Jobs documentation explains every field on that screen, and crontab.guru is a handy way to double-check any schedule before you save it. If you’re connecting WHMCS to cPanel for the first time, our WHMCS cPanel setup guide walks through the server side too.
No cPanel? Use crontab
On a VPS or dedicated server without cPanel, add the same line with crontab -e while logged in as the user that owns your WHMCS files. Running the cron as root can leave files WHMCS later can’t write to, so stick to the site’s own user.
Step 3: Check That It’s Running
Wait ten minutes, then go to Utilities → Automation Status in the WHMCS admin. You’ll see when the cron last ran and what each task did. If the last run time keeps moving forward, you’re set.
You can also run the cron by hand over SSH to see what happens:
php -q /home/username/crons/cron.php -vvThe -v, -vv and -vvv options add more detail to the output. The cron normally prints nothing when it succeeds, so seeing output with these options is a good sign it reached WHMCS.
Useful Cron Options
| Option | What it does |
|---|---|
-v, -vv, -vvv | Shows more detail about what the cron is doing |
--force | Runs tasks even if they aren’t due or are already marked as running |
do | Runs only the tasks you name |
skip | Runs everything except the tasks you name |
--email-report | Emails a summary of the run |
Passing options to the cron needs PHP’s register_argc_argv setting turned on. Most hosts have it on already. If options seem to be ignored, ask your host. The full list is in the official WHMCS system cron documentation.
Common WHMCS Cron Job Problems and Fixes
“Cron has not run within the past two hours”
The cron job either doesn’t exist, has the wrong path, or is failing before it reaches WHMCS. Recheck the path against Automation Settings, then run the command by hand over SSH to see the actual error.
The cron runs, but with the wrong PHP version
On servers with several PHP versions, plain php in a cron job can point to a different version than your website uses. WHMCS 9 needs a current PHP version and the ionCube Loader, so an older default can make the cron fail while the site works fine. Use the full path to the right PHP binary in the command. On cPanel servers with EasyApache that usually looks like /opt/cpanel/ea-php83/root/usr/bin/php.
Daily tasks run at the wrong time
WHMCS’s timezone setting needs to match your server’s timezone. If they differ, the “run daily tasks at” hour drifts. Fix the timezone and the next day’s run lands where you expect.
The cron stopped after a WHMCS update
Updates can change PHP requirements, and a cron that worked yesterday can fail on the new version. Run it by hand after every update. It’s on the checklist in our guide to updating WHMCS safely.
Tasks are stuck as “running”
If a run was interrupted, for example by a server reboot, WHMCS can think a task is still in progress and skip it. Run the cron once by hand with --force to clear it, then let the normal schedule take over.
Domain statuses are out of date
Domain status and transfer checks run hourly through the main cron, in batches. If domains look stale, check that the cron is running every few minutes, then look at your registrar module settings and API access.
Keep the WHMCS Cron Job Secure
Because the WHMCS cron job runs with access to your billing data, treat it like the rest of your install. Keep the crons folder outside your public web root so nobody can trigger it from a browser, and make sure only your account can read the config file it points to. Avoid web-based “cron services” that call a public URL, since that exposes a path attackers can hammer. A plain server cron is safer and more reliable.
What About pop.php?
If you import support emails into tickets over POP3, WHMCS has a second cron file, pop.php, which also runs every five minutes. WHMCS recommends email piping instead where your host supports it, because piping creates tickets instantly. If you do use POP3, add it as its own cron job:
*/5 * * * * php -q /home/username/crons/pop.phpGet an Alert When the Cron Stops
Automation Status only helps if you look at it. A heartbeat monitor flips that around: the WHMCS cron job checks in after each run, and you get an email if the check-in doesn’t arrive. Our Caddie WHMCS tools addon includes a Heartbeat Monitor built for exactly this, and your clients can use it for their own cron jobs and backups too.
Frequently Asked Questions
How often should the WHMCS cron job run?
Every five minutes is recommended, and at least once an hour is required.
Where do I find the WHMCS cron command?
In Configuration → System Settings → Automation Settings. Copy it from there rather than typing the path yourself.
How do I know the WHMCS cron job is working?
Check Utilities → Automation Status. The last run time should update every few minutes.
Can I run the WHMCS cron job more often than every five minutes?
You can, but there’s no benefit. Tasks only run when they’re due, so extra runs just add server load.
Does Blesta work the same way?
Very similar. Blesta also relies on one cron job for its automation. See our Blesta cron job guide.
Need a Hand With WHMCS?
Our reseller hosting plans run on LiteSpeed servers with cPanel/WHM and JetBackup, and they’re built to pair with WHMCS. Read how WHMCS for reseller hosting ties billing to WHM, make sure your invoices land by fixing WHMCS emails going to spam, browse our WHMCS addons and modules, or contact us if your WHMCS cron job is giving you trouble.
