Skip to content

Scheduled Tasks API

The cron module runs ClientFence’s scheduled tasks: invoices, reminders, suspensions, emails, backups and health checks. These calls show when it last ran, run it now, and manage the guest cron call for servers that cannot run cron.php. See Scheduled tasks (cron) for the cron line.

Admin calls need Module access on the Cron card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.

POST /api/admin/cron/info

Returns where cron.php is on the server and when the scheduled tasks last finished.

Permission: View cron information (cron.view)

No parameters.

Returns: An object: cron_path (the full path of cron.php on the server) and last_cron_exec (date and time of the last run, or null before the first one).

Example

Request parameters:

{}

result:

{
"cron_path": "/var/www/clientfence/cron.php",
"last_cron_exec": "2026-11-17 10:05:02"
}

POST /api/admin/cron/run

Runs all the scheduled tasks now, as one cron run: connects hooks, pays invoices with credit, activates paid orders, creates and sends invoices and reminders, suspends and cancels overdue orders, closes old tickets, sends queued email, and runs every module’s cron work.

Permission: Run cron jobs (cron.manage)

No parameters.

Returns: true when every task ran (or when another cron run was already going, in which case this one does nothing); false when one or more tasks failed (they are named in the cron log).

Errors:

  • Update finalization is pending. Cron jobs are paused until finalization is completed. (code 503)

The tasks run for real: invoices are created, email is sent and overdue services are suspended. A run can take a long time on a large install.

POST /api/admin/cron/save_settings

Turns the guest cron call (guest/cron/run) on or off. Turning it on creates a secret hash if there is none; turning it off clears the hash.

Permission: Run cron jobs (cron.manage)

Parameter Type Description
guest_cron boolean true to allow running cron through the guest API with the hash. Anything empty or missing turns it off.

Returns: true

Read the hash with extension config_get (ext: mod_cron, field cron_hash) or make a new one with regenerate_cron_hash.

POST /api/admin/cron/regenerate_cron_hash

Makes a new secret hash for the guest cron call. The old hash stops working at once.

Permission: Run cron jobs (cron.manage)

No parameters.

Returns: An object with cron_hash: the new hash (64 hexadecimal characters).

Example

Request parameters:

{}

result:

{
"cron_hash": "3f9a1c0e5b7d2a4c6e8f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f"
}

POST /api/guest/cron/run

Runs the scheduled tasks, for servers that can call a URL but cannot run cron.php. Works only when the guest cron call is turned on, with the right hash.

Parameter Type Description
hash string, required The secret cron hash from the module’s settings.

Returns: true when every task ran; false when the last run finished less than a minute ago (nothing runs) or when a task failed.

Errors:

  • You do not have permission to perform this action (code 403): the guest cron call is off, or the hash is wrong.
  • Guest cron is enabled but no security hash has been configured (code 403)
  • Update finalization is pending. Cron jobs are paused until finalization is completed. (code 503)

Guest calls share the guest rate limit. Keep the hash secret: anyone with it can start a cron run.