Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared hosting Managed WordPress Cloud hosting VPS hosting By reader location Hosting finder
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Blog Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Developer · Guide

How to Schedule Events With wp_schedule_event

How to Schedule Events With wp_schedule_event

Short answer

Call wp_schedule_event with a Unix timestamp for the first run, a recurrence such as daily, and a hook name, after attaching your function to that hook with add_action. Guard the call with wp_next_scheduled so the event is booked only once. The event then fires on the first site visit after its time passes, so a server cron job is needed for exact timing.

Key takeaways

  • wp_schedule_event books a hook to repeat at a set interval such as daily.
  • The built-in recurrences are hourly, twicedaily, daily, and weekly.
  • Guard the call with wp_next_scheduled so the event is booked only once.
  • Mismatched arguments create duplicate events and bloat the cron option.
  • Unschedule on deactivation, since WordPress keeps running orphaned events.

What does wp_schedule_event do?

wp_schedule_event books a hook to run again and again at a set interval, such as every hour or every day.

The WordPress function reference states that the function schedules a hook which will be triggered by WordPress at the specified interval (checked November 2026).

The action runs when someone visits the site after the scheduled time has passed. The reference states that the action will trigger when someone visits your WordPress site if the scheduled time has passed (checked November 2026).

That visit rule is the key limit of the whole system. WP-Cron is not a clock that wakes on its own, so a quiet site can run its events late.

The function takes five parameters, of which three are required. The reference lists $timestamp, $recurrence, and $hook as required, with $args and $wp_error as optional (checked November 2026).

What are the built-in recurrence intervals?

WordPress ships with four recurrence intervals: hourly, twicedaily, daily, and weekly.

The WordPress function reference states that the valid values for the recurrence are hourly, twicedaily, daily, and weekly, and that they can be extended using the cron_schedules filter in wp_get_schedules (checked November 2026).

The wp_get_schedules reference gives the interval of each in seconds: hourly is 3600, twicedaily is 43200, daily is 86400, and weekly is one week in seconds (checked November 2026).

RecurrenceInterval in secondsHow often it runs
hourly3600Once an hour
twicedaily43200Twice a day, every 12 hours
daily86400Once a day
weekly604800Once a week

The weekly schedule is the newest of the four. The wp_get_schedules reference states that the weekly schedule was added in WordPress 5.4.0, while the function itself dates to 2.1.0 (checked November 2026).

The reference also gives a monthly example for a custom schedule: 30 days in seconds is 2592000, using the MONTH_IN_SECONDS constant (checked November 2026).

For a one-off task that should run once and never repeat, use wp_schedule_single_event instead. The WordPress function reference states that the single event function is the choice for a non-recurring event (checked November 2026).

How do you schedule your first recurring event?

Register the callback first, then schedule the event once, guarded so it is only booked a single time.

The Plugin Handbook states that the WP-Cron system uses hooks to add new scheduled tasks, and that you must create your own custom hook and give that hook the name of a function to run (checked November 2026).

  1. Attach your function to a custom hook with add_action:
add_action( 'bl_cron_hook', 'bl_cron_exec' );
  1. Schedule the event with a timestamp, a recurrence, and the hook name:
wp_schedule_event( time(), 'five_seconds', 'bl_cron_hook' );

The Plugin Handbook states that the three required parameters are the Unix timestamp of the first run, the name of the interval, and the name of the custom hook to call (checked November 2026).

The handbook example uses a five second custom interval and the bl_cron_hook name, with time() as the first run, meaning now (checked November 2026).

The timestamp must be a Unix timestamp in UTC. Use time() for now, or a future timestamp when the first run should wait.

A real example books a daily cleanup like this, with the hook name prefixed so it cannot clash with another plugin:

add_action( 'myplugin_daily_cleanup', 'myplugin_run_cleanup' );

if ( ! wp_next_scheduled( 'myplugin_daily_cleanup' ) ) {
    wp_schedule_event( time(), 'daily', 'myplugin_daily_cleanup' );
}

Schedule the event during plugin activation or another one-time setup step, not on every page load. A guide on how to fix WP-Cron not running covers what happens when the schedule call itself is the fault.

How do you stop the same event being scheduled twice?

Guard the schedule call with wp_next_scheduled, which returns the next run time or false when nothing is booked.

