Install on beehiiv

beehiiv has no site-wide head HTML field, so Rekomi installs via Google Tag Manager. A second GTM tag records subscriber emails as leads, and Premium Subscription sales on your connected Stripe attribute by email match.

beehiiv intentionally does not expose an arbitrary site-wide <head> HTML slot (per-page HTML blocks exist on website pages, but nothing covers every page at once). The supported way to load custom JS site-wide on beehiiv is Google Tag Manager: beehiiv exposes a GTM container ID field, and any tag you publish in that container runs on all beehiiv-served pages. Premium Subscriptions route payments through a Stripe account, so once GTM loads the Rekomi script for click capture and a small second tag records subscriber emails as leads, paid upgrades on your connected Stripe attribute automatically.

Prerequisites

You need a Google Tag Manager account. If you don't have one, create a free GTM container at tagmanager.google.com; you'll get a container ID that looks like GTM-XXXXXXX.

Install Rekomi via Google Tag Manager

Step 1: Add your GTM container ID to beehiiv.

In beehiiv, navigate to Website > Builder > Settings (gear icon, top-right) > All general settings > Pixels > Google Tag Manager. Paste your container ID (GTM-XXXXXXX). Save.

Step 2: Create a Custom HTML tag in GTM.

In Google Tag Manager, open your container and go to Tags > New > Tag Configuration > select Custom HTML. Paste the Rekomi head script:

<script async src="https://api.rekomi.com/api/v1/r/loader.js" data-program-id="YOUR_PROGRAM_ID"></script>

Step 3: Set the trigger to fire on every page.

Under Triggering, select All Pages. This ensures Rekomi loads on every beehiiv-rendered page (newsletter posts, paid landing pages, the homepage).

Step 4: Publish the container.

In GTM, click Submit (top-right) > Give the version a name like "Rekomi install" > Publish. GTM is live within seconds; beehiiv pages will start loading Rekomi on the next page load.

Copy the snippet with your program ID already filled in from Setup > Install in Rekomi.

How attribution works

The GTM-loaded Rekomi script captures the affiliate click on first visit to any beehiiv-served page. When a visitor upgrades to Premium Subscriptions, the payment runs through Stripe and Stripe fires customer.subscription.created and invoice.paid to Rekomi's webhook listener, recording the sale.

Naming the affiliate takes one more piece. beehiiv's checkout cannot carry Rekomi metadata or coupon codes, so Rekomi attributes the sale by matching the buyer's email against a lead recorded in the last 90 days. Record the lead with a second Custom HTML tag in the same GTM container (trigger: All Pages), which captures the email whenever a visitor submits a subscribe form:

<script>
  document.addEventListener("submit", function (e) {
    var form = e.target;
    if (!form || !form.querySelector || !window.Rekomi) return;
    var input = form.querySelector('input[type="email"]');
    if (input && input.value) window.Rekomi.convert({ email: input.value });
  }, true);
</script>

With the lead recorded at signup, the paid upgrade attributes automatically whenever it happens within the 90-day window, and returning customers keep crediting the same affiliate on renewals.

One prerequisite to check: the Stripe account beehiiv bills through must be connected to Rekomi. beehiiv sets up that Stripe account through its own onboarding; if you can sign in to the full Stripe Dashboard for it, connect that same account under Setup > Connect payment gateway. If your beehiiv plan runs on a managed Stripe account you cannot open the full dashboard for, the Stripe rail is not connectable; run a lead-based program instead (see Lead tracking).

beehiiv Boost vs Premium Subscriptions vs Referral Program

beehiiv has three monetization features that are easy to confuse. Rekomi tracks one of them; the other two are separate products.

Premium Subscriptions (Rekomi tracks this). Paid newsletter subscriptions routed through beehiiv's Stripe Connect. Attribution works as described above.

beehiiv Boost (Rekomi does NOT track this). Boost is beehiiv's ad-network where one publisher pays another for newsletter recommendations. Boost spend is Merchant-of-Record through beehiiv (beehiiv collects from the buyer, remits to the recommender after a cut). Boost is NOT attributable through Rekomi by design; affiliates can't commission Boost spend.

Native Referral Program (Rekomi does NOT track this; runs in parallel). beehiiv has a built-in referral feature where readers refer friends in exchange for rewards (t-shirts at milestones, swag, etc.). This is a free-newsletter growth tool, NOT an affiliate revenue-share. It does not conflict with Rekomi; both can run on the same publication. Rekomi commissions paid Premium Subscriptions; the native Referral Program rewards free signups with merchandise.

Quirks worth knowing

GTM is the site-wide path. beehiiv's HTML blocks can carry a script on an individual website page, but nothing covers every page (and newsletter posts strip scripts), so a per-page paste leaves most affiliate landings untracked. Use GTM for the site-wide install; treat per-page HTML blocks as a spot fix at most.

GTM container ID is per-publication, not per-account. If you run multiple beehiiv publications and want Rekomi on all of them, paste the same GTM container ID into each publication's settings.

Test in GTM preview mode first. GTM's Preview mode (the Preview button at the top of the container) lets you load your beehiiv site with the unpublished version of the container active. Use this to verify the Rekomi script actually loads before publishing the container to production.

The GTM container ID is not a Rekomi credential. You're configuring beehiiv to load YOUR Google Tag Manager container; Rekomi has nothing to do with the GTM container itself. GTM is the delivery mechanism; the Custom HTML tag inside GTM is what loads Rekomi.

Refunds

When a Premium Subscription payment is refunded, Stripe fires charge.refunded and the commission claws back automatically. A cancellation (customer.subscription.deleted) stops future renewal commissions but does not claw back commission already earned. No beehiiv-side configuration needed for either.

Troubleshooting

Rekomi script does not load on beehiiv pages. Check three things in order: GTM container ID is correctly pasted in beehiiv Settings > Pixels; the Custom HTML tag in GTM has its trigger set to "All Pages" (not just specific pages); GTM container is published (not just saved as a draft). The most common cause is forgetting to hit Publish in GTM.

Clicks record but conversions never land. Confirm the beehiiv Stripe account is connected in Rekomi under Setup > Connect payment gateway, then check the Sales page: a sale with no affiliate means the lead-capture tag is missing or not firing (see "How attribution works" above); no sale at all means the Stripe connection is the problem.

Boost spend appears in beehiiv but not in Rekomi. Expected. Boost is not attributable through Rekomi by design (see "beehiiv Boost vs Premium Subscriptions vs Referral Program" above).

Native Referral Program signups conflict with affiliate referrals. They don't; they're separate. The native Referral Program rewards free signups with merchandise (read-side growth). Rekomi commissions paid Premium Subscription upgrades. A single reader can refer free signups for swag AND drive paid affiliate revenue through Rekomi simultaneously.

On this page