wcs-renewal-scheduler

To change the next payment date safely, use the `WC_Subscription::update_dates()` method rather than editing `_schedule_next_payment` meta directly. This allows WooCommerce Subscriptions to validate date ordering and automatically reschedule canonical Action Scheduler events.

Duplicate or missing renewal orders usually happen when developers bypass the WCS scheduler lifecycle and directly manipulate Action Scheduler rows. You must use `wcs_create_renewal_order()` and the `wcs_renewal_order_created` hook to ensure correct renewal flow control and order generation.

You trigger gateway recurring charges by using the gateway-specific scheduled action hook pattern `woocommerce_scheduled_subscription_payment_{gateway_id}`. This ensures WCS manages the renewal process correctly instead of relying on manual scheduling shortcuts.

Use the `woocommerce_subscription_renewal_payment_complete` and `woocommerce_subscription_renewal_payment_failed` hooks to distinguish renewal payment outcomes. These hooks support retry-related observability without violating the retry system invariants.

Directly modifying Action Scheduler rows or subscription meta is strongly discouraged. Forcing or rescheduling renewals safely requires using the official `WC_Subscription` date and status methods so the WCS scheduler lifecycle can validate and process the events correctly.

The “any subscription payment complete” hook fires for all payments, while the “renewal payment complete” hook fires specifically for renewal orders. Using the correct renewal-specific hook ensures accurate business side-effects and proper retry behavior tracking.