Imported from nvdigitalsolutions/mcp-ai-wpoos (addons/pro/includes/bundled-skills/wcs-subscription-hooks/SKILL.md). Install upstream with npx skills add nvdigitalsolutions/mcp-ai-wpoos --skill wcs-subscription-hooks. Copyright stays with the author (MIT).

WooCommerce Subscriptions: hook map

Use this when building or reviewing an integration that needs to react to WooCommerce Subscriptions events. This is not an exhaustive dump of the 800+ hook calls in the plugin. It is a decision map for the hooks that are usually correct and the older/noisy hooks that AI agents tend to choose incorrectly.

Misconception this skill corrects

"Subscriptions are just orders, so hook woocommerce_order_status_changed or update _schedule_next_payment meta directly."

Subscriptions are WC_Subscription objects with their own lifecycle hooks, status transition hooks, date hooks, relation store, renewal order hooks, and scheduler bridge. Prefer WCS hooks and CRUD methods unless the task explicitly needs ordinary WC orders.

When to use this skill

Trigger when ANY of the following is true:

• The user asks for WooCommerce Subscriptions actions/filters, lifecycle hooks, renewal hooks, status hooks, payment retry hooks, switching hooks, or gifting hooks.
• You see WC_Subscription, wcs_get_subscription(), wcs_create_subscription(), wcs_create_renewal_order(), woocommerce_scheduled_subscription_payment, wcs_renewal_order_created, payment_retry, wcsg_, or subscription_switch.
• You need to decide whether to hook at subscription creation, renewal order creation, gateway payment attempt, successful payment, failed payment, status change, or scheduled action time.

Workflow

1. Identify the lifecycle point first: creation, status, date schedule, renewal order, gateway charge, retry, switch/gift, or UI/API.
2. Prefer hooks that pass WC_Subscription or WC_Order objects over legacy hooks that pass subscription keys.
3. For dynamic hooks, expand the real hook name from the runtime value: status, date type, payment method ID, or order relation type.
4. Before implementing, inspect the exact source line in the installed plugin with:

rg -n "hook_name|function_name" wp-content/plugins/woocommerce-subscriptions/includes wp-content/plugins/woocommerce-subscriptions/src

Storage facts agents must not guess

Subscriptions registers shop_subscription as a WooCommerce order type. In CPT mode it appears as a post type; in HPOS it is an order type. Subscription product type slugs are subscription, variable-subscription, and subscription_variation.

Subscription prop meta keys include _billing_period, _billing_interval, _suspension_count, _cancelled_email_sent, _requires_manual_renewal, _trial_period, _last_order_date_created, _schedule_start, _schedule_trial_end, _schedule_next_payment, _schedule_cancelled, _schedule_end, _schedule_payment_retry, and _subscription_switch_data.

Related order meta keys are _subscription_renewal, _subscription_switch, and _subscription_resubscribe.

Switch cart items store subscription_switch cart item data. Gift cart items store wcsg_gift_recipients_email; gifted subscriptions use _recipient_user_email_address and _recipient_user, with parent order item meta wcsg_recipient.

Core hook map

Renewal and scheduled payment hooks

Scheduler hooks

WCS uses Action Scheduler with group wc_subscription_scheduled_event, but the public integration point is the subscription date/status API. The scheduler listens to woocommerce_subscription_date_updated, woocommerce_subscription_date_deleted, and woocommerce_subscription_status_updated.

Payment retry hooks

Switching, early renewal, gifting

Gateway hooks

Customer action guardrails

For custom customer account actions, do not expose WCS admin REST writes directly. Load the subscription object, verify the current user owns it, then use WCS capabilities and object methods.

Status actions:

• Check $subscription->get_user_id() === get_current_user_id() unless this is trusted admin/server code.
• Check $subscription->can_be_updated_to( $target_status ) before calling $subscription->update_status( $target_status, $note, true ).
• Prefer domain statuses: cancel to pending-cancel when the prepaid term should continue; cancel to cancelled only when immediate cancellation is intended and allowed.
• Let WCS status hooks run; do not update post_status or order status meta directly.

Payment-method actions:

• Verify the selected payment token belongs to the same WP user and gateway customer.
• Do not update only payment meta/source IDs. Use WC_Subscriptions_Change_Payment_Gateway::update_payment_method() or the gateway's change-payment flow so hooks and remote gateway side effects run.
• Preserve woocommerce_subscriptions_pre_update_payment_method and woocommerce_subscription_payment_method_updated; gateways use them for remote profile cleanup and migration.

Switch actions:

• Use WC_Subscriptions_Switcher::can_item_be_switched_by_user() for eligibility.
• Wrap the switch cart/checkout flow or reproduce _subscription_switch_data deliberately. Direct line-item replacement is not a subscription switch.

Common mistakes

// WRONG: catches many normal orders and misses WCS-specific semantics.
add_action( 'woocommerce_order_status_changed', 'my_sync' );

// RIGHT: subscription transition with object.
add_action( 'woocommerce_subscription_status_updated', function ( WC_Subscription $subscription, string $to, string $from ): void {
    my_sync_subscription_status( $subscription->get_id(), $from, $to );
}, 10, 3 );

// WRONG: changing the schedule by writing meta bypasses validation and can desync Action Scheduler.
update_post_meta( $subscription_id, '_schedule_next_payment', '2026-05-01 00:00:00' );

// RIGHT: CRUD date update; WCS validates and reschedules via date hooks.
$subscription = wcs_get_subscription( $subscription_id );
if ( $subscription ) {
    $subscription->update_dates( array( 'next_payment' => '2026-05-01 00:00:00' ), 'gmt' );
}

// WRONG: use the scheduled-payment hook for fulfillment.
add_action( 'woocommerce_scheduled_subscription_payment', 'ship_box' );

// RIGHT: fulfill only after renewal payment is complete.
add_action( 'woocommerce_subscription_renewal_payment_complete', function ( WC_Subscription $subscription, WC_Order $order ): void {
    ship_box_for_renewal( $subscription, $order );
}, 10, 2 );

What this skill does NOT cover

• Building a payment gateway from scratch.
• HPOS order CRUD beyond the WCS-specific hooks here. Use wc-hpos-compatibility for general order storage issues.
• Exhaustive hook cataloging. For full local discovery, run rg -n "do_action\\(|apply_filters\\(" wp-content/plugins/woocommerce-subscriptions.

Cross-references

• Run wcs-data-model-switching-gifting when exact Subscriptions meta names, product type slugs, switch payloads, switched item meta/types, or WCS Gifting recipient storage matters.
• Run wcs-renewal-scheduler for changes to next payment dates, renewal order creation, scheduled actions, or payment retry timing.
• Run wc-hpos-compatibility if the integration queries orders/subscriptions directly.