Updated: 2026-07-13 15:53:16 UTC

Reserved beehiiv fields and merge tag examples

Certain fields are built into the beehiiv platform to support subscriptions, referrals, analytics, publication details, and other core features. These are considered reserved fields. They can’t be created, renamed, or edited as custom fields — but many of them can be used as merge tags in your posts, automations, and welcome emails.

This guide helps you:

  • Identify field names that are reserved in beehiiv and can’t be used during subscriber imports.
  • Avoid naming conflicts when creating or importing custom fields.
  • Learn how to use reserved fields as merge tags to personalize your content.

Fields are grouped into expandable tables below. Each table includes the reserved field name, a short description, and a merge tag example (when applicable). Click to expand a section and explore the available fields and examples.

Reserved fields related to subscriptions

These fields store subscriber and subscription-related data. Many are used for authentication, preferences, referrals, and account management. Several are available as merge tags, while others function behind the scenes to support platform features.

Subscription-based reserved fields

Field Name Description Merge Tag Example
active_subscriber_count Displays the total number of active subscribers for your publication. Thanks for being our {{active_subscriber_count}} subscribers.
api_subscription_id The subscription ID used for API-based integrations and custom URL tracking. https://example.com/signup?id={{api_subscription_id}}
email Displays the subscriber’s email address. This message is intended for {{email}}.
hostname Displays your publication’s web domain.  All of our content is hosted at {{hostname}}.
integration_connect_url Displays a unique URL for connecting third-party integrations. Connect your account to Discord here: {{integration_connect_url}}
jwt_token Generates a secure authentication token used for login or gated access links. Upgrade here: https://example.com/upgrade?token={{jwt_token}} 
list_unsubscribe_token Token used in email headers to support one-click unsubscribe functionality. System use only, automatically added to email headers.
live_url Displays the public web version URL of a published post. Having trouble viewing this email? Read it online: {{live_url}}
opt_in_token Token used for confirming a subscriber’s opt-in status. System use only, used in confirmation emails.
report_abuse_token Token required for reporting abuse or spam related to a message. System use only, used for abuse reporting links.
reward_promo_code Displays a promo code earned through referral rewards. You’ve earned a reward! Use this code to access your reward: {{reward_promo_code}}
subscriber_email_hash  MD5-hashed version of the subscriber’s email (commonly used for external integrations). https://example.com/signup?email_hash={{subscriber_email_hash}}
subscriber_email_hash_sha1 SHA1-hashed version of the subscriber’s email for secure integrations. https://example.com/signup?email_hash={{subscriber_email_hash_sha1}}
subscriber_email_hash_sha256 SHA256-hashed version of the subscriber’s email for secure integrations. https://example.com/signup?email_hash={{subscriber_email_hash_sha256}}
subscriber_id Unique internal ID assigned to a subscriber. https://example.com/signup?id={{subscriber_id}}
subscriber_preferences_url Displays the URL where a subscriber can manage their preferences. Click here to manage your subscription: {{subscriber_preferences_url}}
subscriber_refer_url Displays the subscriber’s personal referral link. Share your referral URL: {{subsriber_refer_url}}
subscriber_referral_hub_url Displays the subscriber’s referral hub URL. View your referrals here: {{subscriber_referral_hub_url}}
subscription_id Identifier assigned to a specific subscription record. https://example.com/signup?id={{subscription_id}}
subscription_uuid Universally unique identifier (UUID) for the subscription. https://example.com/signup?id={{subscription_uuid}}
unsubscribe_url Displays the unsubscribe link for the subscriber. Click here to unsubscribe: {{unsubscribe_url}}
Reserved fields related to the publications and posts

These fields pull in publication-level or post-level information, such as your publication name, footer details, or RSS content. They’re commonly used in templates and automated content blocks.

Publication or post reserved fields

Field Name Description Merge Tag Example
address_text Displays the publication address shown in the email footer. {{address_text}}
copyright_text Displays the copyright line shown in the email footer (based on your publication settings). {{copyright_text}}
partner_url Displays the subscriber’s Partner Program referral link.  Sign up for beehiiv using my referral link: {{partner_url}}
publication_name Displays your publication name. Welcome to {{publication_name}}
rss_first_item_description Displays the description of the first item in the first RSS block included in a post. Featured article description: {{rss_first_item_description}}
rss_first_item_title Displays the title of the first item in the first RSS block included in a post. Featured article: {{rss_first_item_title}}
Reserved fields related to referrals

These fields are only relevant if your publication has the Referral Program enabled. They allow you to display referral counts, milestone progress, reward details, and personalized referral links for each subscriber.

Referral Program reserved fields

