This document covers the public unscheduling helpers in Action Scheduler.

Overview

Unscheduling cancels existing scheduled actions. For recurring and cron actions, Action Scheduler only ever schedules the next occurrence. Canceling that next occurrence effectively prevents the entire series from continuing, because future occurrences are only scheduled after the previous one runs.

as_unschedule_action()

Cancel the next occurrence of a scheduled action.

Signature

as_unschedule_action( string $hook, array $args = array(), string $group = '' ): ?int

Parameters

• $hook (string) — Hook name to match.
• $args (array) — Args to match. If not an array, args are ignored for matching.
• $group (string) — Group name to match.

Returns

• int|null — The canceled action ID if one was found, or null if none matched.

Behavior

• Only the next pending action is canceled.
• For recurring or cron actions, canceling the next occurrence prevents future occurrences from being scheduled (because each next run is scheduled only after the current one completes).
• If an error occurs while canceling, the error is logged and null is returned.

Example

// Cancel the next pending cleanup action.
$canceled_id = as_unschedule_action(
    'myplugin_cleanup_temp',
    array( 'scope' => 'uploads' ),
    'myplugin'
);

if ( null === $canceled_id ) {
    // No matching action was found (or an error occurred while canceling).
}

Edge cases

• If Action Scheduler is not initialized, the function returns 0 (not null).
• If $args is not an array, it is ignored for matching.
• If multiple pending actions match, the earliest scheduled one (by date ASC) is canceled.

as_unschedule_all_actions()

Cancel all occurrences of a scheduled action.

Signature

as_unschedule_all_actions( string $hook, array $args = array(), string $group = '' ): void

Parameters

• $hook (string) — Hook name to match.
• $args (array) — Args to match. When empty, broader cancellation paths may be used.
• $group (string) — Group name to match.

Returns

• void

Behavior

• If $args is empty and only $hook is provided, all actions for that hook are canceled.
• If $args is empty and only $group is provided, all actions in that group are canceled.
• Otherwise, it repeatedly calls as_unschedule_action() until no matching actions remain.

Effect on recurring/cron actions

Canceling the next occurrence of a recurring or cron action prevents future runs from being scheduled. Using as_unschedule_all_actions() ensures all matching next occurrences are canceled across all matching actions, effectively stopping each series.

Example

// Cancel all actions for a hook.
as_unschedule_all_actions( 'myplugin_cleanup_temp' );

// Cancel all actions for a specific hook + args + group.
as_unschedule_all_actions(
    'myplugin_sync_catalog',
    array( 'source' => 'api' ),
    'myplugin'
);

Edge cases

• If Action Scheduler is not initialized, the function returns early.
• When $args is empty, the helper may perform broad cancellations by hook or by group.