wcs-renewal-scheduler

WooCommerce Subscriptions: renewal scheduler

Use this when code touches renewal timing, scheduled payments, renewal order creation, or retry behavior. The key rule: change subscription dates/status through WC_Subscription methods, not by writing schedule meta or Action Scheduler rows directly.

Misconception this skill corrects

"To reschedule a subscription, update _schedule_next_payment or call as_schedule_single_action()."

That bypasses WCS validation and the scheduler's cleanup/reschedule behavior. WCS_Scheduler listens to woocommerce_subscription_date_updated, woocommerce_subscription_date_deleted, and woocommerce_subscription_status_updated. Those fire when you use WC_Subscription::update_dates(), delete_date(), or update_status().

When to use this skill

Trigger when ANY of the following is true:

• The user wants to change next_payment, trial_end, end, payment_retry, or renewal timing.
• Code contains _schedule_next_payment, _schedule_payment_retry, as_schedule_single_action, woocommerce_scheduled_subscription_payment, WCS_Action_Scheduler, wcs_create_renewal_order, or WCS_Retry_Manager.
• A gateway or integration needs to charge recurring payments, create renewal orders, react after a renewal succeeded, or handle failed renewal retries.

Renewal flow

For a normal WCS-managed automatic renewal:

1. A future Action Scheduler action exists in group wc_subscription_scheduled_event.
2. The action hook is woocommerce_scheduled_subscription_payment with args array( 'subscription_id' => $id ).
3. WC_Subscriptions_Manager::prepare_renewal() runs at priority 1. It puts the subscription on hold and creates a renewal order with wcs_create_renewal_order().
4. wcs_renewal_order_created fires after the renewal relation is stored.
5. WC_Subscriptions_Payment_Gateways::gateway_scheduled_subscription_payment() runs at priority 10.
6. For non-manual gateways that do not manage their own schedule, WCS triggers woocommerce_scheduled_subscription_payment_{gateway_id} with $amount, $renewal_order.
7. After payment result, use woocommerce_subscription_renewal_payment_complete or woocommerce_subscription_renewal_payment_failed for business side effects.