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 Ad Network campaigns.

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 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 related to the Ad Network

These fields are primarily used within Ad Network campaigns and tracking workflows. They dynamically insert campaign, creative, or payout information into sponsored content.

Ad Network reserved fields

Field Name	Description	Merge Tag Example
ad_network_advertisement_id	Unique identifier for the specific ad creative.	Creative ID: {{ad_network_advertisement_id}}
ad_network_advertisement_kind	Identifies the type of creative (e.g., Primary or Secondary).	Creative type: {{ad_network_advertisement_kind}}
ad_network_advertisement_name	Displays the name of the advertisement or campaign creative.	Creative name: {{ad_network_advertisement_name}}
ad_network_campaign_id	Unique identifier assigned to an ad campaign.	Campaign ID: {{ad_network_campaign_id}}
ad_network_campaign_name	Displays the name of the ad campaign.	Campaign name: {{ad_network_campaign_name}}
ad_network_payout_type	Indicates the payout model for the campaign (e.g., CPC or CPM).	Payout type: {{ad_network_payout_type}}
current_date_mdy	Inserts the current date as mm/dd/yyyy (useful for ad reporting or campaign metadata).	Date of open: {{current_date_mdy}}
email_address_id	Unique email address identifier used for tracking or URL parameters.	https://www.example.com?email_address_id={{email_address_id}}
publication_alphanumeric_id	Unique alphanumeric publisher ID assigned to the publication. (Required)	Publisher ID: {{publication_alphanumeric_id}}
publication_name_param	URL-safe version of the publication name used for tracking parameters.	https://example.com?pub={{publication_name_param}}
resource_id	Unique identifier for the specific post or resource.	Post ID: https://example.com/post?id={{resource_id}}

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
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.