Subscription Renewals¶

Barberklingen\BasePlugin\Modules\SubscriptionRenewals\SubscriptionRenewalManager

Replaces WooCommerce Subscriptions' default renewal mechanism with a custom flow that uses a dedicated intermediate status (wc-stalled) instead of the standard on-hold. This allows distinguishing between a customer-initiated hold and a failed payment hold.

Activating the module¶

The module is wrapped in CustomSubscriptionRenewalsLoader, which checks a feature flag before booting:

CustomSubscriptionRenewalsLoader::get_instance();

What it does¶

On plugins_loaded (priority 50) the manager unhooks the WooCommerce Subscriptions core renewal handlers and replaces them:

woocommerce_scheduled_subscription_payment
  └─ (removed) WC_Subscriptions_Manager::prepare_renewal
  └─ (added)   SubscriptionRenewalManager::prepare_renewal  (priority 1)

woocommerce_order_action_wcs_create_pending_renewal
  └─ (removed) WCS_Admin_Meta_Boxes::create_pending_renewal_action_request
  └─ (added)   SubscriptionRenewalManager::create_pending_renewal_action_request

Renewal flow¶

sequenceDiagram
    participant AS as Action Scheduler
    participant RM as SubscriptionRenewalManager
    participant SUB as WC_Subscription

    AS->>RM: woocommerce_scheduled_subscription_payment
    RM->>SUB: update_status('wc-stalled', note)
    RM->>SUB: wcs_create_renewal_order()
    RM->>SUB: payment_complete / update_status based on result

The subscription is placed into wc-stalled before the renewal order is created. If anything fails mid-flight, the subscription stays in wc-stalled rather than silently remaining active.

Custom status: wc-stalled¶

SubscriptionRenewalStatus::STATUS holds the status slug. The status signals that a renewal payment is in progress and the subscription is temporarily paused.

Retry rules¶

The module adjusts WooCommerce Subscriptions' default auto-retry rules via the wcs_default_retry_rules filter (priority 50) to keep the subscription in wc-stalled during retries rather than moving it back to on-hold.

Cancellation handling¶

When an order is cancelled, the module checks whether the related subscription should be put on hold via woocommerce_order_status_cancelled (priority 50).

WP-CLI¶

The module ships CLI commands under Modules\SubscriptionRenewals\CLI. Use wp help to inspect available commands after activation.