`benecaster_user_tier_for_show`

Filter Free Since v1.0.0

Filters the resolved tier slug for the current user on a given show. Fires at the end of benecaster_get_user_tier_for_show() after the database lookup completes. The value entering the filter is the slug from the user’s active token, or an empty string when no active token exists.

This is the correct filter for synthetic tier injection — granting access by returning a tier slug without a real token, for use cases such as grace periods, gift subscriptions, or course-completion access. Prefer this filter over episode-specific access filters when the access grant is tier-scoped rather than tied to a single episode. The return value flows downstream to benecaster_episode_is_accessible, so any tier slug injected here will be received as $tier_slug in that filter as well. Return an empty string to treat the user as having no active subscription, causing locked episode content and upgrade prompts to render as if the user were unauthenticated. Free — registered regardless of license status.

Parameters

Name	Type	Default	Description
`$tier`	`string`	—	Resolved tier slug; empty string when user has no active subscription
`$show_id`	`int`	—	ID of the show
`$user_id`	`int`	—	WordPress user ID

Returns: string

Examples

Grace period after lapsed subscription

add_filter( 'benecaster_user_tier_for_show', function( $tier, $show_id, $user_id ) {
    // Grant 'premium' access during a 7-day grace period after a lapsed subscription.
    if ( ! $tier ) {
        $lapsed_at = (int) get_user_meta( $user_id, '_show_' . $show_id . '_lapsed_at', true );
        if ( $lapsed_at && ( time() - $lapsed_at ) < WEEK_IN_SECONDS ) {
            return 'premium';
        }
    }
    return $tier;
}, 10, 3 );

Grant tier on course completion

add_filter( 'benecaster_user_tier_for_show', function(
    string $tier_slug,
    int    $show_id,
    int    $user_id
): string {
    if ( $tier_slug !== '' || $user_id === 0 ) {
        return $tier_slug;
    }

    $course_id = 123; // LearnDash course ID
    if ( learndash_course_completed( $user_id, $course_id ) ) {
        return 'starter'; // grant Starter tier access
    }

    return '';
}, 10, 3 );

Notes

Returning a tier slug that does not correspond to a configured tier may cause unexpected behavior in tier-aware template functions. Preview as Tier mode uses this filter internally — do not remove all callbacks unconditionally.

Affects

benecaster_get_user_tier_for_show() function
PreviewTierManager (Preview as Tier mode)