Complete Guide to Scheduled Events with Subscriptions

Scheduled events are actions that happen at particular times. WP-Cron and Action Scheduler are systems that trigger and run events. Both of these systems run in the background of a WordPress website.

Action Scheduler excels at batch processing, storing the actions, error logging, and providing an interface for interacting with the scheduled events system.

Note: We are unable to provide support for customizations under our Support Policy. If you need to customize a snippet or extend its functionality, we recommend working with a Woo Agency Partner or finding a WooCommerce developer on Codeable.

WP-Cron is WordPress’s version of cron; a system to run time-based actions in unix systems. WP-Cron makes it so that third-parties don’t have to concern themselves with specific operating system implementations of cron.

By itself, WP-Cron limited by the fact that it’s triggered by page loads that triggers any events that are scheduled for that time, or that are waiting from before that time. This means that, on a site with low traffic, events might not run at their scheduled time. To overcome this issue, low traffic sites may rely on a service that pings the site periodically (triggering a page load), such as the Jetpack – Downtime / Uptime Monitoring service.

All scheduled jobs with WP-Cron are stored in a single row of the wp_options table. This means that on sites with tens of thousands of scheduled actions the system, all data is being stored in a single column of the database. This creates a number of issues including:

• It’s not possible to query scheduled events via MySQL. It must be done in PHP, slowing down querying scheduled events.
• Modifying a single scheduled event requires saving or updating all events, slowing down database operations.

Action Scheduler was developed to overcome the scaling issues posed by WP-Cron. Action Scheduler creates queues of events that are processed in an orderly manner.

To process this queue, Action Scheduler uses two methods.

• It attempts to process the queue every minute via its own WP-Cron event.
• Once per minute, it also check at the end of each WP Admin request whether there are pending actions.

When either of these methods run, pending events which are due are processed in the background. Action Scheduler can run batches and concurrent queues. On sites with large numbers of actions, this is very helpful.

Action Scheduler also offers an interface to interact with scheduled events and a way to trace event histories.

When dealing with events no longer handled by the WP-Cron queue runner, a question to ask is whether WP-Cron has stopped or only Action Scheduler. In order to determine if one or the other stopped, their last working dates need to be found, and checked.

To check WP-Cron:

1. Install a plugin that provides a way to view the WP-Cron system, like WP Crontrol.
2. Once installed and activated, go to WP Admin > Tools > Cron events.
3. In the Next Run column, check the date for the top entry.

To check Action Scheduler:

1. Go to Tools > Scheduled Actions.
2. Choose the Complete sub-tab at the top of the screen.
3. Click the Scheduled Date column’s heading to sort by most recent.
4. Check the Scheduled Date column for the date of the last completed scheduled action.

To determine which system has stopped:

1. Compare the WP-Cron date with the Action Scheduler date.
2. If the WP-Cron date is in the past (it indicates (now)), is before or coincides with the Action Scheduler date, then WP-Cron has been disabled.
3. f the WP-Cron date is recent, such as in the last few minutes, and after the Action Scheduler date, then Action Scheduler is blocked.

It is possible that there was a job in the WP-Cron queue that could never complete, causing WP-Cron to go through an endless loop and effectively be blocked from processing more actions.

Here is a sequence of possible events that would block the queue:

1. The offending job gets to the top of the queue.
2. WP-Cron runs the offending job.
3. The job causes a fatal error.
4. WP-Cron does not remove that job from the queue, because the job was terminated before it had finished.
5. Return to step 2 and repeat.

To determine the cause of this error, check the Fatal Errors log in WooCommerce > Status > Logs. Look for a fatal error coinciding with the time WP-Cron was last working.

Once you identified the source of the problem, that source needs to be fixed for WP-Cron to continue working. In the case of a plugin that produced a fatal error, update the plugin to see if a fix was implemented.

When reinstating WP-Cron, you do not need to clear out or regenerate Subscriptions-related events. Action Scheduler has those events safely stored in a queue waiting to be run. This means that all the actions, such as renewal payments, that might not have processed since WP-Cron stopped working are still waiting to process.

Keep in mind that actions will still have been processing via WP Admin request so there might be a back log to get through, or maybe no back log at all.