Field Name Description Merge Tag Example
rp_display_with_milestone_styles Displays the publication’s Referral Program with milestone styling. Check out our Referral Program and all the perks you can earn: {{rp_display_with_milestone_styles}}
rp_display_with_no_milestone_styles Displays the publication’s Referral Program without milestone styling. Check out our Referral Program: {{rp_display_with_no_milestone_styles}}
rp_next_milestone_image_styles Displays the styled image for the subscriber’s next referral milestone. {{rp_next_milestone_image_styles}}
rp_next_milestone_image_url Displays the image URL for the subscriber’s next referral milestone. {{rp_next_milestone_image_url}}
rp_next_milestone_name Displays the name of the subscriber’s next referral milestone. You're close to earning {{rp_next_milestone_name}}!
rp_num_referrals Displays the number of referrals the subscriber has earned You have {{rp_num_referrals}} referrals.
rp_num_referrals_until_next_milestone Displays the number of referrals the subscriber needs to reach their next milestone. You only need {{rp_num_referrals_until_next_milestone}} more referrals to reach the next milestone.
rp_personalized_text Displays a dynamic, personalized referral progress message summarizing the subscriber’s current referral count and distance from their next reward.  Here's your referral summary: {{rp_personalized_text}}

Example: You currently have 2 referrals, only 1 away from receiving 50% off.
rp_referral_hub_url Displays the subscriber’s referral hub URL. View your referrals here: {{rp_referral_hub_url}}
rp_referral_code Displays the subscriber’s referral code. Often used with rp_referral_url to identify who is doing the referring. Your unique referral code is {{rp_referral_code}}
rp_refer_url Displays the subscriber’s referral URL. Share your referral URL! {{rp_refer_url}}
rp_refer_url_no_params Displays the subscriber’s referral URL without tracking parameters.  {{rp_refer_url_no_params}}

 
rp_refer_url_with_params Displays the subscriber’s referral URL with tracking parameters.  {{rp_refer_url_with_params}}
rp_upcoming_milestones Displays an HTML block showing upcoming milestones the subscriber has not yet earned, including reward images and referral requirements. Refer friends and get these great benefits: {{rp_upcoming_milestones}}.
Reserved fields related to podcasts

These fields pull in episode, show, and listening-platform details for a podcast episode. They're designed for use with the Podcast episode published automation trigger, where the triggering episode's details resolve automatically at send time. Podcasts must be enabled on your publication to use these fields.

Podcast reserved fields

Field Name Description Merge Tag Example
podcast.episode.title Displays the title of the podcast episode. New episode: {{podcast.episode.title}}
podcast.episode.description Displays the show notes entered for the episode. {{podcast.episode.description}}
podcast.episode.image Displays the episode's cover art. If no episode-specific art was uploaded, the show's cover art is used instead. {{podcast.episode.image}}
podcast.episode.publish_date Displays the publish date of the episode. Published on {{podcast.episode.publish_date}}
podcast.episode.duration Displays the runtime of the episode. Runtime: {{podcast.episode.duration}}
podcast.episode.audio_player Displays an embedded audio player for the episode. {{podcast.episode.audio_player}}
podcast.episode.page_button Displays a button linking to the episode's page on your beehiiv website. {{podcast.episode.page_button}}
podcast.show.name Displays the name of the show the episode belongs to. From the show: {{podcast.show.name}}
podcast.show.image Displays the show's cover art. {{podcast.show.image}}
podcast.platform.apple_url Displays the show's Apple Podcasts listening link. Listen on Apple Podcasts: {{podcast.platform.apple_url}}
podcast.platform.spotify_url Displays the show's Spotify listening link. Listen on Spotify: {{podcast.platform.spotify_url}}
podcast.platform.youtube_url Displays the show's YouTube listening link. Watch on YouTube: {{podcast.platform.youtube_url}}
Reserved fields related to analytic tracking

These fields capture subscriber acquisition and device data, such as location, browser, UTM parameters, and referral source. They are useful for advanced personalization and campaign analysis.

Analytic tracking reserved fields

Field Name Description Merge Tag Example
app_version Displays the app version used at the time of subscription (if applicable). {{app_version}}
browser Displays the subscriber’s browser type at time of acquisition. Joined via {{browser}}
city Displays the subscriber’s city at time of acquisition. Thanks for joining us from {{city}}.
country Displays the subscriber’s country at time of acquisition. Welcome to readers in {{country}}.
device_type Displays the type of device used at time of acquisition. {{device_type}}
landing_page Displays the landing page URL where the subscriber signed up (if applicable). {{landing_page}}
latitude Displays the subscriber’s latitude at time of acquisition. {{latitude}}
longitude Displays the subscriber’s longitude at time of acquisition. {{longitude}}
open_tracking_pixel Tracking pixel used internally for open tracking. System use only, not available in the post editor.
os Displays the subscriber’s operating system at time of acquisition. {{os}}
os_version Displays the subscriber’s operating system version at time of acquisition. {{os_version}}
platform Displays the subscriber’s platform at time of acquisition. {{platform}}
referrer Displays the referring URL at time of acquisition (if applicable). {{referrer}}
referring_domain Displays the referring domain at time of acquisition (if applicable). {{referring_domain}}
region Displays the subscriber’s region or state at time of acquisition. {{region}}
user_agent Displays the full user agent string collected at time of acquisition. {{user_agent}}
utm_campaign Displays the UTM campaign parameter captured at signup. {{utm_campaign}}
utm_content Displays the UTM content parameter captured at signup. {{utm_content}}
utm_medium Displays the UTM medium parameter captured at signup. {{utm_medium}}
utm_source Displays the UTM source parameter captured at signup. {{utm_source}}
utm_term Displays the UTM term parameter captured at signup. {{utm_term}}
Reserved fields used for suffixes or related to dates, times, or numbers

