This document covers the public scheduling helpers exposed by Action Scheduler.

Overview

Use these functions to enqueue or schedule actions to run now, once in the future, on a fixed interval, or on a cron-like schedule. All functions return the scheduled action ID on success and 0 on failure.

Common concepts:

• Hook: The action name that will be triggered when the job runs.
• Args: Array of arguments passed to the hook callback.
• Group: A string for grouping related actions.
• Unique: When true, an action is only scheduled if there is not already a pending or running action with the same hook and group.
• Priority: Lower values run first. Accepted values: 0–255. Default: 10.

Note: These helpers do not validate hook callbacks; ensure you register your callback with add_action( $hook, ... ).

as_enqueue_async_action()

Enqueue an action to run one time, as soon as possible.

Signature

as_enqueue_async_action( string $hook, array $args = array(), string $group = '', bool $unique = false, int $priority = 10 ): int

Parameters

• $hook (string) — Hook to trigger.
• $args (array) — Arguments passed to the hook callback.
• $group (string) — Group name for the action.
• $unique (bool) — If true, do not enqueue if a pending or running action with the same hook and group already exists.
• $priority (int) — Lower values run first; default 10 (range 0–255).

Returns

• int — Action ID on success; 0 on failure.

Filters

• pre_as_enqueue_async_action — Short-circuit scheduling.
  • Signature: apply_filters( 'pre_as_enqueue_async_action', ?int $pre, string $hook, array $args, string $group, int $priority, bool $unique )
  • Return a non-null integer to bypass the default scheduling logic. Any non-int return is treated as 0.

Example

// Enqueue an async action to run ASAP.
$action_id = as_enqueue_async_action(
    'myplugin_process_queue',
    array( 'queue_id' => 42 ),
    'myplugin',
    true
);

if ( 0 === $action_id ) {
    // Scheduling failed.
}

Edge cases

• If Action Scheduler is not initialized, returns 0.
• When $unique is true, uniqueness is scoped to hook + group (not args).
• Returning any non-null value from the filter bypasses the default logic, so ensure your filter returns a valid action ID or 0.

as_schedule_single_action()

Schedule a one-time action to run at a specific timestamp.

Signature

as_schedule_single_action( int $timestamp, string $hook, array $args = array(), string $group = '', bool $unique = false, int $priority = 10 ): int

Parameters

• $timestamp (int) — Unix timestamp when the action should run (UTC).
• $hook (string) — Hook to trigger.
• $args (array) — Arguments passed to the hook callback.
• $group (string) — Group name for the action.
• $unique (bool) — If true, do not schedule if a pending or running action with the same hook and group already exists.
• $priority (int) — Lower values run first; default 10 (range 0–255).

Returns

• int — Action ID on success; 0 on failure.

Filters

• pre_as_schedule_single_action — Short-circuit scheduling.
  • Signature: apply_filters( 'pre_as_schedule_single_action', ?int $pre, int $timestamp, string $hook, array $args, string $group, int $priority, bool $unique )
  • Return a non-null integer to bypass the default scheduling logic. Any non-int return is treated as 0.

Example

$timestamp = time() + HOUR_IN_SECONDS;

$action_id = as_schedule_single_action(
    $timestamp,
    'myplugin_send_report',
    array( 'report_id' => 99 ),
    'myplugin'
);

Edge cases

• If Action Scheduler is not initialized, returns 0.
• If $timestamp is in the past, Action Scheduler will run it as soon as possible.
• When $unique is true, uniqueness is scoped to hook + group (not args).

as_schedule_recurring_action()

Schedule a recurring action to run on a fixed interval (in seconds).

Signature

as_schedule_recurring_action( int $timestamp, int $interval_in_seconds, string $hook, array $args = array(), string $group = '', bool $unique = false, int $priority = 10 ): int

Parameters

• $timestamp (int) — Unix timestamp for the first run (UTC).
• $interval_in_seconds (int) — Interval between runs, in seconds.
• $hook (string) — Hook to trigger.
• $args (array) — Arguments passed to the hook callback.
• $group (string) — Group name for the action.
• $unique (bool) — If true, do not schedule if a pending or running action with the same hook and group already exists.
• $priority (int) — Lower values run first; default 10 (range 0–255).

Returns

• int — Action ID on success; 0 on failure.

Filters

• pre_as_schedule_recurring_action — Short-circuit scheduling.
  • Signature: apply_filters( 'pre_as_schedule_recurring_action', ?int $pre, int $timestamp, int $interval_in_seconds, string $hook, array $args, string $group, int $priority, bool $unique )
  • Return a non-null integer to bypass the default scheduling logic. Any non-int return is treated as 0.

Example

// Run every 15 minutes, starting at the next quarter hour.
$timestamp = time() + ( 15 * MINUTE_IN_SECONDS );
$interval  = 15 * MINUTE_IN_SECONDS;

$action_id = as_schedule_recurring_action(
    $timestamp,
    $interval,
    'myplugin_sync_catalog',
    array( 'source' => 'api' ),
    'myplugin',
    true
);

Edge cases

• If $interval_in_seconds is not numeric or is not an integer value (even if numeric), Action Scheduler triggers _doing_it_wrong() and returns 0.
• Recurring actions are scheduled sequentially. Each next occurrence is scheduled after the previous run completes.
• When $unique is true, uniqueness is scoped to hook + group (not args).

as_schedule_cron_action()

Schedule a recurring action based on a cron-like expression.

Signature

as_schedule_cron_action( int $timestamp, string $schedule, string $hook, array $args = array(), string $group = '', bool $unique = false, int $priority = 10 ): int

Parameters

• $timestamp (int) — Base timestamp. The first run is calculated after this time and must match the cron expression.
• $schedule (string) — Cron-like schedule string.
• $hook (string) — Hook to trigger.
• $args (array) — Arguments passed to the hook callback.
• $group (string) — Group name for the action.
• $unique (bool) — If true, do not schedule if a pending or running action with the same hook and group already exists.
• $priority (int) — Lower values run first; default 10 (range 0–255).

Returns

• int — Action ID on success; 0 on failure.

Filters

• pre_as_schedule_cron_action — Short-circuit scheduling.
  • Signature: apply_filters( 'pre_as_schedule_cron_action', ?int $pre, int $timestamp, string $schedule, string $hook, array $args, string $group, int $priority, bool $unique )
  • Return a non-null integer to bypass the default scheduling logic. Any non-int return is treated as 0.

Example

// Run daily at 02:30 UTC.
$timestamp = time();
$cron      = '30 2 * * *';

$action_id = as_schedule_cron_action(
    $timestamp,
    $cron,
    'myplugin_daily_cleanup',
    array(),
    'myplugin'
);

Edge cases

• Cron actions are scheduled sequentially, just like recurring actions. Only the next occurrence is stored at any time.
• The first run will always be after $timestamp and must match the cron expression.
• When $unique is true, uniqueness is scoped to hook + group (not args).