The Plugin Handbook states that calling wp_schedule_event more than once, even with the same hook name, schedules the event more than once, and that code running on each page load could book the task several thousand times (checked November 2026).

The handbook states that WordPress provides wp_next_scheduled to check whether a hook is already scheduled, and that it takes the hook name and returns either the timestamp of the next run or false (checked November 2026).

if ( ! wp_next_scheduled( 'bl_cron_hook' ) ) {
    wp_schedule_event( time(), 'five_seconds', 'bl_cron_hook' );
}

The WordPress function reference states the same advice in one line: use wp_next_scheduled to prevent duplicate events (checked November 2026).

The arguments matter as much as the hook name. The reference states that the arguments are used to uniquely identify the scheduled event, and that mismatched arguments make WordPress treat the event as different, which can lead to duplicate events, excess growth of the cron option, and database performance issues (checked November 2026).

Pass the same argument array every time you schedule, check, or unschedule the event. A single changed value creates a second event that runs beside the first.

How do you add a custom recurrence interval?

Add a custom interval with the cron_schedules filter, giving it a name, an interval in seconds, and a display label.

The wp_get_schedules reference states that a plugin may add more schedules by hooking into the cron_schedules filter, and that each entry needs an interval in seconds and a display string (checked November 2026).

add_filter( 'cron_schedules', 'myplugin_add_five_second_schedule' );

function myplugin_add_five_second_schedule( $schedules ) {
    $schedules['five_seconds'] = array(
        'interval' => 5,
        'display'  => __( 'Every Five Seconds' ),
    );
    return $schedules;
}

Add to the array you are given and return the whole thing. Replacing the array would wipe out the intervals other plugins registered, and their tasks would quietly stop.

Register the filter before you call wp_schedule_event with the new interval name. The schedule must exist when the event is booked, or the call fails.

The WordPress function reference states that an unknown recurrence makes the function fail, and that passing $wp_error as true returns a WP_Error with the code invalid_schedule instead of a plain false (checked November 2026).

A bad timestamp fails the same way, with the code invalid_timestamp. The $wp_error parameter was added in WordPress 5.7.0, while the function itself dates to 2.1.0 and its boolean return arrived in 5.1.0 (checked November 2026).

How do you unschedule an event?

Remove an event with wp_unschedule_event, passing the timestamp of its next run and the hook name.

The Plugin Handbook states that the function takes the timestamp of the next occurrence and the hook name, and that it unschedules that occurrence and all future occurrences of the task (checked November 2026).

You rarely know the next timestamp by heart, so find it first with wp_next_scheduled:

$timestamp = wp_next_scheduled( 'bl_cron_hook' );
wp_unschedule_event( $timestamp, 'bl_cron_hook' );

The handbook states that it is very important to unschedule tasks when you no longer need them, because WordPress will keep trying to run them even after your plugin has been deactivated or removed (checked November 2026).

The right place to clean up is the deactivation hook. The handbook gives this pattern with register_deactivation_hook, which runs a function when the plugin is deactivated (checked November 2026).

register_deactivation_hook( __FILE__, 'bl_deactivate' );

function bl_deactivate() {
    $timestamp = wp_next_scheduled( 'bl_cron_hook' );
    wp_unschedule_event( $timestamp, 'bl_cron_hook' );
}

If you only need to clear every event on a hook without knowing timestamps, wp_clear_scheduled_hook removes them all at once. Use it on deactivation when a hook may hold several events with different arguments.

How do you check scheduled events with WP-CLI?

List the queue with wp cron event list, which shows every scheduled event, its next run time, and its recurrence.

The WP-CLI command reference states that the default fields shown are hook, next_run_gmt, next_run_relative, and recurrence (checked November 2026).

wp cron event list

Run one due event by hook name with wp cron event run, or run everything due now with the --due-now flag. The WP-CLI command reference gives wp cron event run --due-now as the command to run all cron events due right now (checked November 2026).

The same reference lists the other event commands: wp cron event schedule books a new event, wp cron event delete removes all events for a hook, and wp cron event unschedule clears them (checked November 2026).

For a JSON view you can filter or save, add fields and a format flag. The reference gives wp cron event list --fields=hook,next_run --format=json as the example for listing events as JSON (checked November 2026).

Without SSH access, the dashboard can show the same queue. WordPress.org states that the WP Crontrol plugin shows all scheduled events with their arguments, schedule, callback functions, and next due time, and can edit, delete, pause, or run events from the admin screens (checked November 2026).

When a plugin leaves old events behind after deactivation, a guide on how to fix WooCommerce Action Scheduler past due actions shows how stale scheduled work is cleared.

How do you fix events that never run?

First confirm the event is actually booked, then confirm something triggers WP-Cron at all.

Run wp cron event list and look for your hook. If it is missing, the schedule call never ran or ran with the wrong hook name, so check the activation code and the guard.

If the event is listed but its next run time keeps passing, WP-Cron itself is not firing. The WordPress function reference states that the action triggers when someone visits the site, so a site with no visits runs nothing (checked November 2026).

The fix is a server cron job that calls wp-cron.php on the clock. Kinsta states that the job should be set up before WP-Cron is disabled, and that disabling first stops scheduled tasks silently, with no errors, just missed jobs (checked November 2026).

Hosts with cPanel offer the same job through a screen instead of a crontab file. cPanel docs state that the Cron Jobs screen asks for Minute, Hour, Day, Month, Weekday, and Command values, and warns to leave enough time between jobs so one run finishes before the next starts (checked November 2026).

A guide on how to disable WP-Cron and use a real cron job walks through that switch step by step.

If scheduled posts miss their time while other events run, the fault is narrower. A guide on how to fix scheduled posts with a missed schedule covers that case.

What mistakes should you avoid?

The most common mistake is calling wp_schedule_event on every page load with no guard, which books the same event thousands of times.

Always wrap the call in if ( ! wp_next_scheduled( 'your_hook' ) ), and prefer booking it on plugin activation.

A second mistake is changing the arguments between calls. The same hook with different arguments is a different event to WordPress, so keep one exact argument array through the whole life of the event.

A third mistake is scheduling with a custom interval before registering it. The cron_schedules filter must run first, or the schedule call fails with an invalid schedule error.

A fourth mistake is leaving events behind on deactivation. Add the unschedule code to the deactivation hook, since WordPress keeps running orphaned events after the plugin is gone.

Finally, do not expect exact timing from WP-Cron. Events run on the first visit after their time passes, so a daily event on a quiet site can run hours late unless a server cron job drives it.

Frequently asked questions

When should I use wp_schedule_single_event instead?

Use wp_schedule_single_event for a task that runs once at a set time, such as sending one reminder. Use wp_schedule_event for work that repeats, such as a daily cleanup or a weekly report. The single event function takes a timestamp and a hook, with no recurrence.

Can I add a recurrence interval that WordPress does not ship with?

Yes, with the cron_schedules filter. Add an entry with an interval in seconds and a display label, such as a five second interval for short jobs. Register the filter before you call wp_schedule_event with the new name, and always add to the array you receive instead of replacing it.

Does wp_schedule_event run my function right away?

No. wp_schedule_event only books the event; it does not run the callback at once. The first run happens when WP-Cron fires after the timestamp passes, which needs a site visit or a server cron job. Call the callback directly, or run wp cron event run for the hook, when you need an instant run.

What does wp_schedule_event return when scheduling fails?

No. It returns true when the event was booked, or false when it failed. Pass true as the fifth argument, $wp_error, to get a WP_Error instead of false, with codes such as invalid_timestamp or invalid_schedule. That option arrived in WordPress 5.7.0.

Can two events share the same hook name?

Yes, but only with the same hook name and the same argument array. WordPress treats a different argument array as a different event, so a changed value books a second event beside the first. Keep one exact argument array for scheduling, checking, and unscheduling.

Sources

  1. wp_schedule_event() – Function WordPress Developer Resources
  2. Scheduling WP Cron Events WordPress Developer Resources
  3. wp_get_schedules() – Function WordPress Developer Resources
  4. wp cron event – WP-CLI Command WordPress Developer Resources
  5. wp cron event list – WP-CLI Command WordPress Developer Resources
  6. Disabling WP-Cron (wp-cron.php) for Faster Performance Kinsta
  7. WP Crontrol – WordPress plugin WordPress.org
  8. Cron Jobs | cPanel & WHM Documentation cPanel

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test