wcs-subscription-hooks

# 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:

```bash
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

| Need | Hook | Type | Args | Use |
|---|---|---|---|---|
| Detect a loaded subscription object | `wcs_get_subscription` | filter | `WC_Subscription|false $subscription` | Last-resort object substitution/validation. Do not return arbitrary types; WCS 8.1+ rejects non-`WC_Subscription` values. |
| Create subscription programmatically | `wcs_created_subscription` | filter | `WC_Subscription $subscription` | Modify the newly saved object before the post-create action. |
| Run after subscription creation | `wcs_create_subscription` | action | `WC_Subscription $subscription` | Attach metadata, external IDs, logs, or provisioning. |
| Change default new status | `woocommerce_default_subscription_status` | filter | `string $status` | Default is `pending`; return status without `wc-`. |
| Add/rename statuses | `wcs_subscription_statuses` | filter | `array $statuses` | Keys must use `wc-` prefix, e.g. `wc-paused`. |
| Allow status transition | `woocommerce_can_subscription_be_updated_to_{status}` | filter | `bool $can, WC_Subscription $subscription` | Permit a custom or normally blocked transition. |
| Before status update | `woocommerce_subscription_pre_update_status` | action | `$old_status, $new_status, WC_Subscription $subscription` | Validate/log before WCS mutates dates and saves. |
| Status reached | `woocommerce_subscription_status_{to}` | action | `WC_Subscription $subscription` | React to a specific target status, e.g. `woocommerce_subscription_status_active`. |
| Specific transition | `woocommerce_subscription_status_{from}_to_{to}` | action | `WC_Subscription $subscription` | Use for exact transitions such as `on-hold_to_active`. |
| Generic status update | `woocommerce_subscription_status_updated` | action | `WC_Subscription $subscription, string $to, string $from` | Best general hook for lifecycle integration. |
| WC-like status changed | `woocommerce_subscription_status_changed` | action | `int $subscription_id, string $from, string $to, WC_Subscription $subscription` | Useful when porting code shaped like `woocommerce_order_status_changed`. |
| Read a stored date | `woocommerce_subscription_get_{date_type}_date` | filter | `$date, WC_Subscription $subscription, string $timezone` | Display/read override; do not use to reschedule. |
| Calculate a future date | `woocommerce_subscription_calculated_{date_type}_date` | filter | `$date, WC_Subscription $subscription` | Change calculated `next_payment`, `trial_end`, `end`, or `end_of_prepaid_term`. |
| Date changed | `woocommerce_subscription_date_updated` | action | `WC_Subscription $subscription, string $date_type, string $datetime` | Scheduler listens here; good place for external sync. |
| Date deleted | `woocommerce_subscription_date_deleted` | action | `WC_Subscription $subscription, string $date_type` | Clean up external schedule/state. |
| Can date be changed | `woocommerce_subscription_can_date_be_updated` | filter | `bool $can, string $date_type, WC_Subscription $subscription` | Open/close date editing rules. |
| Query subscriptions | `woocommerce_get_subscriptions_query_args` | filter | `$query_args, $working_args` | Modify `wcs_get_subscriptions()` query before execution. |
| After query | `woocommerce_got_subscriptions` | filter | `$subscriptions, $working_args` | Post-filter subscription results. |
| Related orders | `woocommerce_subscription_related_orders` | filter | `$orders, WC_Subscription $subscription, $return_fields, $order_type` | Add/adjust parent, renewal, switch, resubscribe relations. |

## Renewal and scheduled payment hooks

| Need | Hook | Type | Args | Use |
|---|---|---|---|---|
| Scheduled renewal is due | `woocommerce_scheduled_subscription_payment` | action | `int $subscription_id` | Fired by Action Scheduler/admin action. WCS prepares renewal at priority 1 and gateway processing runs at priority 10. |
| Renewal order creation failed | `wcs_failed_to_create_renewal_order` | action | `WP_Error $error, WC_Subscription $subscription` | Alert/log/retry externally. |
| Renewal order created | `wcs_renewal_order_created` | filter | `WC_Order $renewal_order, WC_Subscription $subscription` | Add order meta, line item data, external IDs. Return a `WC_Order`. |
| Gateway charge hook | `woocommerce_scheduled_subscription_payment_{gateway_id}` | action | `float $amount, WC_Order $renewal_order` | Payment gateways implement recurring charge here, e.g. `_stripe` or `_paypal`. |
| Manual renewal order generated | `woocommerce_generated_manual_renewal_order` | action | `int $renewal_order_id, WC_Subscription $subscription` | Notify, adjust pending manual renewal order. |
| Renewal payment complete | `woocommerce_subscription_renewal_payment_complete` | action | `WC_Subscription $subscription, WC_Order $last_order` | Provision after a successful renewal, not before gateway payment. |
| Renewal payment failed | `woocommerce_subscription_renewal_payment_failed` | action | `WC_Subscription $subscription, WC_Order $related_order` | Handle failed renewal consequences. |
| Any subscription payment complete | `woocommerce_subscription_payment_complete` | action | `WC_Subscription $subscription` | Fires for parent or renewal payment completion. |
| Any subscription payment failed | `woocommerce_subscription_payment_failed` | action | `WC_Subscription $subscription, string $new_status` | React to failure and resulting status. |
| Paid failed renewal | `woocommerce_subscriptions_paid_for_failed_renewal_order` | action | `WC_Order $renewal_order, WC_Subscription $subscription` | Update failing payment method or clear retry state after customer pays a failed renewal. |

## 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`.

