Updated: Apr 22, 2026
How to create a custom referral section in a post
Available on paid beehiiv plans. Click here to upgrade your account.
The referral program is a powerful way to organically market to engaged audiences by offering rewards to subscribers who refer others to your newsletter. You can create a custom dynamic referral section to include in your posts with unique referral links, encouraging your subscribers to keep spreading the word.
We’ll start with some quick tips on the program basics, including a few key glossary terms and a list of the custom fields that are reserved for referral program merge tags. Next, you'll find a video tutorial on customizing your referral section/widget along with step-by-step examples of the possibilities available to you.
Quick tips to get you started
- Set up your referral program: Before creating a custom referral section in a post, ensure the referral program is set up for your subscribers. Learn how to set up a referral program on beehiiv.
- Use custom fields for personalization: To fully customize your referral widget with details like your subscriber’s name, make sure custom fields are set up for your subscribers. Read more about setting up custom fields in this article.
- Leverage merge tags: From your custom fields, you can create merge tags to dynamically add subscriber information to your posts. Learn how to personalize your posts using merge tags.
- Reserved custom fields: Some custom fields are reserved to be used as merge tags for the referral program (listed below) and other beehiiv tools. Check the full list of reserved fields.
Important glossary terms
- Referrals: Subscribers who sign up for your newsletter through a referral link associated with your beehiiv publication.
- Milestones: The number of referrals required to unlock a specific reward.
- Rewards: The gifts your subscribers receive when they reach a milestone.
Merge tags used for referral widget personalization
You can add these referral program merge tags to personalize your referral widget and make it dynamic for your subscribers.
- {{ rp_refer_url }} Their personal referral link they should share with others.
- {{ rp_referral_hub_url }} Their personal link to the referral hub to view their progress and rewards.
- {{ rp_num_referrals }} Number of referrals.
- {{ rp_num_referrals_until_next_milestone }} Number of referrals until the next milestone.
- {{ rp_next_milestone_name }} Next milestone name.
- {{rp_personalized_text}} How many referrals they have and how close they are to the next milestone.
Here’s an example of how these merge tags will appear in the post editor:
And here’s how the merge tags will render for the subscriber:
Watch and learn: How to create a custom referral widget/section in beehiiv
Disclaimer:
The beehiiv platform has evolved since the filming of this video, parts of
the user interface featured in the video will be slightly different than what
you see in your account.
How to create a custom referral section in a post
Creating a custom referral section allows you to engage your subscribers with personalized content and encourage them to refer your newsletter to others.
- Open a saved post to edit, or click + New in the left panel to create a new post.
- Type /ref to access the post editor, under Premium, select the Referral Program.
- A referral section will appear in your post with default settings. To adjust the look of the button, access the Style panel on the right, then open the Advanced options and go to Widgets > Button.
- To add a header above the widget, such as ‘Earn free gifts.’ Enter the header and then highlight the text to select a header size from the dropdown menu (e.g., H1).
- You can add an emoji for visual interest in your header text. To do this, type : to bring up the emoji menu and type a description of the emoji you want. For this example, we used :gift to select from the gift emoji options.
- Add copy to include a brief description that explains your referral program and the rewards subscribers can earn.
- You can also add an image to show the rewards that your subscribers receive. Type /image to select an image to add to the post.
Note:
You may need to create custom images (e.g., with Canva or Photoshop) if you want
an image that specifically displays your reward tiers.
- Once added, adjust the image as needed in the post editor.
- Make the referral section dynamic by inserting merge tags. Type {{ on the post canvas to bring up the merge tag options. Use {{rp_personalized_text}} to show the subscriber’s progress towards the next milestone.
- You can also use use {{ rp_refer_url }} to share their unique referral link. Highlight the referral URL text and click the link icon to hyperlink the text.
- Paste {{rp_refer_url}} in as the link address. Click the check mark icon to save.
- You can group and style the elements of your referral section. Highlight the elements and click the 6 dots menu on the left, then select Group to section. This allows you to modify the section as a single unit.
- Also from the 6 dots menu, you can go to Visual settings to adjust design elements such as background colors, text colors, borders, and line spacing.
- Before publishing, click Preview to see how everything will look and function in your post.
Was this article helpful?
Related Articles