Add a Custom WP-Cron Interval in WordPress

WordPress core ships with four WP-Cron intervals: hourly, twicedaily, daily and weekly. If you need anything else, such as every 5 minutes, register a custom interval with the cron_schedules filter and then schedule your event with wp_schedule_event().

The order matters. The custom interval has to exist before you schedule an event that uses it, otherwise WordPress rejects the event.

Add a Custom Cron Interval

Add this to your child theme’s functions.php or to a plugin. It registers a 5-minute interval, schedules one recurring event on it, and attaches the task.

// 1. Register the interval.
add_filter( 'cron_schedules', function ( $schedules ) {
	$schedules['every_five_minutes'] = array(
		'interval' => 5 * MINUTE_IN_SECONDS,
		'display'  => 'Every 5 Minutes',
	);
	return $schedules;
} );

// 2. Schedule the event once, if it isn't scheduled yet.
add_action( 'init', function () {
	if ( ! wp_next_scheduled( 'my_custom_cron_event' ) ) {
		wp_schedule_event( time(), 'every_five_minutes', 'my_custom_cron_event' );
	}
} );

// 3. The task that runs on each interval.
add_action( 'my_custom_cron_event', function () {
	// Your code here.
} );

How It Works

The cron_schedules filter lets you add entries to the list of recurrences. Each entry needs a unique key, an interval in seconds, and a display label shown by tools like WP-CLI.

wp_schedule_event( $timestamp, $recurrence, $hook ) stores the event. The first run happens at $timestamp, then every interval after that. The wp_next_scheduled() check prevents a duplicate event on every page load.

When the event is due, WordPress fires the hook name you passed, so any function attached with add_action() runs. For a refresher on actions and filters, see WordPress hooks explained.

WordPress Default Cron Intervals

These recurrences are available without any filter. The weekly schedule was added in WordPress 5.4.

So for a weekly task on WordPress 5.4 or later, skip the filter and pass 'weekly' directly, as in this weekly transient cleanup. You also can’t redefine these four keys, core defaults override filter entries with the same name.

Common Mistakes

Most WP-Cron problems with custom intervals come down to one of these.

• Scheduling before the filter exists. If the interval isn’t registered when wp_schedule_event() runs, it returns false (or a WP_Error with code invalid_schedule when you pass true as the fifth argument).
• Switching the event to another schedule key. If you change 'every_five_minutes' in the wp_schedule_event() call, the existing event keeps its old recurrence, because wp_next_scheduled() still finds it. Run wp_clear_scheduled_hook( 'my_custom_cron_event' ) once, then let the code schedule it again.
• Not cleaning up. In a plugin, clear the hook on deactivation with register_deactivation_hook() so the event doesn’t keep firing into nothing.
• Expecting exact timing. WP-Cron only runs when someone visits the site, so a 5-minute task on a quiet site runs late.

For reliable timing, set DISABLE_WP_CRON to true and trigger cron from the server instead. The steps are in Disable WP-Cron and use a real server cron job.

To check that your interval and event were registered, run these WP-CLI commands:

wp cron schedule list
wp cron event list

The full parameter list is in the wp_schedule_event() reference.

FAQs

Common questions about custom WP-Cron intervals: