Functions Reference

The public functions Benecaster provides for add-ons and themes. Each name links to its reference page with the signature, parameters and return value.

Access Tier

Answer whether a listener can hear something: which tier they hold on a show, whether that tier can reach a given episode yet, what opens a locked episode, and which grants (access owned outright, outside any tier) they hold.

Function	Description
`benecaster_compare_tiers()`	Which of two tiers on a show ranks higher — `1`, `-1` or `0`, or `null` when they cannot be ranked. Tells an upgrade from a downgrade.
`benecaster_get_episode_access_tiers()`	What opens a locked episode, for copy such as “Available to Gold subscribers”: its tiers, lowest first, then the buy-ups it requires. An empty list does not mean public.
`benecaster_get_paid_tier_hierarchy()`	A show’s paid built-in tiers, lowest first: the order the audio-variant cascade walks.
`benecaster_get_show_tiers()`	Returns a show’s tiers, slug and name, already in the show’s tier order — for tier pickers in blocks and widgets.
`benecaster_get_user_grants()`	Returns the grants a person currently holds on a show — non-tier access such as episodes or a bundle owned outright, independent of any membership tier.
`benecaster_get_user_tier_for_show()`	Returns the active tier slug for a user’s subscription to a specific show.
`benecaster_user_can_access_episode()`	Returns whether a user can open a specific episode on the website right now: public, a required buy-up held, or an access date that has passed for their tier or for anything they own outright on the show.
`benecaster_user_holds_grant()`	Whether a person holds one named grant on a show. The one to use in a gate.

Analytics

Read the same figures Benecaster’s own analytics screens show — downloads, the win-back list, platform benchmarks and built-in membership revenue — instead of querying its tables.

Function	Description
`benecaster_get_download_total()`	Returns how many tracked downloads a show, or one of its episodes, had over a window, including days older than 30.
`benecaster_get_downloads_by()`	Returns a show’s tracked downloads broken down by tier, podcast app, day or episode.
`benecaster_get_listener_support_donations()`	Returns a show’s Listener Support donations, one row per donation, in minor units.
`benecaster_get_membership_payments()`	Returns what a show’s built-in membership has actually collected, one row per paid invoice.
`benecaster_get_membership_payments_recorded_since()`	Returns when this site began recording built-in membership payments.
`benecaster_get_show_benchmarks()`	Returns the platform benchmarks for a show, from the cached copy only.
`benecaster_get_winback_leads()`	Returns the cancelled subscribers whose podcast app is still checking the feed — the win-back count’s list.

Episode

Work with a single episode: its production notes, its default credits, and finding a show’s latest episode.

Function	Description
`benecaster_add_episode_note()`	Adds a production note to an episode.
`benecaster_get_audio_variant_slug()`	Which tier’s audio variant a tier’s copy of an episode plays, or `null` for the base file. The same choice the feed enclosure makes.
`benecaster_apply_default_credit()`	Public helper that applies the show’s default credit template to an episode.
`benecaster_get_episode_notes()`	The read counterpart to `benecaster_add_episode_note()`.
`benecaster_get_latest_episode_id()`	Returns the ID of a show’s latest episode, for building “newest episode” surfaces in theme code and add-ons without writing the query yourself.

Feed Token

Get people onto a show’s feeds: sign someone up as a free follower, get the public feed URL anyone can subscribe to, or link to the show’s subscribe page.

Function	Description
`benecaster_follower_signup()`	Signs one email address up as a free follower of a show.
`benecaster_get_signup_url()`	Where a show’s subscribe page lives: the same page the signup QR code and the account page’s upgrade link use, falling back to the show’s own page.
`benecaster_is_member_sync()`	Whether the token being written right now belongs to Sync existing members rather than a live signup.
`benecaster_get_token_type()`	Who a token belongs to — its stored type and the `base` (`subscriber` or `follower`) to branch on — for hooks that pass only a token ID.
`benecaster_get_public_feed_url()`	Returns the canonical public (un-gated) feed URL for a show — the URL at `/podcast-feed/{slug}/` that anyone can access without a subscriber token.

Feeds

Build a subscriber’s private feed URL from a token you already hold.

Function	Description
`benecaster_get_feed_url()`	Builds one subscriber’s private feed URL for one show, from a token you already hold.

