Skip to main content

Thank annual switchers, and tell your CRM when a subscriber changes billing period

Premium Intermediate

A built-in-membership subscriber can move to another billing period of their own tier from the account page. The switch lands at their next renewal, so there are two moments to react to: when they ask (…_switch_scheduled) and when it takes effect (…_switched). A switch can also be withdrawn before it lands (…_switch_cancelled).

Act on …_switched, not …_switch_scheduled, for anything that assumes the new price is being paid. A scheduled switch can still be withdrawn: by the subscriber (subscriber), by cancelling the membership (membership_cancelled), by the license hard-cutoff pause (billing_paused), or in the Stripe dashboard (stripe).

The tier does not change on a billing-period switch. benecaster_subscription_tier_changed does not fire for one, and the feed URL is the same before and after.

These three hooks also fire when a subscriber moves to another tier, because both kinds of change share one mechanism. A tier move keeps the billing period, so $to_price_id points at a price on a different tier. If your callback is only about billing periods, compare the tier of $from_price_id and $to_price_id first. For tier moves, see React to a scheduled plan change.

Price ids are benecaster_membership_prices.id, not Stripe Price ids. In …_switched, $from_price_id is 0 for a subscription created before the plugin recorded which price it was on.

Code

<?php
// Record the intent at once, but grant the perk only when the annual price is actually billed.
add_action(
    'benecaster_subscription_cadence_switch_scheduled',
    function ( int $user_id, int $show_id, int $from_price_id, int $to_price_id, int $switch_at ): void {
        my_crm_note( $user_id, sprintf( 'Switching billing period on %s', wp_date( 'Y-m-d', $switch_at ) ) );
    },
    10,
    5
);
add_action(
    'benecaster_subscription_cadence_switched',
    function ( int $user_id, int $show_id, int $from_price_id, int $to_price_id ): void {
        global $wpdb;
        $unit = $wpdb->get_var( $wpdb->prepare(
            "SELECT interval_unit FROM {$wpdb->prefix}benecaster_membership_prices WHERE id = %d",
            $to_price_id
        ) );
        if ( 'year' === $unit ) {
            my_send_annual_thank_you( $user_id, $show_id );
        }
    },
    10,
    4
);
add_action(
    'benecaster_subscription_cadence_switch_cancelled',
    function ( int $user_id, int $show_id, int $to_price_id, string $reason ): void {
        my_crm_note( $user_id, 'Billing-period switch withdrawn: ' . $reason );
    },
    10,
    4
);

View on GitHub →

Hooks Used

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