System Cron

When you set up your WHMCS installation, you must set up the system cron to automate WHMCS’s many tasks. The system cron is a system daemon that executes tasks at designated times. WHMCS includes processes that must run on a periodic basis via the cron.

Cron Tasks

The method that you use to set up your cron jobs will depend on the type of server that you use and whether you prefer to use the command line or a control panel interface.

Most hosting control panels provide a simple user interface for creating cron jobs. For more information, see Configure the System Cron Job.

After you set up the cron job, you can change the time at which the daily automated actions run using Time of Day at Configuration () > System Settings > Automation Settings. You must ensure that the system cron will run during the hour that you set.

  • WHMCS uses the PHP now() timestamp when the cron.php script runs. This determines the current time using the value that the PHP configuration returns.
  • We recommend running the cron task every five minutes. WHMCS will never perform a particular task more frequently than you specify.
  • Make certain that WHMCS’s configured timezone matches the server’s timezone.
For steps to set the Time of Day setting, see Configure When Daily Tasks Run.

When you configure WHMCS, set up the following cron tasks:

System Cron

The system cron automates tasks within WHMCS. The system uses this to automate billing, generate invoices, and perform many other actions. Configure this to run every 5 minutes, or as frequently as your hosting provider allows (at minimum, once per hour).

You can find the correct command to copy-and-paste for your WHMCS installation by going to Configuration () > System Settings > Automation Settings and clicking on the first badge:

Automation Settings badges

For example: */5 * * * * php -q /home/username/crons/cron.php

For more information, see System Cron Options and Example Cron Commands (below).

POP Email Import Cron

You only need to configure this cron task if you want to import emails to the support queue via the POP3 protocol.

If you use this, configure it to run every five minutes.

For example: */5 * * * * php -q /home/username/crons/pop.php

We recommend using email piping instead.

The crons Directory

All of the files for WHMCS’s cron tasks are in the crons directory.

You can move the crons folder to any location above or below the document root. We recommend moving it to a private directory above your document root for better security.

For more information, see Moving the Crons Directory.

System Cron Options

The system cron automates tasks within WHMCS. You can run the system cron script (crons/cron.php) with additional options if you need additional control over the tasks that run and the script’s output.

The system cron script has the following argument input structure:

cron.php [<argument> [options]]

  • Most WHMCS installations will not need these additional options.
  • To pass arguments to PHP scripts, you must enable the register_argc_argv directive. For help, contact your hosting provider or system administrator.
You can also use the hook system to customize what happens before, during, and after the system cron runs. For more information, see our Developer Documentation.

Arguments

You can use the following arguments:

ArgumentDescriptionExample
allAttempt to perform all due automation tasks. If you do not provide input, the cron runs with this argument by default.*/5 * * * * php -q /path/to/cron.php all
doOnly perform the tasks that you specify.
  • The --force option is enabled by default when you use this argument.
  • The system does not modify its internal scheduling for tasks when you run tasks using this argument.
For a list of tasks, see Tasks below.
helpLists help and options for the argument you specify.
listLists all possible arguments.
skipPerform all tasks (in the same way as the all argument) but exclude tasks that you specify.
For a list of tasks, see Tasks below.
*/5 * * * * php -q /path/to/cron.php skip --DomainRenewalNotices
You can view the additional options for each of the above options using help <argument>.

Options

You can use the following arguments:

OptionDescription
-F, --forceForce the execution of tasks, regardless of whether the task is due or already in progress.
-v, -vv, -vvvSet the verbosity of command line output. By default, the system cron does not generate any success output.
--email-reportForcibly send a digest report of the actions during the run. This report contains information about that cron run and will not contain information from previous runs. During the normal daily run, this uses a default value of 1 and sends the Digest Email Report message. In all other runs, this defaults to 0 and does not send anything. For example: --email-report=1
-V, --versionOutput the WHMCS version and exit.
--no-ansiStrip any non-printing command line markup (for color output).
-h, --helpPrint help for a command. This returns the same output as the help argument.

Tasks

Most of the system cron’s tasks only need to run daily. Others, however, may benefit from running multiple times per day, like ticket escalations or checking for WHMCS updates. A few tasks only run once per month, like calculating overage usage and generating invoices.

For an example of scheduling a particular task to only execute on a particular schedule, see Custom Task Runs below.

WHMCS handles this correctly automatically for scheduled cron runs, but you can also choose tasks to run (using the do argument) or skip (using the skip argument) when running the cron yourself:

