This guide explains the available hooks in the WPSubscription and WPSubscription Pro plugins. These hooks allow developers to trigger custom logic at different stages of the subscription lifecycle or modify subscription-related behavior.

What Are Hooks?

Hooks let developers:

  • Trigger actions when a subscription is created, canceled, expired, etc.

  • Customize WooCommerce behavior during renewals or cart handling

  • Integrate with external tools (via REST API or automation tools)

Hooks are available as:

  • do_action() (Actions): Trigger a function at a specific point

  • add_filter() (Filters): Modify data before it is returned or saved

Free Version Hooks

These are available in the free WPSubscription plugin.

Action Hooks

Hook Name

Triggered When

Parameters

subscrpt_subscription_activated

Subscription is activated

$subscription_id

subscrpt_subscription_expired

Subscription expires

$subscription_id

subscrpt_subscription_cancelled

Subscription is cancelled

$subscription_id

subscrpt_subscription_pending_cancellation

Subscription marked for cancellation

$subscription_id

subscrpt_subscription_pending

Subscription status is pending

$subscription_id

subscrpt_subscription_resumed

Resumed from cancellation

$subscription_id, $old_status

subscrpt_subscription_status_changed

Status changes

$subscription_id, $old_status, $new_status

subscrpt_status_changed_admin_email_notification

Email alert to admin

$post_id, $old_status_label, $new_status_label

Pro Version Hooks

These are available only in WPSubscription Pro and used mostly for automation and integrations.

REST API Hooks

Hook Name

Triggered When

Parameters

subscrpt_subscription_cancelled

Cancelled via API

$subscription_id

subscrpt_subscription_pending

Paused via API

$subscription_id

subscrpt_subscription_activated

Reactivated via API

$subscription_id

subscrpt_subscription_status_changed

Status changed via API

$subscription_id, $old_status, $new_status

trial_end

Trial ends

$subscription_id

expire_subscription

Marked expired

$subscription_id

payment_failed

Payment fails

$subscription_id

verify_api

API key is verified

api_key

Email Notification Hooks

Used to customize the content and behavior of emails sent to customers or admins.

Hook Name

Purpose

subscrpt_status_changed_admin_email

Admin email on status change

subscrpt_subscription_expired_email

Customer email for expired subscription

subscrpt_subscription_expired_email_notification

System email trigger for expiry

Example: Customize Email Content

add_action('subscrpt_subscription_expired_email', function($subscription_id) {
    add_filter('woocommerce_email_content', function($content) use ($subscription_id) {
        return $content . "\n\nRenew today and save 10%!";
    });
});

Checkout & Cart Filters

These allow customization of how subscription products behave during renewal and checkout.

Filter Name

Description

subscrpt_renewal_item_meta

Add meta to renewal order

subscrpt_renewal_product_args

Modify product args for renewals

subscrpt_block_simple_cart_item_data

Modify cart item data for subscriptions

Admin Filters

Filter Name

Description

post_updated_messages

Customize admin notices for subscriptions

plugin_action_links_{plugin_file}

Add plugin action links (e.g., Settings, Upgrade)

Automation Hooks

Used by third-party plugins for Automations or similar external tools for programmatic subscription control.

Hook

Description

subscrpt_cancel_subscription

Cancel subscription via external trigger

subscrpt_pause_subscription

Pause subscription

subscrpt_resume_subscription

Resume paused subscription

subscrpt_change_status

Change status manually

subscrpt_reactivate_subscription

Reactivate a cancelled subscription

Best Practices

  • Use add_action() or add_filter() with a unique callback function

  • Use priority and number of accepted arguments correctly: add_action('subscrpt_subscription_activated', 'my_custom_function', 10, 1);

Use Cases

  • Send a custom Slack alert on failed renewals

  • Automatically assign roles on activation

  • Trigger CRM workflows on pause or cancellation

  • Extend email templates with loyalty offers

  • Update external dashboards on subscription changes