Set up the Blesta cron for billing and provisioning

Blesta funnels almost every recurring action through a single cron entry: invoicing, auto-debit, late fees, suspension, cancellation, module provisioning callbacks, exchange rate updates, and the outbound email queue. Miss the cron and the whole platform looks broken from the customer side — invoices stop, paid orders sit in pending, overdue accounts never suspend, welcome emails never send.

This is the configuration that works on a real production Blesta install: the crontab line, the per-task intervals to set inside the panel, how to confirm tasks are actually firing, and the failure modes that account for most of the "Blesta is broken" support tickets.

Step 0 — Confirm the PHP binary and install path

Blesta's cron handler is <install path>/index.php, invoked with cron as an argument. On a default cPanel install with Blesta in /home/billing/public_html/blesta/, that becomes:

/usr/local/bin/php /home/billing/public_html/blesta/index.php cron

Two things commonly break here:

1. The wrong PHP binary. Current Blesta requires PHP 8.1 or newer. On EasyApache 4 the system /usr/bin/php may point at an older alt-PHP version that the web stack uses fine but the cron rejects. Always invoke the binary that matches your install's PHP requirement, not whatever which php happens to return.
2. The wrong path. If you symlinked the Blesta directory into a vhost, the cron may follow the symlink under SELinux or open_basedir restrictions and fail silently. Use the canonical filesystem path in the crontab, not the symlink target.

Verify both before adding the cron:

/usr/local/bin/php -v
/usr/local/bin/php /home/billing/public_html/blesta/index.php cron

The second command should print task names and run times, not a PHP fatal error.

Step 1 — Add the crontab entry

Add the cron under the user that owns the Blesta files — usually the cPanel or Plesk account user, not root:

crontab -u billing -e

For a typical install, fire every five minutes:

*/5 * * * * /usr/local/bin/php -q /home/billing/public_html/blesta/index.php cron > /dev/null 2>&1

Don't run it more often than every minute and don't run it less often than every fifteen. Below one minute, concurrent cron processes race on the same task queue and you get duplicate work. Above fifteen, email retries, payment processing, and provisioning callbacks stack visibly — customers see delays that look like outages.

For very small installs (under ~50 active services) every fifteen minutes is fine:

*/15 * * * * /usr/local/bin/php -q /home/billing/public_html/blesta/index.php cron > /dev/null 2>&1

Step 2 — Schedule the individual tasks inside Blesta

The crontab line only fires the dispatcher. Each task has its own interval under Settings → Company → Automation:

The system cron must fire at least as often as the most-frequent task. If your crontab is set to fifteen minutes but Process service provisioning is set to five, provisioning still runs every fifteen — the inner interval is a ceiling, not a guarantee.

Stagger the Time to Run for daily tasks. By default Blesta runs everything at 00:00 server time, which produces a thundering herd against your payment gateways and the delivery slot most likely to overlap with overnight backups. A workable stagger:

• Create invoices: 02:00
• Auto-debit: 03:30 (after invoices, before reminders)
• Send invoice reminders: 04:00
• Suspend overdue services: 05:00
• Cancel scheduled services: 05:30

Step 3 — Confirm tasks are actually firing

Two checks: the cron is running, and Blesta is completing the work.

Is the cron running?

grep CRON /var/log/cron | tail -20
# Debian/Ubuntu and Plesk:
grep CRON /var/log/syslog | tail -20

You should see the dispatcher firing on its schedule. If you don't, check the crontab is under the right user (crontab -u billing -l), that crond is running (systemctl status crond), and that SELinux isn't denying execution (grep blesta /var/log/audit/audit.log).

Is Blesta completing tasks?

Inside the panel, go to Tools → System Logs → Cron Tasks. Every successful dispatcher run logs a row with start time, end time, and the tasks that ran. Empty log means the crontab isn't reaching Blesta — check the PHP binary path. Rows with errors are click-through to the stack trace.

For live diagnosis, run the cron manually as the Blesta user:

sudo -u billing /usr/local/bin/php /home/billing/public_html/blesta/index.php cron

Output goes straight to the terminal, so a stuck task that's blocking the queue surfaces immediately.

Step 4 — The five failure modes

Cron runs but no invoices generate. The Create invoices task needs a Time to Run set, and at least one service must have its Next Renew Date inside the invoice generation window (default: seven days ahead). Check both before anything else.

Provisioning callbacks fail silently. The per-module cron catches exceptions and logs them under Tools → System Logs → Module Logs, not the main cron log — easy to miss. The most common cause on cPanel installs is the WHM API token losing one of its required scopes after a WHM version upgrade. See WHM API token scopes for the exact set Blesta needs.

Email queue grows but nothing sends. The Send email queue task is firing but SMTP is rejecting. Check Settings → Company → Emails → Mail Settings for credentials and tail your MTA log. If Blesta routes through an outbound smart host for deliverability, the smart host's credentials are what matters — not whatever's in the "Mail server" field.

Auto-debit stalls on one customer. Blesta processes auto-debit sequentially. A gateway timeout on customer #1 stalls the whole batch under tight transaction settings. Raise the gateway timeout to 60 seconds and confirm your processor returns within that window. The relevant timeout fields for the Stripe gateway are in the Stripe setup guide.

Duplicate invoices show up on the same day. Two crontabs are firing the dispatcher. This happens after migrations or when a sysadmin adds a cron under one user and the panel re-adds one under another. List every relevant crontab and remove duplicates:

for u in root billing $(awk -F: '$3>=1000 {print $1}' /etc/passwd); do
  echo "=== $u ==="
  crontab -u "$u" -l 2>/dev/null | grep -i blesta
done

Step 5 — Split out the module cron for heavy provisioning

By default Run module cron is one task inside the main dispatcher. On a host with hundreds of cPanel accounts auto-provisioning at the same minute, the dispatcher run can exceed five minutes and the next tick starts before the previous finishes — exactly the race condition Step 4 warns about.

For that load, split the module cron into its own line and disable the inner task. Two crontab entries, one user:

*/5 * * * * /usr/local/bin/php -q /home/billing/public_html/blesta/index.php cron > /dev/null 2>&1
*/5 * * * * /usr/local/bin/php -q /home/billing/public_html/blesta/index.php cron module > /dev/null 2>&1

Then under Settings → Company → Automation, set Run module cron to disabled — it now runs via the dedicated entry instead, and the main dispatcher returns within a few seconds regardless of how slow WHM is to respond.

Next steps

• Set up Stripe in Blesta so auto-debit has a working gateway before the cron starts firing it daily.
• Migrate from WHMCS to Blesta — adding the cron is the cutover step most often missed during the switch.
• See the Blesta licence options if you're sizing a new install and want to know which features are gated by tier.