Many WordPress plugins need to do work in the background. Sending a thousand emails after a product launch. Syncing orders to an accounting system. Regenerating thumbnails for a large media library. Processing a CSV import row by row. Doing that work during a page request makes the page slow or makes it time out. Doing it with plain WP-Cron works for small tasks but becomes fragile at scale, with no visibility into what ran, what failed and what’s still waiting. Action Scheduler handles that kind of work far better than WP-Cron alone.
Action Scheduler is a library built to solve exactly this. It’s a job queue for WordPress, originally developed for WooCommerce Subscriptions and now bundled with WooCommerce itself, which means it’s already running on millions of sites. It stores scheduled actions in dedicated database tables, processes them in batches, logs every run, retries can be built around it and it provides an admin screen showing everything that’s queued, running, completed or failed. If you build plugins that do any meaningful background work, Action Scheduler is worth knowing well.
Why not just WP-Cron?
WP-Cron is WordPress’s built-in scheduler. You schedule an event with wp_schedule_event or wp_schedule_single_event, and WordPress runs it on a later page load or when a real cron job calls wp-cron.php.
It’s fine for a handful of recurring tasks, such as a daily cleanup. Its limitations show up quickly with heavier workloads:
- Storage. All scheduled events live in a single option, the cron option. Thousands of events make that option huge, and it’s loaded on many requests.
- No visibility. There’s no built-in log of what ran, when, how long it took or whether it failed.
- No batching. Events run one after another until time runs out, with little control.
- Concurrency issues. Multiple requests can trigger cron at once, occasionally running jobs twice.
- Failures are silent. If an event throws an error, it’s simply gone.
Action Scheduler addresses each of these.
How Action Scheduler works
Action Scheduler stores each scheduled action as a row in its own tables, with the hook name, arguments, scheduled date, status and group. A queue runner processes due actions in batches, by default triggered via WP-Cron every minute and also through async requests, so work continues even on sites with little traffic.
Each action is simply a WordPress hook. When an action runs, Action Scheduler calls do_action with the hook name and arguments, and your callback does the work. If the callback throws an exception, the action is marked as failed, and the error is logged.
Statuses include pending, in-progress, complete, failed and canceled. You can see and manage all of them under Tools, Scheduled Actions, or under WooCommerce, Status, Scheduled Actions on WooCommerce sites.
Including Action Scheduler in your plugin
If your plugin requires WooCommerce, Action Scheduler is already available. For standalone plugins, include it with Composer:
Then load it early in your main plugin file:
The library is designed so that multiple plugins can bundle it safely. When several copies are present, the newest version is loaded and used by all of them.
Scheduling actions
The API is a set of simple functions.
Run something as soon as possible, in the background:
Run something once at a specific time:
Run something on a recurring interval:
Or with a cron expression:
The last argument is a group, which makes it easy to filter your plugin’s actions in the admin screen and to cancel them all on deactivation.
Then attach the callback:
Arguments are passed to the callback in order. Keep them small and simple, such as IDs, rather than whole objects, and fetch fresh data inside the callback.
Breaking big jobs into batches
The most important pattern with Action Scheduler is splitting large work into many small actions. Instead of one action that processes 50,000 products and inevitably times out, schedule actions that each process a batch of, say, 100 products, then schedule the next batch.
Each batch is quick, failures are isolated to one batch and you can see progress in the admin screen. For very large tables, paging by the last processed ID rather than by offset is more efficient.
Avoiding duplicates
Plugins often schedule the same action repeatedly by accident, for example on every page load. Before scheduling, check whether a matching action is already pending:
Newer versions also support a unique flag when scheduling, which prevents duplicates of the same hook in the queue.
Handling failures
When a callback throws an exception, Action Scheduler marks the action as failed and records the message. It doesn’t retry automatically. For tasks like API calls that may fail temporarily, build retries yourself: catch the exception, schedule the same action again with a delay and an attempt counter, and give up after a few attempts.
The final throw marks the action as failed after the last attempt, so it shows up in the failed list for investigation.
Running the queue reliably
On low-traffic sites, WP-Cron may not trigger often enough, delaying background work. Two improvements:
- Disable WP-Cron’s page-load trigger and run it from a real server cron every minute.
- Run Action Scheduler directly with WP-CLI, which is ideal for large backlogs:
WP-CLI runs aren’t constrained by web server timeouts, which makes them suitable for heavy processing.
Cleaning up
Action Scheduler automatically deletes completed and canceled actions after a retention period, 30 days by default, which can be adjusted with a filter. Failed actions are kept for investigation. On sites with very high volumes, reduce the retention period so the tables stay small.
When your plugin is deactivated, unschedule its recurring actions:
Monitoring in production
Make checking the Scheduled Actions screen part of routine maintenance. A growing number of pending actions that never complete usually means the queue runner isn’t running or a callback is very slow. A cluster of failed actions shows a broken integration. Both are much easier to spot with Action Scheduler than with plain WP-Cron, which is one of its biggest practical advantages.
A real-world example: syncing orders to an accounting system
A client’s store sent every completed order to an accounting system through an API. The original plugin did this during the order status change, inside the admin request. When the accounting API was slow, changing an order status took ten seconds. When the API was down, the status change failed altogether, or worse, succeeded in WooCommerce while the sync silently failed.
We rewrote the integration around Action Scheduler. When an order was completed, the plugin enqueued an async action with just the order ID. The action’s callback fetched the order, pushed it to the accounting API and stored the external reference on the order. Temporary failures were retried with an increasing delay up to five times. Permanent failures were marked as failed and appeared in the Scheduled Actions screen, filtered by the plugin’s group, where the bookkeeper could see them and ask for a manual fix.
Order status changes became instant again, because the slow work no longer happened in the request. The accounting system received every order eventually, even when it had outages. And for the first time, the team could actually see which orders hadn’t synced and why. That visibility alone justified the change.
Designing good actions
A few principles make Action Scheduler jobs robust:
- Make actions idempotent. If an action runs twice, the result should be the same as running it once. Check whether the work has already been done before doing it again, for example by storing a “synced” flag.
- Keep each action short. Aim for actions that finish in a few seconds. Long-running actions risk timeouts and block other work in the batch.
- Pass identifiers, not data. Load the latest data inside the callback, so actions don’t act on stale information.
- Use groups consistently. Groups make monitoring, filtering and cleanup straightforward.
- Log meaningfully. Action Scheduler records basic logs automatically, but adding your own log notes or storing results on the related object helps when diagnosing problems later.
When Action Scheduler isn’t the right tool
For a single daily task with no need for visibility, plain WP-Cron is simpler. For very high-throughput processing, such as millions of jobs per day, a dedicated queue system outside WordPress may be more appropriate. Action Scheduler sits in the large middle ground where most WordPress plugins live, and it handles that ground very well.
Frequently asked questions
Does Action Scheduler replace WP-Cron?
It builds on it. By default, WP-Cron triggers the queue runner. You can also run the queue with WP-CLI or a server cron.
Is it safe to bundle in a plugin that may also run alongside WooCommerce?
Yes. The library handles multiple copies and uses the newest version available.
Can I see the logs for a specific action?
Yes. The Scheduled Actions screen shows each action’s log, including when it was created, started, completed or failed, and any error messages.
How many actions can it handle?
Large WooCommerce stores process hundreds of thousands of actions. Keep callbacks efficient and clean up old actions to maintain performance.