| Need | Hook | Type | Args | Use |
|---|---|---|---|---|
| Add/remove date types to schedule | `woocommerce_subscriptions_date_types_to_schedule` | filter | `string[] $date_types` | Include custom subscription date types. |
| Change scheduled action hook | `woocommerce_subscriptions_scheduled_action_hook` | filter | `string $hook, string $date_type` | Route a date type to a custom action. |
| Change scheduled args | `woocommerce_subscriptions_scheduled_action_args` | filter | `array $args, string $date_type, WC_Subscription $subscription` | Add deterministic args for custom scheduled actions. |
| Change Action Scheduler priority | `woocommerce_subscriptions_scheduled_action_priority` | filter | `int $priority, string $action_hook` | Default is priority `1`. |
| Trial ended | `woocommerce_subscription_trial_ended` | action | `int $subscription_id` | Fired from scheduled trial end handler. |
| Expiration/end hooks | `woocommerce_scheduled_subscription_expiration`, `woocommerce_scheduled_subscription_end_of_prepaid_term` | action | `int $subscription_id` | Internal status handlers run here; attach after them if you need post-status side effects. |

## Payment retry hooks

| Need | Hook | Type | Args | Use |
|---|---|---|---|---|
| Enable/disable retries | `wcs_is_retry_enabled` | filter | `bool $enabled` | Feature-level gate. |
| Replace default retry rules | `wcs_default_retry_rules` | filter | `array $rules` | Configure retry cadence/statuses. |
| Alter one retry rule | `wcs_get_retry_rule_raw`, `wcs_get_retry_rule` | filter | `$rule, $retry_number, $order_id` | Fine-grained retry rule customization. |
| Before/after applying rule | `woocommerce_subscriptions_before_apply_retry_rule`, `woocommerce_subscriptions_after_apply_retry_rule` | action | `WCS_Retry_Rule $rule, WC_Order $last_order, WC_Subscription $subscription` | Observe scheduled retry creation. |
| Retry action is about to charge | `woocommerce_subscriptions_before_payment_retry` | action | `WCS_Retry $retry, WC_Order $last_order` | Prepare/log before retry payment. |
| Retry charge finished | `woocommerce_subscriptions_after_payment_retry` | action | `WCS_Retry $retry, WC_Order $last_order` | Record retry result. |
| Retry status/date changed | `woocommerce_subscriptions_retry_status_updated`, `woocommerce_subscriptions_retry_date_updated` | action | `WCS_Retry ...` | External sync for retry objects. |

## Switching, early renewal, gifting

| Area | Hooks | Use |
|---|---|---|
| Switch eligibility | `wcs_is_product_switchable`, `woocommerce_subscriptions_can_item_be_switched`, `woocommerce_subscriptions_can_item_be_switched_by_user` | Allow/block switching by product, item, or user. |
| Switch pricing | `wcs_switch_should_prorate_recurring_price`, `wcs_switch_should_prorate_sign_up_fee`, `wcs_switch_sign_up_fee`, `wcs_switch_proration_extra_to_pay` | Adjust proration math. |
| Switch completion | `woocommerce_subscriptions_switch_completed` | React after switch order flow completes. |
| Early renewal | `wcs_is_early_renewal_enabled`, `woocommerce_subscriptions_can_user_renew_early`, `woocommerce_subscriptions_get_early_renewal_url` | Enable/disable and route early renewal. |
| Gifting product/checkout | `wcsg_enable_gifting`, `wcsg_is_enabled_for_all_products`, `wcsg_is_giftable_product`, `wcsg_cart_item_data` | Control whether gifting is available and persisted in cart. |
| Gifting recipient | `wcsg_recipient_details_updated`, `woocommerce_subscriptions_gifting_recipient_changed` | Sync recipient changes. |

## Gateway hooks

| Need | Hook | Type | Args | Use |
|---|---|---|---|---|
| Gateway support check | `woocommerce_subscription_payment_gateway_supports` | filter | `bool $supports, string $feature, WC_Subscription $subscription` | Add support for features like `subscription_date_changes`. |
| Status changed for gateway | `woocommerce_subscription_activated_{gateway_id}`, `woocommerce_subscription_on-hold_{gateway_id}`, `woocommerce_subscription_pending-cancel_{gateway_id}`, `woocommerce_subscription_cancelled_{gateway_id}`, `woocommerce_subscription_expired_{gateway_id}` | action | `WC_Subscription $subscription` | Gateway-specific remote profile updates. |
| Payment method updated | `woocommerce_subscription_payment_method_updated` | action | `WC_Subscription $subscription, string $new, string $old` | Sync token/payment method changes. |
| Payment method updated to/from gateway | `woocommerce_subscription_payment_method_updated_to_{gateway_id}`, `woocommerce_subscription_payment_method_updated_from_{gateway_id}` | action | `WC_Subscription $subscription, string $other_gateway_id` | Gateway-specific migration logic. |
| Failing method updated | `woocommerce_subscription_failing_payment_method_updated` and `..._{gateway_id}` | action | `WC_Subscription $subscription, WC_Order $renewal_order` | After customer changes method for a failed renewal. |
| Payment meta fields | `woocommerce_subscription_payment_meta` | filter | `array $payment_meta, WC_Subscription $subscription` | Add fields to payment-method change UI. |
| Validate payment meta | `woocommerce_subscription_validate_payment_meta` and `..._{gateway_id}` | action | `array $payment_meta, WC_Subscription $subscription` | Throw/notice on invalid payment details. |

## 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

```php
// 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.