Action Scheduler

WordPress ships its own scheduler, WP-Cron: wp_schedule_single_event(), wp_schedule_event() and the hooks they fire. It is fine for a small periodic task, but it has properties that matter on a busy shop:

Action Scheduler keeps the WP-Cron API shape (as_schedule_single_action() mirrors wp_schedule_single_event()) but stores each job in its own tables, claims jobs before running them so that two runners never run the same job, records a log line for every state change and exposes the queue in an admin screen and in WP-CLI. It still uses WP-Cron as one way to start a queue run, which is the subject of a later section. WP-Cron itself, with a system cron and Action Scheduler outside WooCommerce, is covered in WP-Cron and Scheduled Tasks.

Source: WordPress Plugin Handbook: Cron

Source: Action Scheduler: API reference (WP-Cron APIs vs. Action Scheduler APIs)

Action Scheduler is developed in the open (https://github.com/woocommerce/action-scheduler) and can be used in three ways: bundled inside a plugin as a library, installed as an ordinary plugin from WordPress.org (slug action-scheduler), or required through Composer as the package woocommerce/action-scheduler (type wordpress-plugin; the package list on Packagist showed 59 versions with 4.2.0 as the newest on 2026-10-27). WooCommerce bundles it under wp-content/plugins/woocommerce/packages/action-scheduler.

The bundled library follows its own release line, which is why the version differs from WooCommerce’s:

The header of the bundled 4.1.0 copy declares Requires at least: 6.8, Tested up to: 7.0 and Requires PHP: 7.2. Its documentation describes an "L-2" policy for the library (the latest minus two WordPress versions), which is wider than the L-1 policy of WooCommerce itself; see Versions, Requirements and Release Cadence.

WooCommerce itself uses the queue heavily. On the test site, which has only sample data, the actions table held these groups and hooks after a few hours: woocommerce_run_product_attribute_lookup_update_callback (group woocommerce-db-updates, 176 pending), wc-admin_import_orders (group wc-admin-data, the analytics import), woocommerce_deliver_webhook_async (group woocommerce-webhooks, webhook delivery), wc_schedule_pending_batch_processes (group wc_batch_processes), woocommerce_delete_legacy_report_transients, and the library’s own action_scheduler/migration_hook and action_scheduler_run_recurring_actions_schedule_hook. An extension that slows or blocks the queue therefore slows down WooCommerce itself, not only its own jobs.

Source: Action Scheduler: Usage (installation, loading, load order)

Source: Action Scheduler: FAQ

Since Action Scheduler 3.0 the data is in four custom tables, created with the site’s table prefix (wp_ below):

The arguments are stored as JSON. When the JSON is up to 191 characters it is kept in the args column (an index column); a longer array is stored in extended_args (varchar(8000)) and args holds a hash of it. Only values that survive wp_json_encode() come back identical, so pass scalars and small arrays, and pass the ID of an order rather than the order.

An action is always in one of five statuses, constants of ActionScheduler_Store:

The store behind the tables is swappable (action_scheduler_store_class), as are the logger (action_scheduler_logger_class), the lock (action_scheduler_lock_class) and the runner (action_scheduler_queue_runner_class). On the test site wp action-scheduler data-store printed ActionScheduler_HybridStore: the store that serves a site while old post-based actions are still being migrated. The migration action (action_scheduler/migration_hook) had been pending since the site was created because nothing had processed the queue yet, which is a first example of the WP-Cron dependency discussed below.

Source: Action Scheduler: FAQ (How does Action Scheduler store its data)

All functions live in the global namespace and are loaded by the winning copy of the library. Every scheduling function returns the numeric action ID, or 0 when the action could not be stored or, with $unique set, when an identical action is already pending or running.

Four parameters have the same meaning in all scheduling functions:

When it is safe to call the API. The functions exist as soon as a copy of the library is loaded, but its stores are only initialized on init at priority 1. Called earlier, a function logs a "doing it wrong" notice and returns 0. Hook the work to init priority 2 or later, or to the action action_scheduler_init, which fires once the stores are ready:

Source: Action Scheduler: API reference

Source: Action Scheduler: Usage (Load Order, Passing arguments)

The plugin below is the whole example. It needs WooCommerce (Requires Plugins: woocommerce, see Extension Development), declares compatibility with High-Performance Order Storage, and uses five of the scheduling patterns: an async action per new order, a delayed single action, a recurring action, a cron action, and a callback that retries itself. It passes PHP_CodeSniffer with the WooCommerce-Core and WordPress-Extra standards (no findings) and ran on the test site.

The plugin removes its pending actions when it is deleted. Its uninstall.php:

Source: Action Scheduler: API reference

Source: Action Scheduler: Usage (Scheduling Recurring Actions on Activation and Ensuring They Remain Scheduled)

The points worth noting in the code:

Three behaviours of the query and cancel functions caused surprises while building the example.

as_get_scheduled_actions() returns five rows unless told otherwise. per_page defaults to 5, status defaults to every status, and date_compare defaults to <=. With 33 pending review requests in the queue:

printed 5 and 33. Use per_page => -1 only when the number is bounded, and page with offset otherwise. The WP-CLI command passes its flags straight through, so --per_page=200 is needed there too.

Source: Action Scheduler: API reference (as_get_scheduled_actions)

Arguments match exactly. as_unschedule_action( 'pocket_coffee_review_request', array(), 'pocket-coffee' ) finds nothing when every row has array( $order_id ). as_has_scheduled_action() and as_next_scheduled_action() default $args to null, which means "any arguments", whereas as_unschedule_action() and as_unschedule_all_actions() default it to array(), which means "exactly no arguments".

as_unschedule_all_actions() has two shortcuts. The code of 4.1.0 branches on which of its parameters are empty:

The first version of the example’s uninstall.php called the third form for four hooks. After activating the plugin, creating orders and running wp plugin uninstall, 34 pocket_coffee_review_request rows were still pending, because each has an order ID as its argument. Replacing the loop with the second form (as_unschedule_all_actions( '', array(), 'pocket-coffee' ), the uninstall.php shown above) and repeating the test left 0 pending rows and 38 canceled ones. Cancelling only changes the status; the rows stay until the cleaner deletes them (see the queue runner section).

Source: Action Scheduler: API reference (as_unschedule_all_actions)

An action runs only when a queue runner claims it. A claim marks a batch of due pending actions with a claim_id so that a second runner skips them, and the runner then executes them one by one: status becomes in-progress, WordPress runs do_action( $hook, ...$args ), and the status becomes complete or failed.

There are three ways to start a runner:

The defaults of one run, all taken from the 4.1.0 code and from the performance guide:

The numbers are deliberately conservative so that the library works on shared hosting. A site that processes thousands of actions can raise the batch size, the time limit and the number of concurrent batches, but the performance guide warns that concurrent batches combined with the async loopback can take a site down: the preferred way to go faster is WP-CLI. The same filters take a plain function:

With WP-CLI a runner can be dedicated to one kind of job (--hooks takes a comma-separated list of hooks, --group one group, --exclude-groups a list of groups to leave out). The WP-CLI documentation recommends this at scale to avoid database contention, for example one runner for e-mails and another for payments, with the caveat that actions that depend on each other’s order must not be split across runners.

Source: Action Scheduler: Background Processing at Scale

Past-due actions are normal. A pending action whose date has passed is "past-due". Because WP-Cron needs traffic, a quiet shop shows past-due actions; the FAQ treats several past-due actions older than a day as a sign of a problem. On the test site the library’s own migration action stayed past-due for hours with the shop idle, and the 179 pending actions counted by wp action-scheduler status included the oldest one from 13:47.

Source: Action Scheduler: FAQ (My site has past-due actions)

Making WP-Cron reliable. The usual production set-up for WooCommerce stores is:

The system cron line itself was not installed on the test container; the WP-CLI command it relies on ran, as shown above with wp action-scheduler run. Without options the command works through batches of 100 actions (--batch-size) until nothing is due (--batches=0, the default); --force overrides the limit on concurrent batches, and --hooks, --group and --exclude-groups restrict what the runner claims.

One more observation from the test site: wp action-scheduler run --group=pocket-coffee failed with Error: There was an error running the action scheduler: The group "pocket-coffee" does not exist. even though the group existed in wp_actionscheduler_groups, while --hooks=... worked. The site was using the hybrid store (see above), and the error message comes from the old post-based store, which has no such group. A site whose migration has finished uses the plain database store and does not show this; the sentence is a reason to let the queue run until the migration action has completed before relying on --group.

Source: Action Scheduler: WP CLI

Source: WordPress Plugin Handbook: Cron

Replacing the web runners. To use only WP-CLI, stop the web runners. The documentation points to the plugin "Action Scheduler - Disable Default Queue Runner", whose effect can be written as two filters (shown for illustration, not run here):

If you do this, nothing runs the queue unless you run it; keep a monitor on the age of the oldest pending action.

Source: Action Scheduler: FAQ (I don’t want to use WP-Cron)

On Kubernetes the queue is usually run by dedicated worker pods and a CronJob rather than by web requests; see Cloud: Action Scheduler Workers on Kubernetes.

A failure is an exception or a dead process. When the callback throws any Exception, the runner marks the action failed, writes action failed via <context>: <message> to the log and fires action_scheduler_failed_execution with the action ID, the exception and the context. A PHP fatal error or a timeout is caught later, by the fatal-error monitor (hook action_scheduler_unexpected_shutdown) or by the cleaner when the action has been in-progress for more than the failure period.

The example plugin logs every failure through that hook. An action whose callback always throws (pocket_coffee_always_fails, Supplier API unreachable) produced:

and the action row reads status: failed with the log entries action created, action started via WP CLI and action failed via WP CLI: Supplier API unreachable.

A hook without a callback also fails. An action whose hook has no callback when the runner reaches it (the plugin that registered it is deactivated, or the callback is only added on certain requests) is marked failed with the message Scheduled action for pocket_coffee_orphan will not be executed as no callbacks are registered. Register callbacks unconditionally, early (at plugin load, not inside is_admin() or a template hook), because queue runs happen in WP-Cron, loopback and CLI contexts.

Nothing retries a failed action. Action Scheduler records the attempt (attempts and last_attempt_gmt columns) and moves on. If the job should be repeated, the callback schedules the next try itself, with a growing delay, and stops after a fixed number. That is the pocket_coffee_sync_supplier callback of the example (attempt 1 failed to reach the supplier, so it queued attempt 2 two minutes later, and attempt 3 would wait four minutes):

The first row is complete because the callback did not throw; it asked for a retry. Throw only for the final attempt, so that the last row ends as failed and the admin screen shows it. Because $unique is true and the arguments differ per attempt, the retry rows do not collide.

Recurring series can stop. For recurring and cron actions the next instance is created after the current one finishes. When the latest runs of the same hook have all failed (5 by default, filter action_scheduler_recurring_action_failure_threshold), Action Scheduler does not schedule another and fires action_scheduler_failed_to_schedule_next_instance. This is why the example hooks action_scheduler_ensure_recurring_actions: a hook that has been failing for days and is then fixed would otherwise never run again.

Idempotence. Jobs talk to external systems and can fail half way, and an operator can run an action again from the admin screen or WP-CLI. Write callbacks so that running them again is harmless: check the state of the order before sending the e-mail, use idempotency keys on external calls, and keep each job short.

Source: Action Scheduler: Usage

Action Scheduler registers the wp action-scheduler command group (4.1.0, WP-CLI 2.12.0 on the test site). wp action-scheduler printed this list:

Source: Action Scheduler: WP CLI

The built-in screen lists all actions with their status, hook, arguments, schedule, group, claim and log. It is at Tools > Scheduled Actions (tools.php?page=action-scheduler) and, when WooCommerce is active, at WooCommerce > Status > Scheduled Actions (the tab action-scheduler of the status page). From it an administrator can filter by status, search by hook, arguments, action ID or claim ID, sort, run a pending action immediately, cancel it, and read the log to find out why an action failed. The screen needs no code, so it is the first place to look when an order’s follow-up e-mail never arrived. When Action Scheduler is installed as a plugin rather than bundled, the screen is still there but the plugin adds no interface for scheduling.

Source: Action Scheduler: Scheduled Actions Administration Screen

WooCommerce bundles Action Scheduler, and so do many other plugins (subscriptions, bookings, memberships, mailers). Every one of them calls the same global functions and writes to the same tables, so exactly one copy of the code must be running. The library solves this with a version registry, and the mechanism explains most of the conflicts seen in the wild.

The main file of each copy (action-scheduler.php) does the following, as read from the bundled 4.1.0 source:

On the test site two experiments showed the outcome. First, the standalone plugin from WordPress.org at version 3.9.3 was installed next to WooCommerce 11.2.1. The older copy registered but did not win:

Then that plugin was replaced by the 4.2.0 release. Now the standalone plugin supplied the code that WooCommerce runs on:

ActionScheduler_SystemInformation::active_source() returned {"type":"plugin","name":"Action Scheduler"} and as_supports( 'uninstall_bootstrap' ) was true, which is a 4.2.0 feature: WooCommerce’s own jobs, and the jobs of every other plugin, ran on the newer copy for as long as it was active. Both plugins were deactivated and deleted afterwards. This is also the supported way to try a newer Action Scheduler than the one WooCommerce bundles.

Consequences for extension authors

Diagnosing a conflict. wp action-scheduler version --all lists every registered version and marks the active one, wp action-scheduler source --all lists the file each copy was registered from, and wp action-scheduler runner and data-store name the classes in use. Remember that a copy that never registered (loaded too late or modified) is invisible in these lists, so if a plugin’s jobs are missing and the list looks normal, check where the plugin loads its copy.

The WooCommerce 11.2.0 changelog names one such fatal error: when another plugin loads an Action Scheduler copy older than 3.3.0, the function as_has_scheduled_action() (added in 3.3.0) is not defined, and the batch processing controller of WooCommerce failed on calling it. Since 11.2.0 it falls back to as_next_scheduled_action() (#69415). The copies tested above (3.9.3 and 4.2.0, next to 4.1.0) are all newer than 3.3.0 and coexisted without a fatal error, so this case was not reproduced here. The lesson for an extension is the same: check function_exists() before calling an as_* function that is newer than the oldest copy that may win.

Source: WooCommerce changelog (11.2.0, #69415)

Source: Action Scheduler: Usage (Loading Action Scheduler, Load Order, Usage in Themes)

Source: Action Scheduler: FAQ (Is it safe to release Action Scheduler in my plugin?)

Deactivating a plugin does not touch its scheduled actions. They stay pending, and when their time comes the runner finds no callback and marks them failed (see above). Cancel the pending actions of the plugin when it is uninstalled:

This variant was not run (the example plugin does not bundle the library). It uses the group form of as_unschedule_all_actions() instead of the documentation’s per-hook call, for the reason found in the cancel section. Cancel only your own group: the tables belong to the site, and another plugin may still use them.

Source: Action Scheduler: Usage (Usage in uninstall.php)

Source: WordPress Plugin Handbook: Uninstall methods