Skip to main content

Email Merge Tags Reference

Merge tags are {{double-brace}} placeholders in email templates that Benecaster replaces with real values at send time — one resolution per recipient.

The full list, per email type, comes from benecaster_get_email_merge_tag_catalog(), which also says which tags hold a URL and which carry HTML. Only {{custom_message}} carries HTML; every other tag is plain text and is escaped where it is printed. The feed tag is {{feed_url}}; there is no {{rss_url}}.

A subject is tidied after its tags are filled: repeated spaces are collapsed, and a dash, colon or comma left dangling at either end by an empty tag is removed. So Your {{show_title}} receipt — {{amount_formatted}} with no amount sends as Your My Podcast receipt.

In a design stored by an email editor, a tag that belongs to that email type and has no value prints nothing. Any other {{text}}, including a tag that belongs to a different email type, stays exactly as written. Template files and subject lines don’t follow this rule.

Global Tags

Available in every Benecaster email regardless of type.

Tag Value
{{site_name}} WordPress site name from Settings → General
{{site_url}} WordPress site URL
{{current_year}} Current four-digit year
{{subscriber_name}} Subscriber’s display name; empty string for admin-only emails
{{subscriber_email}} Subscriber’s email address; empty string for admin-only emails
{{show_title}} Display name of the show, as plain text (& and other entities decoded)
{{preheader}} The inbox preview line, when the send sets one (a broadcast’s preheader, for example); otherwise empty
{{show_url}} Show’s public URL: the show’s own page. The default templates use it only for Subscribe and Resubscribe buttons
{{account_url}} The subscriber’s account page, where they manage their plan, payment method, billing address and feed link. Every your account page link and every Update payment method, Manage subscription and Update your billing address button in the default templates uses it. Empty when the account page has been deleted, so guard for that
{{show_support_email}} Where subscribers can write to: the show’s Author Email (the show’s Details settings), or the site admin email when that’s blank or no show is in context. Only empty when the site has no admin email either, so guard for that before writing a sentence around it
{{unsubscribe_url}} HMAC-signed opt-out URL for this subscriber and show. Empty string on transactional types (the billing emails among them), on types registered 'unsubscribable' => false, and on admin-only emails

Welcome Email Tags

If you’re using the Email Editor, these tags are available in the merge tag autocomplete — no manual typing required. Available in addition to all global tags when $email_type is welcome.

