wp_clear_scheduled_hook( string $hook, array $args = array(), bool $wp_error = false ): int|false|WP_Error

Unschedules all events attached to the hook with the specified arguments.


Warning: This function may return boolean false, but may also return a non-boolean value which evaluates to false. For information about casting to booleans see the PHP documentation. Use the === operator for testing the return value of this function.


Action hook, the execution of which will be unscheduled.
Array containing each separate argument to pass to the hook’s callback function.
Although not passed to a callback, these arguments are used to uniquely identify the event, so they should be the same as those used when originally scheduling the event.


Whether to return a WP_Error on failure.



int|false|WP_Error On success an integer indicating number of events unscheduled (0 indicates no events were registered with the hook and arguments combination), false or WP_Error if unscheduling one or more events fail.

More Information

If you created a scheduled job using a hook and arguments, you cannot delete it by supplying only the hook. Similarly, if you created a set of scheduled jobs that share a hook but have different arguments, you cannot delete them using only the hook name, you have to delete them all individually using the hook name and arguments.


function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
	 * Backward compatibility.
	 * Previously, this function took the arguments as discrete vars rather than an array like the rest of the API.
	if ( ! is_array( $args ) ) {
			__( 'This argument has changed to an array to match the behavior of the other cron functions.' )

		$args     = array_slice( func_get_args(), 1 ); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
		$wp_error = false;

	 * Filter to override clearing a scheduled hook.
	 * Returning a non-null value will short-circuit the normal unscheduling
	 * process, causing the function to return the filtered value instead.
	 * For plugins replacing wp-cron, return the number of events successfully
	 * unscheduled (zero if no events were registered with the hook) or false
	 * or a WP_Error if unscheduling one or more events fails.
	 * @since 5.1.0
	 * @since 5.7.0 The `$wp_error` parameter was added, and a `WP_Error` object can now be returned.
	 * @param null|int|false|WP_Error $pre      Value to return instead. Default null to continue unscheduling the event.
	 * @param string                  $hook     Action hook, the execution of which will be unscheduled.
	 * @param array                   $args     Arguments to pass to the hook's callback function.
	 * @param bool                    $wp_error Whether to return a WP_Error on failure.
	$pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args, $wp_error );

	if ( null !== $pre ) {
		if ( $wp_error && false === $pre ) {
			return new WP_Error(
				__( 'A plugin prevented the hook from being cleared.' )

		if ( ! $wp_error && is_wp_error( $pre ) ) {
			return false;

		return $pre;

	 * This logic duplicates wp_next_scheduled().
	 * It's required due to a scenario where wp_unschedule_event() fails due to update_option() failing,
	 * and, wp_next_scheduled() returns the same schedule in an infinite loop.
	$crons = _get_cron_array();
	if ( empty( $crons ) ) {
		return 0;

	$results = array();
	$key     = md5( serialize( $args ) );

	foreach ( $crons as $timestamp => $cron ) {
		if ( isset( $cron[ $hook ][ $key ] ) ) {
			$results[] = wp_unschedule_event( $timestamp, $hook, $args, true );

	$errors = array_filter( $results, 'is_wp_error' );
	$error  = new WP_Error();

	if ( $errors ) {
		if ( $wp_error ) {
			array_walk( $errors, array( $error, 'merge_from' ) );

			return $error;

		return false;

	return count( $results );


apply_filters( ‘pre_clear_scheduled_hook’, null|int|false|WP_Error $pre, string $hook, array $args, bool $wp_error )

Filter to override clearing a scheduled hook.


5.7.0The $wp_error parameter was added.
5.1.0Return value modified to indicate success or failure, 'pre_clear_scheduled_hook' filter added to short-circuit the function.

User Contributed Notes

  1. Skip to note 2 content

    Basic Example

    Clear a scheduled event

    // If you previously added for example
    // wp_schedule_single_event( time() + 3600, 'my_new_event' );
    wp_clear_scheduled_hook( 'my_new_event' );
    // or this if you created something like
    // wp_schedule_single_event( time() + 3600, 'my_new_event', array( 'some_arg' ) );
    wp_clear_scheduled_hook( 'my_new_event', array( 'some_arg' ) );

You must log in before being able to contribute a note or feedback.