woocommerce-subscriptions
Add subscription products to WooCommerce with automatic recurring billing, renewal notifications, and subscriber self-service management
How do I install this agent skill?
npx skills add https://github.com/finsilabs/awesome-ecommerce-skills --skill woocommerce-subscriptionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a comprehensive guide for developers to programmatically manage WooCommerce subscriptions, including product creation, payment lifecycle hooks, and plan switching logic. No security risks or malicious patterns were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
WooCommerce Subscriptions
Overview
WooCommerce Subscriptions (the official premium plugin) adds subscription product types — simple subscriptions and variable subscriptions — with configurable billing periods (daily, weekly, monthly, yearly), free trials, sign-up fees, and prorated upgrades/downgrades. It integrates with Stripe, PayPal Reference Transactions, and other gateways that support automated recurring billing. Custom logic hooks into the subscription lifecycle via a rich set of WordPress actions and filters.
When to Use This Skill
- When selling products or services on a recurring billing schedule (SaaS, memberships, box subscriptions)
- When implementing subscription upgrades, downgrades, or plan switching
- When building custom renewal logic or adding business rules around failed payment retry
- When integrating subscription status with access control (e.g., membership site content gates)
- When extending subscription emails or admin reporting with custom data
- When creating subscription add-ons or per-unit quantity scaling
Core Instructions
-
Create a subscription product programmatically
<?php // Create a simple subscription product via code (e.g., in a migration script) $product = new WC_Product_Subscription(); $product->set_name('Monthly Pro Plan'); $product->set_status('publish'); $product->set_regular_price('29.99'); // Save first so the product gets an ID $product->save(); // Subscription-specific meta (product must be saved before setting post meta) update_post_meta($product->get_id(), '_subscription_price', '29.99'); update_post_meta($product->get_id(), '_subscription_period', 'month'); update_post_meta($product->get_id(), '_subscription_period_interval', '1'); update_post_meta($product->get_id(), '_subscription_length', '0'); // 0 = forever update_post_meta($product->get_id(), '_subscription_trial_length', '14'); update_post_meta($product->get_id(), '_subscription_trial_period', 'day'); update_post_meta($product->get_id(), '_subscription_sign_up_fee', '0'); -
Hook into subscription lifecycle events
WooCommerce Subscriptions fires specific actions at each lifecycle stage:
<?php // When a new subscription is created (after successful first payment) add_action('woocommerce_subscription_status_active', function ($subscription) { $user_id = $subscription->get_user_id(); $plan = $subscription->get_items(); // Array of WC_Order_Item_Product // Grant access — e.g., set user role or update capabilities $user = new WP_User($user_id); $user->add_role('subscriber_member'); // Track in analytics error_log("Subscription {$subscription->get_id()} activated for user {$user_id}"); }); // When a renewal payment succeeds add_action('woocommerce_subscription_renewal_payment_complete', function ($subscription, $last_order) { $user_id = $subscription->get_user_id(); // Extend access, send renewal receipt, update CRM do_action('my_plugin_renewal_processed', $user_id, $subscription); }, 10, 2); // When a renewal payment fails add_action('woocommerce_subscription_payment_failed', function ($subscription, $last_order) { $user_id = $subscription->get_user_id(); $retry_count = $subscription->get_failed_payment_count(); // Notify user and optionally pause access if ($retry_count >= 2) { $user = new WP_User($user_id); $user->remove_role('subscriber_member'); // Send dunning email $subscription->update_status('on-hold'); } }, 10, 2); // When subscription is cancelled add_action('woocommerce_subscription_status_cancelled', function ($subscription) { $user_id = $subscription->get_user_id(); $user = new WP_User($user_id); $user->remove_role('subscriber_member'); }); -
Query subscriptions programmatically
<?php // Get all active subscriptions for a user function get_user_active_subscriptions(int $user_id): array { return wcs_get_users_subscriptions($user_id, ['active']); } // Check if a user has an active subscription to a specific product function user_has_active_subscription_to_product(int $user_id, int $product_id): bool { $subscriptions = wcs_get_subscriptions_for_product($product_id, 'any', ['customer_id' => $user_id]); foreach ($subscriptions as $subscription) { if ($subscription->has_status('active')) { return true; } } return false; } // Get subscription by ID function get_subscription_details(int $subscription_id): ?WC_Subscription { $subscription = wcs_get_subscription($subscription_id); if (!$subscription) return null; return $subscription; } // Usage $subscription = get_subscription_details(1234); if ($subscription) { echo $subscription->get_status(); // 'active', 'on-hold', 'cancelled', etc. echo $subscription->get_next_payment_date(); // ISO 8601 date echo $subscription->get_total(); // Current billing amount } -
Handle plan upgrades and downgrades
<?php // Add proration logic for plan switches add_filter('woocommerce_subscriptions_switch_proration', function ($proration_amount, $subscription, $new_order, $product, $switch_cart_item) { // Custom proration: charge/credit based on days remaining in billing period $next_payment = strtotime($subscription->get_next_payment_date()); $last_payment = $subscription->get_date('last_payment'); $billing_period_days = ($next_payment - strtotime($last_payment)) / DAY_IN_SECONDS; $days_remaining = ($next_payment - time()) / DAY_IN_SECONDS; $old_daily_rate = (float)$subscription->get_total() / $billing_period_days; $new_product_price = (float)$switch_cart_item['data']->get_price(); $new_daily_rate = $new_product_price / $billing_period_days; // Credit remaining days at old rate, charge at new rate $proration_amount = ($new_daily_rate - $old_daily_rate) * $days_remaining; return round($proration_amount, 2); }, 10, 5); // Trigger a plan switch programmatically function switch_subscription_plan(int $subscription_id, int $new_product_id): bool { $subscription = wcs_get_subscription($subscription_id); if (!$subscription) return false; // Remove existing item and add new product foreach ($subscription->get_items() as $item_id => $item) { $subscription->remove_item($item_id); } $item = new WC_Order_Item_Product(); $item->set_product(wc_get_product($new_product_id)); $item->set_quantity(1); $subscription->add_item($item); // Recalculate totals $subscription->calculate_totals(); $subscription->save(); return true; } -
Retry failed payments and synchronize billing dates
<?php // Trigger an immediate payment retry (e.g., from an admin action) function retry_failed_subscription_payment(int $subscription_id): bool { $subscription = wcs_get_subscription($subscription_id); if (!$subscription || !$subscription->has_status('on-hold')) { return false; } // Create a renewal order and attempt payment $renewal_order = wcs_create_renewal_order($subscription); if (is_wp_error($renewal_order)) { return false; } // Process payment using the subscription's payment method $payment_gateway = wc_get_payment_gateway_by_order($subscription); if ($payment_gateway && method_exists($payment_gateway, 'scheduled_subscription_payment')) { $payment_gateway->scheduled_subscription_payment( $renewal_order->get_total(), $renewal_order ); } return true; } // Synchronize all active subscriptions to renew on the 1st of the month add_filter('woocommerce_subscriptions_synced_next_payment_date', function ($next_payment_date, $product, $from_timestamp, $trial_end_timestamp) { if ($product->get_meta('_subscription_period') === 'month') { $next_month = date('Y-m-01', strtotime('+1 month')); return strtotime($next_month); } return $next_payment_date; }, 10, 4);
Examples
Suspension and reinstatement flow
<?php
// Admin-triggered suspension with reason logging
function suspend_subscription_with_reason(int $subscription_id, string $reason): void {
$subscription = wcs_get_subscription($subscription_id);
if (!$subscription) return;
// Store suspension reason as meta before status change
$subscription->update_meta_data('_suspension_reason', $reason);
$subscription->update_meta_data('_suspension_date', current_time('mysql'));
$subscription->save();
// Change status to on-hold (fires woocommerce_subscription_status_on-hold action)
$subscription->update_status('on-hold', sprintf('Suspended: %s', $reason));
}
// Reinstate and reset payment date
function reinstate_subscription(int $subscription_id): void {
$subscription = wcs_get_subscription($subscription_id);
if (!$subscription || !$subscription->has_status('on-hold')) return;
// Reset next payment date to avoid immediately triggering a renewal
$subscription->set_date('next_payment', strtotime('+1 month'));
// Activate subscription
$subscription->update_status('active', 'Reinstated by admin');
$subscription->save();
}
Custom subscription email
<?php
// Add a custom "Renewal Reminder" email 7 days before renewal
add_filter('woocommerce_email_classes', function ($email_classes) {
require_once plugin_dir_path(__FILE__) . 'class-renewal-reminder-email.php';
$email_classes['My_Renewal_Reminder_Email'] = new My_Renewal_Reminder_Email();
return $email_classes;
});
// Schedule the emails via WooCommerce action scheduler
add_action('woocommerce_scheduled_subscription_payment', function ($subscription_id) {
$subscription = wcs_get_subscription($subscription_id);
if (!$subscription) return;
// Schedule reminder 7 days before next payment
$next_payment = strtotime($subscription->get_next_payment_date()) - (7 * DAY_IN_SECONDS);
if ($next_payment > time()) {
as_schedule_single_action(
$next_payment,
'my_plugin_send_renewal_reminder',
[['subscription_id' => $subscription_id]]
);
}
}, 10);
Best Practices
- Use Action Scheduler (bundled with WooCommerce) for all async subscription tasks — never rely on WP cron for payment-critical operations
- Always use
wcs_get_subscription()with null-checks — subscriptions may be deleted or missing in edge cases (manual deletions, import failures) - Test payment gateway token handling — subscription renewals require a stored payment token; test that the gateway correctly charges the original card on file during renewal
- Handle failed payment dunning explicitly — the default retry schedule is 1, 4, and 7 days after failure; customize via
wcs_retry_rulesfilter to match your business policy - Log all subscription status changes — store status change history in order notes or a custom table for auditing and customer support
- Respect proration on plan switches — don't force customers to pay double for the same period; use built-in proration or implement custom logic
- Test upgrade/downgrade edge cases — especially when a trial is active or when the billing period changes (monthly to annual)
- Use
wcs_user_has_subscription()for access control — it's more reliable than checking user roles alone
Common Pitfalls
| Problem | Solution |
|---|---|
| Renewal payments not processing | Check that the payment gateway has supports[] = subscription in its capabilities; gateways must explicitly declare subscription support |
| Subscription status stays "pending" after successful payment | The woocommerce_payment_complete action must fire — verify the payment gateway calls $order->payment_complete() on success |
| Proration results in negative charge | Implement minimum floor of 0.00 in the proration filter return value; negative amounts cause gateway errors on most processors |
wcs_get_subscriptions_for_product returns empty | Pass the product's parent ID for variations — WCS stores the parent product ID, not the variation ID, on subscription items |
| Trial ends but renewal isn't charged | Ensure _subscription_trial_length meta is set to a number > 0 AND the payment gateway token is stored correctly from the initial order |
| Cancellation emails sent on admin status changes | Add remove_action for woocommerce_subscription_status_cancelled before programmatic cancellations and re-add after if you need to suppress emails |
Related Skills
- @woocommerce-plugin-development
- @woocommerce-rest-api
- @subscription-billing
- @stripe-integration
- @woocommerce-blocks
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/finsilabs/awesome-ecommerce-skills/woocommerce-subscriptions">View woocommerce-subscriptions on skillZs</a>