Skip to main content

benecaster_get_subscriber_data()

Membership Free 
benecaster_get_subscriber_data( string $email, int $show_id ): ?array

Looks up a subscriber’s Benecaster state for one show, starting from their email address. Built for integrations whose own data — a CRM export, a webhook payload, a CSV — is keyed by email rather than by WordPress user ID.

Benecaster subscribers are WordPress users; there is no subscriber record that exists independently of the WP user. This is a convenience layer over that lookup plus the existing public functions, so one call replaces three.

null and “no access” are different answers, and conflating them loses information. null means no WordPress user holds that address. A user who exists but has never had a token for this show comes back as an array with token_status of 'none' and an empty tier — that is somebody with an account who simply is not subscribed here, which usually deserves different handling from a stranger.

Parameters

Name Type Default Required Description
email string — Yes Email address to look up. Trimmed before matching.
show_id int — Yes Show post ID to scope the tier and token state to.

Return Value

Type: array|null

An array of the subscriber's state for that show, or null when no WordPress user holds that email. Keys: user_id (int), email (string — the address as WordPress stores it, which may differ from the argument in case and whitespace), wp_display_name (string), wall_display_name (string), tier (string — empty when the token is not active), token_status (string), revocation_reason (string), token_type (string — the stored type, verbatim: subscriber, follower, purchaser or an add-on's own type), token_type_base (string — subscriber or follower, what that type behaves as). Both type keys are '' when the user has no token for the show.

Example

foreach ( $crm_rows as $row ) {
    $data = benecaster_get_subscriber_data( $row['email'], $show_id );

    if ( null === $data ) {
        // Nobody on this site has that address at all.
        continue;
    }

    if ( 'none' === $data['token_status'] ) {
        // Has an account, has never had access to this show.
        continue;
    }

    my_crm_sync( $row['id'], $data['tier'], $data['token_status'] );
}

Hooks Fired

Notes

token_status is 'active', 'revoked', or 'none'. There is no 'expired'. Anything written against an 'expired' value is testing for a string the function cannot return.

Revocation covers five different situations — a bridge cancellation, a license grace timeout, a promotion grace expiry, a manual grant reaching its end date, and a podcaster deliberately removing somebody. Collapsing those into "expired" would report a lapsed subscription for a subscriber who was removed by hand, which is why revocation_reason comes back alongside rather than being left to guesswork. It is an empty string for active tokens, for 'none', and for legacy revoked rows written before the reason was recorded.

Branch on token_type_base, never on token_type. token_type is open-ended — an add-on can register its own listener type that behaves as a follower — so 'follower' === $data['token_type'] would file that add-on's listeners as subscribers. Compare token_type only to recognise a type you know, such as purchaser. The same two facts are available from a token ID with benecaster_get_token_type().

tier comes through benecaster_get_user_tier_for_show(), so the benecaster_user_tier_for_show filter applies here too. A Preview as Tier session does not change the answer: the preview applies only when the previewing admin asks about themselves.

Use benecaster_get_user_id_by_subscriber_email() instead when all you need is the ID.

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