Membership

Read and change membership state: which membership system a show uses, subscriber lookups and counts, badges, buy-ups, and the names shown on community surfaces.

Function	Description
`benecaster_bridge_supports_manual_membership()`	Returns whether the specified bridge supports programmatic manual subscriber creation — the operation behind the “Add subscriber manually” admin action.
`benecaster_count_paying_subscribers_site_wide()`	Counts paying subscribers across every show on the site, using the same definition of “paying” as benecaster_count_paying_subscribers() — a token type Benecaster doesn’t exempt (a deny list, not `token_type = 'subscriber'`) on a…
`benecaster_count_paying_subscribers()`	Counts paying subscribers for one show.
`benecaster_find_audience_user_ids()`	Resolves a broadcast audience slug to the WordPress user IDs it reaches — the public entry point for answering “who would this send go to?” without pulling anything out of the service container.
`benecaster_get_engagement_threshold()`	Returns a show’s inactivity threshold in days, as the daily engagement check applies it. Display it read-only; never keep a copy.
`benecaster_get_marketing_consent()`	Returns a person’s marketing-consent answer for a show, or `null` when they were never asked — which is not “no”.
`benecaster_get_active_bridge_slug()`	Answers which membership system a show is connected to.
`benecaster_get_buyup_slug()`	Turns a buy-up’s ID into the slug the feed knows it by; `null` for another show’s buy-up.
`benecaster_get_member_thanks_rows()`	Turns a list of user IDs into fully described Member Thanks rows.
`benecaster_get_subscriber_count()`	Returns how many active tokens a show has issued.
`benecaster_get_subscriber_data()`	Looks up a subscriber’s Benecaster state for one show, starting from their email address.
`benecaster_get_user_badges()`	Returns the badges a subscriber has earned, both the ones their tier grants automatically and any an admin gave them by hand, merged and ordered oldest first.
`benecaster_get_user_id_by_subscriber_email()`	Resolves an email address to a WordPress user ID, or `0`.
`benecaster_payment_test_mode_active()`	Whether payments in the requested scope are running against test credentials rather than live ones.
`benecaster_render_user_badges()`	Renders a subscriber’s badge chips as HTML, so a theme can show them anywhere without knowing how badges are stored or styled.
`benecaster_resolve_wall_display_name()`	Canonical function for resolving the name shown on community surfaces — the Supporter Wall, `[benecaster_member_thanks]`, and any add-on that needs to display a subscriber’s name consistently.
`benecaster_set_active_bridge()`	Connects a show to a membership system programmatically — the same value the bridge picker in Settings → Subscription writes, so the UI reflects it on next page load.
`benecaster_user_has_buyup()`	Checks whether a subscriber has bought a particular buy-up on a particular show.

Settings

Register an add-on so it only boots on sites where it is entitled, and connect it to outside systems through the podcaster’s webhook and integration actions.

Function	Description
`benecaster_register_addon()`	Registers an add-on’s boot-time bootstrap with Benecaster’s entitlement gate, so the add-on only boots where it is entitled and needs no `any_show_addon_is_active()` check of its own. A free add-on can register site-wide.
`benecaster_register_integration_action()`	Declares an action an outside system — Zapier, Make, a CRM — may call through `POST /wp-json/benecaster/v1/actions`. Benecaster handles sign-in, checks, idempotency and the call log; your handler does the work.
`benecaster_register_webhook_event()`	Declares an event, named `{addon-slug}.{noun}.{verb}`, that your add-on may send through the podcaster’s webhook.
`benecaster_send_webhook_event()`	Queues one delivery of a registered add-on event; queues nothing on a show where your add-on is off.

Show Episode Description

Read the show and episode descriptions podcast apps display, for use in themes and add-ons.

Function	Description
`benecaster_get_episode_description()`	Returns an episode’s description — the text that appears in podcast apps — for use in theme code, template overrides, and add-ons.
`benecaster_get_show_description()`	Returns a show’s description for use in theme code, template overrides, and add-ons.

Template

Output Benecaster’s pages in your theme: headers and footers, template parts and their overrides, design templates, and the account page URL.

