Skip to main content

benecaster_subscription_tier_moved

Action Premium

Fires once whenever a subscriber’s tier changes to a different tier, whatever reported the change, and sends nothing itself — no email. This is the hook to listen to when you need to know that a subscriber now holds a different tier: to retag them in an email platform, update a CRM field, or provision tier-specific perks.

It fires for:

  • A plan change in a membership plugin. MemberPress (a move inside an upgrade-path group), Paid Memberships Pro, Restrict Content Pro and WooCommerce Subscriptions (a plan switch) all reach Benecaster as an activation on a subscriber who is already active, so benecaster_subscription_activated fires too. On Restrict Content Pro the plugin cancels the old membership before it activates the new one; Benecaster sees the replacement and keeps the feed URL, so the subscriber is never revoked in between.
  • A partial cancellation — a subscriber holding two tiers cancels one and keeps the higher remaining tier.
  • A built-in membership tier switch, a move onto the free plan landing, and an admin tier change from Subscribers. These also fire benecaster_subscription_tier_changed, which runs first.

benecaster_subscription_tier_changed never fires for a membership-plugin plan change, because it sends the Tier Change email. On a built-in-membership show and for an admin change both hooks fire for the same move, so never put the same job on both.

It does not fire for a renewal on the same tier, a follower or a single-purchase listener starting a subscription (a join, not a move), a WooCommerce Subscriptions switch onto a product mapped to no tier, or a cancelled subscriber resubscribing on another tier — that is a reactivation, and benecaster_token_reactivated carries the new tier.

The two slugs carry no direction. To tell an upgrade from a downgrade, call benecaster_compare_tiers(); never compare the slugs yourself.

Parameters

Name Type Default Description
$user_id int — WordPress user ID
$show_id int — ID of the show
$old_tier_slug string — The tier the subscriber held before the move
$new_tier_slug string — The tier the subscriber holds now

Examples

Retag a subscriber on any tier move, with its direction

add_action( 'benecaster_subscription_tier_moved', function ( int $user_id, int $show_id, string $old, string $new ): void {
    $direction = benecaster_compare_tiers( $show_id, $new, $old ); // > 0 upgrade, < 0 downgrade, null cannot rank
    my_crm_retag( $user_id, $show_id, $new, $direction );
}, 10, 4 );

Notes

The membership-plugin path runs only while the site's license is active. The built-in and admin paths fire whatever the license state, as benecaster_subscription_tier_changed does.

A plan change that a membership plugin reports as a cancellation of the subscriber's only tier followed by a new signup can reach you as benecaster_token_revoked and then benecaster_token_reactivated instead. To cover it, also retag on benecaster_token_reactivated. Worked example: the recipe Retag a subscriber in your email platform whenever their tier changes.

Related Recipes

Need this built rather than just documented? See our services →