Subscriptions requires a working WP-Cron because Action Scheduler, the system used to process scheduled events, relies on WP-Cron to work at maximum efficiency. Without the initial event triggered by WP-Cron, the events queue in Action Scheduler can only be processed via WP Admin async requests.

Because the base WP-Cron system is triggered by a page load, the queue on sites with low traffic may process events well after they were due. For a more reliable processing of the WP-Cron queue, take a look at our guide on alternative methods to triggering the WP-Cron.

woocommerce_scheduled_subscription_payment

Scheduled: When a subscription is purchased.

Rescheduled: When a subscriptions status is changed to active. When the next payment date is updated if the subscription has an active status.

Unscheduled: When a subscription’s status is changed to pending-cancel, cancelled, switched, expired or trash.

Run: At the next payment date.

Date type: next_payment.

Arguments: Subscription ID.

woocommerce_scheduled_subscription_trial_end

Scheduled: When a subscription item with a free trial is purchased.

Rescheduled: When a subscriptions status is changed to active. When the trial end date is updated if the subscription has an active status.

Unscheduled: When a subscription’s status is changed to pending-cancel, cancelled, switched, expired or trash.

Run: At the end of a free trial.

Date type: trial_end.

Arguments: Subscription ID.

woocommerce_scheduled_subscription_payment_retry

Scheduled: When the payment_retry date is updated, after a renewal payment has failed.

Rescheduled: When a subscription’s status is changed to active. When the next payment date is updated.

Unscheduled: When a subscription status is changed to pending-cancel, cancelled, switched, expired or trash. When the status changes if the new status is not the same as the retry’s expected status.

Run: According to retry rules; default rules have the first retry 12 hours after failed renewal attempt.

Date type: payment_retry.

Arguments: Last renewal order ID.

woocommerce_scheduled_subscription_expiration

Scheduled: When a subscription is purchased. It will be 0 unless the subscription has an expiration date, i.e. a length.

Rescheduled: When a subscription status is changed to active. When the next payment date is updated if the subscription has an active status.

Unscheduled: When a subscription’s status is changed to pending-cancel, cancelled, switched, expired or trash.

Run: At the end of the subscription length.

Date type: end.

Arguments: Subscription ID.

woocommerce_scheduled_subscription_end_of_prepaid_term

Scheduled: When a subscription is cancelled and its status is changed to pending-cancel.

Rescheduled: When a subscription’s status is changed to pending-cancel.

Unscheduled: When a subscription’s status is changed to active, cancelled, switched, expired or trash.

Run: At the end of the subscription’s prepaid term, when it moves to cancelled status.

Date type: end.

Arguments: Subscription ID.

woocommerce_subscriptions_privacy_anonymize_ended_subscriptions

Scheduled: Hooked onto woocommerce_cleanup_personal_data.

Run: Daily.

Arguments: None.

Notes: This action will not do anything if the setting to cleanup ended subscriptions is not set.

woocommerce_subscriptions_privacy_anonymize_subscription_orders

Scheduled: For each ended subscription which needs to be anonymized.

Run: Immediately when subscription is anonymized.

Arguments: Subscription ID.

woocommerce_subscriptions_privacy_anonymize_subscription_order

Scheduled: For each ended subscription which needs to be anonymized.

Run: Immediately when subscription is anonymized.

Arguments: Subscription ID. 

wcs_report_update_cache 

Scheduled: After a cache-invalidating event and before PHP shutdown.

Run: On most sites: 10 minutes after a cache-invalidating event, once every 5 minutes apart for each report type. On large sites: once a day at 4 am site time, 15 minutes apart for each report type.

Arguments:  The subscription-related report which needs updating.

If an error occurs when processing a scheduled subscription payment, a notice will appear in the admin dashboard to alert store managers of this error. The Subscriptions Scheduled Action Errors guide explains why a notice is displayed, the likely causes of the issue, steps to diagnose the cause, and how to fix the problem or get help.

Action Scheduler has WP-CLI commands that can be used for processing actions. This can be particularly useful for large sites with long-running tasks, large queues, or many demands on WP-Cron.

More information about using these commands can be found on the Action Scheduler site in the section about WP-CLI.