Function	Description
`benecaster_account_page_url()`	Returns the URL of the subscriber account page — where a listener goes to see their feed URL, reset a token, or manage their subscription.
`benecaster_activate_template()`	Activates a design template by slug — either a built-in (`default-light`, `default-dark`) or one installed from a zip by `benecaster_install_template()`.
`benecaster_get_active_template()`	Returns the manifest of the design template currently in force.
`benecaster_get_footer()`	The closing half of `benecaster_get_header()`, with the same three behaviours: the `footer` block template part on block themes, `get_footer()` on classic themes, and silence on themes that have no footer file.
`benecaster_get_header()`	Prints the site header in a way that works on both classic and block themes.
`benecaster_get_installed_templates()`	Returns every design template the site can activate, active or not — the two built-ins shipped with the plugin first, then anything installed from a zip.
`benecaster_get_template_part()`	Renders one of Benecaster’s template parts, resolving it through your child theme, then your parent theme, then any directory an add-on registered with `benecaster_register_template_directory()`, then the plugin’s own copy.
`benecaster_get_template_path()`	Returns the file `benecaster_get_template_part()` would load for a given part, checking child theme, then parent theme, then each registered add-on directory in registration order, then the plugin default.
`benecaster_install_template()`	Validates and installs a Benecaster design template from a zip file.
`benecaster_locate_template()`	Answers one question: has the theme overridden this template part?
`benecaster_register_template_directory()`	Registers a directory that Benecaster will look in when resolving template parts, so an add-on can ship its own parts and override Benecaster’s defaults.

Utilities

General helpers for add-ons and themes: plan and add-on checks, deciding which show a shortcode is for, custom field reads and writes, referral details, sending email and broadcasts, email previews and tests, add-on secrets, REST permissions, and the read-only platform and merge-tag lists behind block and widget pickers.

