Follower Tier — REST API Reference

The free follower tier adds a follower_tier field to the show tiers endpoint and a token_type field to subscriber list responses.

GET /benecaster/v1/shows/{id}/tiers

The response now includes a top-level follower_tier object alongside the items array (bridge tier list).

{
  "items": [
    { "slug": "gold", "name": "Gold", ... },
    { "slug": "silver", "name": "Silver", ... }
  ],
  "follower_tier": {
    "internal_slug": "follower",
    "internal_name": "Followers",
    "feed_url": "https://yoursite.com/podcast-feed/your-show/follower/",
    "subscriber_count": 142
  }
}

follower_tier always appears in the response — even when no followers have signed up yet (subscriber_count will be 0). It is not conditional on follower signups existing.

internal_slug reflects the show’s follower tier slug. The default is "follower". If you’ve overridden it via the benecaster_follower_tier_slug filter, the overridden value is returned here.

feed_url is the base feed URL for the follower tier, without a token. This is the URL prefix used to construct individual follower feed URLs.

GET /benecaster/v1/shows/{id}/subscribers

Each subscriber item now carries a token_type field:

{
  "id": 47,
  "email": "listener@example.com",
  "token_type": "subscriber",
  ...
}

{
  "id": 91,
  "email": "follower@example.com",
  "token_type": "follower",
  ...
}

The summary object gains two fields alongside the existing keys:

{
  "summary": {
    "paying": 84,
    "followers": 142,
    "total": 226
  }
}

paying is the count of tokens where token_type = 'subscriber' and the tier is not a free-mapped bridge tier. This is the figure that drives plan threshold logic — use paying, not total or active, when evaluating against subscriber limits.

followers is the count of tokens where token_type = 'follower'. Followers do not count toward plan limits.

benecaster_follower_tier_slug Filter

Overrides the internal slug used to store and query follower availability rows in benecaster_availability. Applied per-show.

add_filter( 'benecaster_follower_tier_slug', function( string $slug, int $show_id ): string {
    // Return a custom slug for a specific show
    if ( $show_id === 5 ) {
        return 'free-listeners';
    }
    return $slug; // default: 'follower'
}, 10, 2 );

Important: Changing this filter after availability rows have already been written for a show will cause existing follower-availability episodes to stop appearing in follower feeds — the stored slug in benecaster_availability will no longer match. If you need to rename the slug on an existing show, run a UPDATE benecaster_availability SET tier_slug = 'new-slug' WHERE tier_slug = 'old-slug' AND show_id = {id} migration.