Some fields below beginning with an underscore (such as _mdy or _round2) are formatting suffixes. These must be appended to another merge tag — typically a custom field — to change how the value is displayed.

Other fields in this section, such as current_date_mdy, are standalone merge tags and do not require another field.

Formatting reserved fields

Field Name Description Merge Tag Example
_currency_x Formats a number field as currency using the currency code you specify. Replace x with a supported currency code. 

Supported codes: AUD, BRL, CAD, EUR, GBP, INR, MXN, NZD, USD.		 You will receive {{gift_amount_currency_USD}}

 
_currency_x_no_cents Formats a number field as currency without decimals. Replace x with a supported currency code.

Supported codes: AUD, BRL, CAD, EUR, GBP, INR, MXN, NZD, USD.		 Your total is {{salary_amount_currency_usd_no_cents}}
_dmy When used with other custom fields, displays a date formatted as dd/mm/yyyy. Your birthday is coming up on  {{birthday_date_dmy}}.
_mdy Formats a date field as mm/dd/yyyy. Your birthday is coming up on {{birthday_date_mdy}}.
_ymd Formats a date field as yyyy/mm/dd. Your birthday is coming up on {{birthday_date_ymd}}.
_dmy_dashed Formats a date field as dd-mm-yyyy. Your birthday is coming up on {{birthday_date_dmy_dashed}}.
_mdy_dashed Formats a date field as mm-dd-yyyy.  Your birthday is coming up on {{birthday_date_mdy_dashed}}.
_ymd_dashed Formats a date field as yyyy-mm-dd. Your birthday is coming up on  {{birthday_date_ymd_dashed}}.
_dmy_dotted Formats a date field as dd.mm.yyyy. Your birthday is coming up on  {{birthday_date_dmy_dotted}}.
_mdy_dotted When used with other custom fields, displays a date formatted as mm.dd.yyyy. Your birthday is coming up on  {{birthday_date_mdy_dotted}}.
_ymd_dotted Formats a date field as yyyy-mm-dd. Your birthday is coming up on  {{birthday_date_ymd_dotted}}.
_full Formats a date field as a full written date (e.g., July 14, 2025). Your birthday is coming up on {{birthday_date_full}}.
_round0 Rounds a number field to a whole number. Your score is {{average_round0}}
Ex: 2 
_round1 Rounds a number field to 1 decimal place. Your score is {{average_round1}}
Ex: 1.8
_round2 Rounds a number field to 2 decimal places. Your score is {{average_round2}}
Ex: 1.77
_round3 Rounds a number field to 3 decimal places. Your score is {{average_round3}}
Ex: 1.770
birthday_full_md Displays the subscriber’s birthday, month and day only (e.g., October 15). Your birthday is coming up on {{birthday_full_md}}.
current_date_dmy Inserts today’s date formatted as dd/mm/yyyy. This newsletter was sent on {{current_date_dmy}}.
current_date_mdy Inserts today’s date formatted as mm/dd/yyyy. This newsletter was sent on {{current_date_mdy}}.
current_date_ymd Inserts today’s date formatted as yyyy-mm-dd. This newsletter was sent on {{current_date_ymd}}.
current_date_dmy_dashed Inserts today’s date formatted as dd-mm-yyyy. This newsletter was sent on {{current_date_dmy_dashed}}.
current_date_mdy_dashed Inserts today’s date formatted as mm-dd-yyyy. This newsletter was sent on {{current_date_mdy_dashed}}.
current_date_ymd_dashed Inserts today’s date formatted as yyyy-mm-dd. This newsletter was sent on {{current_date_ymd_dashed}}.
current_date_dmy_dotted Inserts today’s date formatted as dd.mm.yyyy. This newsletter was sent on {{current_date_dmy_dotted}}.
current_date_mdy_dotted Inserts today’s date formatted as mm.dd.yyyy. This newsletter was sent on {{current_date_mdy_dotted}}.
current_date_ymd_dotted Inserts today’s date formatted as yyyy.mm.dd. This newsletter was sent on {{current_date_ymd_dotted}}.
current_date_full Inserts today’s date in a full written format (e.g., July 14, 2025). This newsletter was sent on {{current_date_full}}.
current_date_full_md Inserts today’s month and day only (e.g., October 15). The {{current_date_full_md}} edition of my newsletter.