Tag Value
{{feed_url}} Subscriber’s new private RSS feed URL (plaintext token URL, filtered via benecaster_token_url)
{{tier_name}} Subscriber’s tier display name from TierMapRepository; empty string if no tier map row exists
{{apple_podcasts_url}} Deep link to open the feed in Apple Podcasts
{{overcast_url}} Deep link to open the feed in Overcast
{{pocket_casts_url}} Deep link to open the feed in Pocket Casts
{{castro_url}} Deep link to open the feed in Castro
{{podcast_addict_url}} Deep link to open the feed in Podcast Addict (podcastaddict://subscribe?url=...)
{{marketing_consent_text}} The wording of the marketing checkbox, for someone who signed up for a free tier while logged out, ticked the box and has not confirmed it. Empty for everyone else
{{marketing_confirm_url}} The link that says yes to that wording and confirms the answer. Empty when {{marketing_consent_text}} is. An edited Welcome email needs both tags, or those people can’t confirm their answer

Token Reset Email Tags

Available in addition to all global tags when $email_type is token_reset.

Tag Value
{{feed_url}} New private RSS feed URL after reset
{{apple_podcasts_url}} Deep link for the new feed URL
{{overcast_url}} Deep link for the new feed URL
{{pocket_casts_url}} Deep link for the new feed URL
{{castro_url}} Deep link for the new feed URL
{{podcast_addict_url}} Deep link for the new feed URL (Podcast Addict)
{{custom_message}} Optional admin-supplied note; empty string when no message was provided

The default template closes with a Why did this happen? note that uses {{show_title}} and {{show_support_email}}. If the support address is empty, the contact sentence is left out.

Tier Change Email Tags

Available in addition to all global tags when $email_type is tier_change.

Tag Value
{{old_tier_name}} Display name of the subscriber’s previous tier, from the show’s own tier list — Built-in Membership tiers or the membership plugin’s tier mapping, whichever the show uses. Falls back to the tier’s slug if neither knows it; never empty
{{new_tier_name}} Display name of the new tier, looked up the same way. Falls back to the slug; never empty

Donation Thank-You Email Tags

Available when $email_type is donation_thank_you. Only sent when the “Collect donor email” setting is enabled for the show.

Tag Value
{{donor_name}} Donor’s name as submitted; empty string if not collected
{{amount_formatted}} Locale-formatted amount with currency symbol (e.g. $10.00)
{{amount}} Raw amount in major units (e.g. 10.00)
{{currency}} ISO 4217 currency code, uppercase (e.g. USD)
{{show_title}} Display name of the show
{{donation_date}} Date of donation in site date format
{{donor_message}} Message left by donor; empty string if not collected or not configured

Subscription Receipt Email Tags

Available in addition to all global tags when $email_type is subscription_receipt.

Tag Value
{{amount_formatted}} Amount actually paid, with its currency code, at that currency’s precision (USD 9.00, JPY 1,500, KWD 5.250)
{{invoice_number}} Stripe invoice number
{{invoice_hosted_url}} Link to the Stripe-hosted invoice page
{{invoice_pdf_url}} Link to download the invoice PDF
{{tier_name}} Subscriber’s tier display name
{{period_end_formatted}} Formatted next renewal date
{{line_items}} What the payment covers: one item per line, Description — USD 9.00, joined by a newline. The description is Stripe’s own for the invoice line: the plan, and each buy-up. Empty when the invoice carries no lines
{{subtotal_formatted}} Invoice subtotal; empty when no tax was charged
{{tax_formatted}} Tax on the invoice; empty when no tax was charged
{{tax_inclusive}} 1 when the tax is included in the prices, otherwise empty. The subtotal then already contains the tax, so print the total and includes tax, never Subtotal + Tax = Total
{{total_formatted}} Invoice total
{{line_items_incomplete}} 1 when {{line_items}} is not every item on the invoice because Stripe could not be asked for the rest, otherwise empty. The default template then says the payment covers more items than listed

All six come from Stripe’s invoice for that payment, and every value is a string. To split {{line_items}} in a PHP override, see Customizing Email Templates.

Renewal Reminder Email Tags

Available in addition to all global tags when $email_type is renewal_reminder.

Tag Value
{{tier_name}} Subscriber’s tier display name
{{renewal_date}} Formatted renewal date
{{days_until_renewal}} Integer number of days until the billing period ends
{{renews_in}} The same, in words: 7 days, 1 day. The default subject uses it
{{amount_formatted}} Renewal amount with its currency code, at that currency’s precision (USD 9.00, JPY 1,500, KWD 5.250). With Calculate tax automatically off, a prediction: the tier’s price for this billing period plus the subscriber’s active buy-ups. With it on, Stripe’s own total for the upcoming invoice, tax included; if Stripe can’t be asked, the same prediction, before tax (see {{amount_before_tax}}). Empty when no price can be found for the subscriber’s tier and billing period
{{billing_interval}} month or year
{{subtotal_formatted}} Upcoming subtotal; empty when there is no tax
{{tax_formatted}} Upcoming tax; empty when there is none
{{tax_inclusive}} 1 when the tax is included in the prices, otherwise empty
{{amount_before_tax}} 1 when Calculate tax automatically is on but Stripe’s upcoming-invoice preview couldn’t be had, so {{amount_formatted}} is the stored, pre-tax price; otherwise empty. The default template then labels the amount Amount before tax:

Calculate tax automatically is at Benecaster → Settings → Payments. With it off, the four tax tags are empty.

Payment Failed Email Tags

Available in addition to all global tags when $email_type is payment_failed.

Tag Value
{{tier_name}} Subscriber’s tier display name

Cancellation Confirmation Email Tags

Available in addition to all global tags when $email_type is cancellation_confirmation.

Tag Value
{{tier_name}} Subscriber’s tier display name
{{period_end_formatted}} Formatted date access ends
{{resume_url}} URL to resume the subscription — filterable via benecaster_cancellation_confirmation_resume_url

Subscription Cancelled Email Tags

Available in addition to all global tags when $email_type is subscription_cancelled.

Tag Value
{{tier_name}} Subscriber’s tier display name
{{period_end_formatted}} Formatted date access ended (if cancel_at_period_end was set)
{{keeps_purchases}} 1 when the subscriber bought episodes outright and keeps their private feed for them, otherwise empty. The default template then says the feed keeps working and labels the date Plan ended: instead of Access ended:
{{removed_by_podcaster}} 1 when you had already removed the subscriber, otherwise empty. The default template then says they will not be charged again and their access had already ended, with no resubscribe line or button

This email is not sent at all to a subscriber who still holds another active plan on the show.

Price Change Notice, Reminder, and Cancelled Email Tags

Available in addition to all global tags when $email_type is price_change_notice, price_change_reminder, or price_change_cancelled — all three share the same tag set.

Tag Value
{{item_name}} Tier or buy-up name the change applies to
{{old_price}} Current price, formatted with currency
{{new_price}} New price the subscriber is moving to, formatted with currency
{{effective_date}} Formatted date the new price takes effect
{{notice_days}} Days of notice configured for this change
{{timing_sentence}} Pre-built sentence describing the notice window — print this rather than building your own from {{notice_days}}; see Customizing Email Templates for why

Billing Change Scheduled Email Tags

Available in addition to all global tags when $email_type is cadence_switch_scheduled.

Tag Value
{{from_label}} The billing period the subscriber is on now, e.g. “Monthly”
{{to_label}} The billing period they’re switching to, e.g. “Annual”
{{price_formatted}} What they’ll pay from the switch date, formatted with currency
{{switch_date}} Formatted date the switch takes effect — the subscriber’s next renewal
{{later_formatted}} A later price on the new billing period, formatted with currency; empty string unless a price change on it lands after the switch
{{later_date}} Formatted date of the first charge at {{later_formatted}}; empty string when that is

The Plan Change Scheduled email (tier_switch_scheduled) carries the same six tags, with {{from_label}} and {{to_label}} holding plan names rather than billing periods. It is sent only for a move down or to a tier at the same price, so {{switch_date}} is always the subscriber’s next renewal. An upgrade takes effect at once and sends no scheduled email — only Tier Change.

Move to Free Plan Scheduled Email Tags

Available in addition to all global tags when $email_type is free_tier_switch_scheduled.

Tag Value
{{from_label}} The paid plan the subscriber is on now, e.g. “Gold”
{{to_label}} The free plan they’re moving to, e.g. “Free”
{{switch_date}} Formatted date the move takes effect: the end of the period they’ve already paid for

There is no price tag: the move ends the subscriber’s payments.

Billing Address Needed for Tax Email Tags

$email_type is tax_address_needed. There are no type-specific tags: the email uses the global tags only. Its Update your billing address button links {{account_url}}, the subscriber’s account page, whose Billing section has the Billing address form.

Sales Passed US$1,000 Email Tags

Available in addition to the global tags when $email_type is tax_threshold_nudge. This email goes to the site’s admin email address, not a subscriber, so {{subscriber_name}}, {{subscriber_email}} and {{unsubscribe_url}} are empty.

Tag Value
{{sales_lines}} The show’s net sales so far this calendar year, after tax and refunds, one currency per line (e.g. USD 1,200.00), joined by a newline
{{year}} The four-digit calendar year, in the site’s timezone
{{settings_url}} Link to Benecaster → Settings → Payments in wp-admin

Manual Grant Expired Email Tags

Available in addition to all global tags when $email_type is manual_grant_expired.

Tag Value
{{tier_name}} Subscriber’s tier display name; empty string when the tier has since been deleted

This email does not receive a {{feed_url}} tag — the subscriber’s token has already been revoked before it dispatches.

Promote Grace Reminder and Expired Email Tags

Available in addition to all global tags when $email_type is promote_grace_reminder or promote_grace_expired.

Tag Value
{{tier_name}} The subscriber’s original native tier name
{{grace_period_end_date}} Formatted expiry date
{{target_plugin_name}} Name of the destination membership plugin
{{signup_url}} The destination plugin’s signup page for the subscriber’s level, always a page on this site: the one confirmed under Show Settings → Subscription → Signup pages, or else the one Benecaster suggests from the plugin’s settings. Empty when no signup page can be found for the level

The reminder’s Re-enter payment details button and the expiry email’s Resubscribe button link {{signup_url}}. When it is empty, both default templates link {{show_url}} instead, labelled Visit the show page.

Account Provisioning Email Tags

These four types are registered in EmailTypeRegistry (follower_confirm is not, but is dispatched the same way and its tags work identically). None are managed by per-show toggle — see Customizing Email Templates for the suppression caveats that apply to them.

New Account — Set Password ($email_type is guest_password_set):

Tag Value
{{reset_url}} Single-use password-reset link

Already Following ($email_type is already_following):

Tag Value
{{login_url}} Single-use signed link that lets the follower into their account
{{account_url}} Plain account page URL (the same as the global tag), for anyone who prefers to log in normally
{{feed_url}} The follower’s existing private feed URL. Nothing is reset, so an app already set up keeps working
{{apple_podcasts_url}} Deep link for that feed URL
{{overcast_url}} Deep link for that feed URL
{{pocket_casts_url}} Deep link for that feed URL
{{castro_url}} Deep link for that feed URL
{{podcast_addict_url}} Deep link for that feed URL (Podcast Addict)

{{feed_url}} and the five app links are empty when the URL can’t be recovered, and the default template then sends only the sign-in link. That happens when the feed link can’t be read back (for example, it dates from before recoverable feed links, or the site’s encryption key has changed or is unavailable), when it has been revoked, or when the address belongs to a paying subscriber rather than a follower and the show’s feed has gone dark. A follower on a dark show still gets their URL, because their feed keeps serving the public episodes.

Follower — Confirm Signup ($email_type is follower_confirm):

Tag Value
{{confirm_url}} Single-use signed link that confirms the signup and mints the token. It only follows the show: it doesn’t confirm a marketing answer
{{marketing_consent_text}} The wording of the marketing checkbox when it was ticked on the signup form, otherwise empty
{{marketing_confirm_url}} Single-use signed link that follows the show and confirms the marketing answer. Empty when the box wasn’t ticked. An edited email needs this tag and {{marketing_consent_text}} together, or nobody can confirm their answer

Email Verification ($email_type is email_verification):

Tag Value
{{verify_url}} Single-use link, good for 24 hours, that promotes the new address
{{new_email}} The address being verified — this message’s own recipient

Episode Notification Email Tags

Available when $email_type is episode_notification. Requires the Email Editor add-on.

Tag Value
{{episode_title}} Episode post title
{{episode_url}} Episode page URL
{{episode_number}} Episode number; empty string if not set
{{season_number}} Season number; empty string if not set
{{season_name}} Season display name (Podcasting 2.0); empty string if not set
{{episode_type}} full, trailer, or bonus
{{episode_duration}} Human-readable duration
{{episode_artwork_url}} Episode artwork URL
{{listen_url}} URL to listen to the episode
{{tier_name}} Subscriber’s tier display name
{{availability_date}} Date this tier can access the episode
{{episode_magic_link}} Per-subscriber tokenized episode URL for one-click access (Email Editor only)
{{player_image}} HTML player card with artwork + play button, linked to magic link (Email Editor only)

Registering Custom Tags

Add your own merge tags via benecaster_email_merge_tags (global) or benecaster_email_merge_tags_{type} (type-specific):

// Global — available in every email type
add_filter( 'benecaster_email_merge_tags', function( array $tags, string $type, ?int $user_id, ?int $show_id ): array {
    $tags['podcast_network'] = get_option( 'podcast_network_name', '' );
    return $tags;
}, 10, 4 );

// Type-specific — available in welcome emails only (3 params, no $type)
add_filter( 'benecaster_email_merge_tags_welcome', function( array $tags, ?int $user_id, ?int $show_id ): array {
    $tags['tier_benefits_url'] = home_url( '/member-benefits/' );
    return $tags;
}, 10, 3 );

Tags are resolved at enqueue time — your filter receives an already-populated $tags array with all built-in values for that send. Add new keys or overwrite existing ones. Return the modified array.

Using Tags in Templates

In PHP templates, use $tags['tag_name'] directly (the resolved variable, not the brace syntax). In template content strings rendered by the email renderer, use {{tag_name}} and the renderer substitutes the value before output.

See Customizing Email Templates for template override details.

See Also

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