The Complete as_schedule_single_action Reference

/ Signature

What is the as_schedule_single_action signature?

as_schedule_single_action() schedules one background action to run once, at or after a given Unix timestamp. It is a global function shipped with Action Scheduler, the background-job library maintained by WooCommerce and bundled inside WooCommerce, Jetpack, and hundreds of other plugins. When the scheduled time arrives, the queue runner calls do_action( $hook, ...$args ), so the code that actually runs is an ordinary WordPress hook callback registered with add_action().

PHP — as_schedule_single_action full signature

as_schedule_single_action(
    int    $timestamp,           // Unix time of the earliest run
    string $hook,                // action hook fired via do_action()
    array  $args     = [],       // args spread into the callback
    string $group    = '',       // label for filtering / bulk cancel
    bool   $unique   = false,    // skip if an identical action is pending
    int    $priority = 10        // 0-255, lower runs first (AS 3.5+)
): int;  // returns the action ID, or 0 on failure

The $unique parameter was added in Action Scheduler 3.3.0 and $priority in 3.5.0. On older bundled versions those trailing arguments are simply ignored, so passing them is safe but has no effect until the host site ships a recent enough copy.

/ Parameters

What does each as_schedule_single_action parameter do?

The first two arguments are required; the rest are optional. Getting $args and $group right matters most, because they are what the deduplication and cancellation functions match on.

/ Timestamp

How precise is the $timestamp argument?

The timestamp is a floor, not an alarm clock. Action Scheduler runs a queue on each WP-Cron pass (or Action Scheduler's own runner), claims a batch of actions whose scheduled_date is in the past, and executes them. So an action set for time() + 5 runs on the first queue pass after those five seconds — which could be a few seconds late on a busy site, or longer if no traffic triggers WP-Cron. If you need clock-aligned execution (always at 06:00), use as_schedule_cron_action() instead; if you need it to run as soon as possible with no delay target at all, use as_enqueue_async_action().

/ Return value

What does as_schedule_single_action return?

It returns the integer action ID — the primary key of the new row in the wp_actionscheduler_actions table. Store it if you plan to cancel or inspect the action later. Two edge cases change what you get back:

1. Duplicate skipped. When $unique = true and a matching pending or in-progress action already exists, the call returns that existing action's ID and inserts nothing.
2. Failure. If the action store cannot save the row, the function returns 0. Treat a falsy return as "not scheduled" rather than assuming success.

Every scheduled action maps to a WordPress hook. When the action runs, Action Scheduler calls do_action($hook, ...$args) — the callback is just a normal hook handler. — Action Scheduler usage guide

/ Deduplication

How does $unique prevent duplicate single actions?

Passing $unique = true makes the scheduling call idempotent: before inserting, Action Scheduler looks for a pending or running action with the same hook, the same serialised $args, and the same group. If one exists, no new row is created. This is the race-safe way to guarantee "at most one queued job" for an event, because the check and the insert happen inside the same call rather than in your application code. The matching is exact, though — a different argument value, order, or type counts as a distinct action. For the guard-based alternative and the exact matching rules, see preventing duplicate scheduled actions.

PHP — schedule one delayed, deduplicated webhook

// Deliver a webhook 30s after checkout — but only once per order
$action_id = as_schedule_single_action(
    time() + 30,
    'myplugin_deliver_order_webhook',
    [ 'order_id' => $order_id ],
    'order-webhooks',
    true            // unique: repeated saves won't queue a 2nd delivery
);

add_action( 'myplugin_deliver_order_webhook', function( $order_id ) {
    $order = wc_get_order( $order_id );
    wp_remote_post( 'https://example.com/hook', [
        'body' => wp_json_encode( $order->get_data() ),
    ] );
} );

/ vs WP-Cron

How is it different from wp_schedule_single_event?

Both schedule a one-time hook, but the storage and reliability differ sharply. wp_schedule_single_event() stores every event in a single serialised cron row in wp_options, runs on visitor page loads, keeps no history, and never retries. as_schedule_single_action() stores one row per action, is claimed by a dedicated queue runner, retries failures, and logs every attempt.

/ In practice

Do you call as_schedule_single_action for webhooks directly?

Usually not. Firing an outbound webhook when a WordPress or WooCommerce event happens is event-driven, not time-delayed: you hook do_action and POST on the event itself, ideally behind a queue that adds retry with exponential backoff and a delivery log. You reach for as_schedule_single_action() in your own code when you need a delayed one-off job that is not a webhook: a reminder email, a cleanup pass, a deferred API sync. For the full function family — async, recurring, cron, query and cancel — see the Action Scheduler PHP API reference.