OptionDescriptionFrequency
--AddLateFeesApply Late FeesDaily
--AffiliateCommissionsProcess Delayed Affiliate CommissionsDaily
--AffiliateReportsSend Monthly Affiliate ReportsMonthly
--AutoClientStatusSyncSynchronise Client StatusDaily
--AutoPruneTicketAttachmentsAuto Remove Inactive Ticket Attachments. Batches of 1000Hourly
--AutoSuspensionsProcessing Overdue SuspensionsDaily
--AutoTerminationsProcess Overdue TerminationsDaily
--CancellationRequestsProcess Cancellation RequestsDaily
--CheckForWhmcsUpdateCheck for WHMCS Software UpdatesAs soon as every 8 hours
--CloseInactiveTicketsAuto Close Inactive TicketsDaily
--CreateInvoicesGenerate InvoicesDaily
--CreditCardExpiryNoticesSending Credit Card Expiry RemindersMonthly
--CurrencyUpdateExchangeRatesUpdate Currency Exchange RatesDaily
--CurrencyUpdateProductPricingUpdate Product Prices for Current RatesDaily
--DataRetentionPruningProcess data retention pruning operation.Daily
--DatabaseBackupCreate a database backup and deliver via FTP or emailDaily
--DomainRenewalNoticesProcessing Domain Renewal NoticesDaily
--DomainStatusSyncProcessing Domain Status Syncing for Active domains. Batches of 50.As soon as every hour
--DomainTransferSyncProcessing Domain Transfer Syncing for Pending Transfer domainsAs soon as every hour
--EmailCampaignsUpdate the status of Email Campaigns and schedule emails. Batches of 50As soon as every 5 minutes
--EmailMarketerProcess Email Marketer RulesDaily
--FixedTermTerminationsProcess Fixed Term TerminationsDaily
--InvoiceAutoCancellationAutomatically cancel old overdue unpaid invoices. 8.10+Daily
--InvoiceRemindersGenerate daily reminders for unpaid and overdue invoiceDaily
--OverageBillingProcess Overage Billing Charges and Generate InvoicesMonthly
--ProcessCreditCardPaymentsProcess Credit Card ChargesDaily
--ProcessEmailQueueProcess scheduled emails within Email Campaigns. Batches of 25As soon as every 5 minutes
--SslReissuesProcess MarketConnect SSL certificate reissuances. v8.5+Daily
--SslSyncCheck validity of SSL Certificates on services and domains. Batches of 100.Daily
--ServerRemoteMetaDataAuto Update Server Meta Data. Displayed on Configuration () > System Settings > Servers.Hourly
--ServerUsageCountAuto Update Server Usage Count. Displayed on Configuration () > System Settings > Servers.Hourly
--TenantUsageMetricsAuto Update Service Usage Data. Displayed when viewing Service within Client Area.Twice-daily
--TicketEscalationsProcess and escalate tickets per any Escalation RulesAs soon as every 3 minutes
--UpdateDomainExpiryStatusUpdate Domain Expiry Status for domains with a past Expiry DateDaily
--UpdateServerUsageUpdating Disk & Bandwidth Usage StatsDaily
The system cron also runs specific system tasks that you cannot specify when running the cron command yourself. WHMCS will perform these tasks when it requires them.

Custom Task Runs

If you want a particular task to only execute on a particular schedule, create a separate scheduled cron command that uses the do argument for that task and alter your main System Cron command to skip that task using the skip argument.

For example, you could schedule the first cron command below to skip ticket escalations and automatic suspensions on regular runs:

*/5 * * * * php -q /path/to/cron.php skip --TicketEscalations --AutoSuspensions

Then, you could schedule the second and third commands separately to only process ticket escalations on weekdays during business hours and only process automatic suspensions on weekday mornings:

0 9,10,11,12,13,14,15,16 * * 1-5 php -q /path/to/cron.php do --TicketEscalations
0 9 * * 1-5 php -q /path/to/cron.php do --AutoSuspensions

Invoke the Cron with an HTTP Request

In some hosting environments, you may not be able to create a crontab entry directly. Instead, you can invoke the cron command using an HTTP request.

To do this, ensure that the cron.php script is accessible within the document root.

For example, the following GET request runs the system cron, skipping the DomainRenewalNotices and TicketEscalations tasks.

GET http://www.example.com/admin/cron.php?command=skip&options=DomainRenewalNotices,TicketEscalations

Last modified: April 30, 2024