Function	Description
`benecaster_get_episode_preview_video_html()`	The video preview player for this render, for a theme or add-on that overrides a player template.
`benecaster_get_admin_url()`	A link into Benecaster’s admin, optionally opening it on a given show.
`benecaster_request_wizard_step()`	Asks for an add-on’s setup-wizard step to be run on a show that has already finished setup.
`benecaster_withdraw_wizard_step()`	Takes back a late setup step that is still pending, because what it asks for is already done.
`benecaster_addon_is_active_for_any_show()`	The install-wide counterpart to benecaster_addon_is_active(), mirroring `benecaster_any_show_is_premium()`.
`benecaster_addon_is_active()`	Answers whether an add-on may be used on a particular show, resolving two questions in order: is it granted (does this show’s license entitle it?) and is it enabled (has the podcaster left it switched on for this show?).
`benecaster_delete_secret()`	Removes a secret an add-on stored with `benecaster_store_secret()`.
`benecaster_get_addon_manager_tokens()`	For the Benecaster Add-on Manager only: the site tokens it authenticates with, one per license.
`benecaster_get_email_merge_tag_catalog()`	Describes every merge tag an email can carry, or those one email type can: label, description, sample value and how it is escaped. For editor autocomplete.
`benecaster_get_field()`	Reads one custom field value off one object.
`benecaster_get_fields()`	Reads every value in a field group off one object, keyed the way you named the fields.
`benecaster_get_license_plan()`	Returns which plan the site is on.
`benecaster_get_live_referral_balance()`	The podcaster’s referral credit balance, fetched live from the license server. Returns `null` when the lookup fails, so “no credit” and “could not check” never look the same.
`benecaster_get_notify_referral_updates()`	Reads the podcaster’s answer to Email me when referral credits are earned or applied on the Refer a Friend page.
`benecaster_get_over_limit_show_ids()`	Returns the show IDs currently disabled because the site is over its plan’s show limit.
`benecaster_get_plan_label()`	Turns a plan slug into the name a podcaster would recognise.
`benecaster_get_automatic_podcast_platforms()`	The podcast platforms `[benecaster_platform_links]` fills in itself, with no URL to enter — today just `rss`. Read-only.
`benecaster_get_broadcasts()`	One show’s broadcasts, newest first, optionally between two dates. No message bodies.
`benecaster_get_email_opt_outs()`	Everyone opted out of a show’s email right now.
`benecaster_get_podcast_platforms()`	The podcast listening platforms `[benecaster_platform_links]` can show, for block and widget pickers — including `rss`, which a picker must offer. Read-only.
`benecaster_get_referral_code()`	Returns the customer’s referral code from the locally cached `benecaster_license_referral_code` option.
`benecaster_get_referral_link()`	Returns the podcaster’s own referral URL, ready to share.
`benecaster_get_secret()`	Returns a secret an add-on stored, decrypted; `null` means none is stored or it can no longer be read, so ask for it again.
`benecaster_get_share_merge_tags()`	The merge tags `[benecaster_episode_share]`‘s `text` attribute resolves. Read-only.
`benecaster_get_share_platforms()`	Every platform `[benecaster_episode_share]` can share to — also its default. Read-only.
`benecaster_get_social_platforms()`	The social platforms `[benecaster_social_links]` can link to, for block and widget pickers. Read-only.
`benecaster_get_sole_show_id()`	Returns the show ID on a single-show install, and nothing on a multi-show one.
`benecaster_is_follower_double_optin()`	Whether a new follower of this show must confirm by email before they follow.
`benecaster_is_premium()`	Returns whether a valid premium license is active for the given show.
`benecaster_is_production_site()`	Whether this install is the real site, and not a staging site or a copy. Check it before reaching a real person or a live service.
`benecaster_is_transactional_email_type()`	Whether an email type is still sent to someone who unsubscribed from announcements, decided exactly as the send decides it.
`benecaster_mail()`	Sends an ad-hoc email carrying Benecaster’s sender identity — a drop-in for `wp_mail()` in add-on code.
`benecaster_register_field_cpt()`	Opens your own post type up to Benecaster’s field groups, so podcasters can attach custom fields to it the same way they do to episodes.
`benecaster_render_email_preview()`	Renders an email the way it would be sent, with simulated data, without sending, queueing or logging it.
`benecaster_resolve_show_id()`	Which show a shortcode or block is for, decided as Benecaster’s own shortcodes decide it: the ID given, then the show or episode page, then the only show.
`benecaster_rest_permission_admin()`	Permission callback for an add-on REST route that requires a site admin.
`benecaster_send_broadcast()`	Sends one message to one or more audiences of a show. Returns the broadcast ID at once; the recipients are queued in the background.
`benecaster_send_email()`	Sends one Benecaster email to a WordPress user through the full dispatch pipeline.
`benecaster_send_test_email()`	Sends a test of an email type to any address, with simulated data. A test is not a send of that type: no opt-out check, no send hooks.
`benecaster_store_secret()`	Stores an add-on secret, such as a provider API key, encrypted with the key Benecaster uses for payment credentials. Never send it to the browser.
`benecaster_update_field()`	Writes one custom field value onto one object.
`window.benecasterFrontend.init()`	JavaScript. Wires Benecaster widgets (QR code, feed URL, Copy link) in markup inserted after the page loaded, such as a block preview. Safe to call repeatedly.
`window.benecasterFrontend.seek()`	JavaScript. Moves an episode’s player on the page to a time and plays it; `false` when that episode has no player there. Its page also covers the bubbling `benecaster:timeupdate` event for following playback.
`window.benecasterFrontend.getPlayer()`	JavaScript. Returns the `<audio>` or `<video>` element of an episode’s player on the page, or `null`.

Name	Set by	What it does	Kept for
`wordpress_logged_in_*`	Benecaster	Keeps you signed in to your Benecaster account.	Until you sign out, or two weeks with "Remember Me".
`wordpress_sec_*`	Benecaster	Secures your signed-in session over HTTPS.	Until you sign out, or two weeks with "Remember Me".
`wp-settings-*`	Benecaster	Remembers your admin screen preferences.	One year.
`benecaster_ls_purchase_sign_in`	Benecaster	Signs you in to your new account on the page you bought from, once your purchase has gone through.	Thirty minutes, or until you are signed in.
`benecaster_ls_cookie_consent`	Benecaster	Remembers the choice you make on this banner, so we do not ask again.	One year.

Name	Set by	What it does	Kept for
`__stripe_mid`	Stripe	Lets Stripe recognise the device across payment attempts to detect card fraud.	One year.
`__stripe_sid`	Stripe	The same fraud check, for the current visit only.	Thirty minutes.