wp_clear_scheduled_hook( string $hook, array $args = array(), bool $wp_error = false )

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

Description Description

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.

Top ↑

Parameters Parameters


(string) (Required) Action hook, the execution of which will be unscheduled.


(array) (Optional) 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.

Default value: array()


(bool) (Optional) Whether to return a WP_Error on failure.

Default value: false

Top ↑

Return Return

(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.

Top ↑

More Information 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.

Top ↑

Source Source

File: wp-includes/cron.php

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 ) ) {
		_deprecated_argument( __FUNCTION__, '3.0.0', __( '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 preflight or hijack 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
	 * 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 );

Top ↑

Changelog Changelog

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

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    Contributed by Codex

    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.