How to create a custom referral widget

The beehiiv 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 widget to include in your posts with unique referral links, encouraging your subscribers to keep spreading the word.

We’ll start with some quick tips to help you get started, including a few key glossary terms and a list of the custom fields that are reserved for Referral Program merge tags. Then, we’ll guide you through a video tutorial on widget creation and provide a step-by-step walkthrough of an example widget to showcase the possibilities available to you.

Quick tips to get you started

• Set up your Referral Program: Before creating a custom referral widget, ensure your 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 editor:

 

 

And here’s how the merge tags will render for the subscriber:

 

---

Watch and learn: How to Create a CUSTOM Referral Widget in beehiiv

---

How to create a custom referral widget 

Creating a custom referral widget allows you to engage your subscribers with personalized content and encourage them to refer your newsletter to others.

1. From the left panel Dashboard, click Start writing or open a saved post to edit.
   
   
   
   
   
   
2. Type /ref to access the post editor, under Premium, select the Referral Program. 
   
   
   
   
   
   
3. Your referral widget will appear in your post with default settings. From here you can customize the look of your referral widget as you wish.
   
   
   
   
   
   
4. To add a header above the widget, such as ‘Earn free gifts.’ Highlight the text and select a header size from the dropdown menu (e.g., H1).
   
   
   
   
   
   
5. 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.
   
   
   
   
   
   
6. Enter a brief description explaining your referral program and the rewards subscribers can earn.
   
   
   
   
   
   

7. You can also add an image to show the rewards that your subscribers receive. Type /image to select an image to add to the widget.

   Note: You may need to create custom images (e.g., with Canva or Photoshop) if you want an image that displays your reward tiers.
   
   
   
   
8. Your image will appear in the widget and be visible in the post editor.
   
   
   
   
   
   
9. Make your widget dynamic by inserting merge tags. You can type {{rp_personalized_text}} to show the subscriber’s progress towards the next milestone.
   
   
   
   
   
   
10. Type {{ rp_refer_url }} to share their unique referral link. Highlight the referral URL text and click the link icon to hyperlink the text.
    
    
    
    
    
    
11. Paste {{rp_refer_url}} in as the link address. Click the check mark icon to save.
    
    
    
    
    
    
12. Or, you can create a button from this URL. To do so, grab a button from the post editor, by clicking Button.
    
    
    
    
    
    
13. You’ll need to select a button preset, click Custom.
    
    
    
    
    
    
14. Paste {{rp_refer_url}} in as the link.
    
    
    
    
    
    
15. Customize the button text to something like Refer a friend. Click the check mark icon to save.
    
    
    
    
    
    
16. You can group and style the widget. Highlight all elements of the widget and click the 6-dots icon on the left, then select Group to section. This allows you to modify the widget as a single unit.
    
    
    
    
    
    
17. Go to Visual settings to adjust design elements such as background colors, text colors, borders, and line spacing.
    
    
    
    
    
    
18. Before publishing, click Preview to see how your widget will look and function in your post.
    

---