Install on beehiiv
beehiiv blocks per-post script tags and offers no arbitrary head HTML field, so Rekomi installs via Google Tag Manager. Premium Subscriptions then attribute through beehiiv's Stripe Connect webhook.
beehiiv intentionally does not expose an arbitrary <head> HTML slot, and per-post Custom HTML blocks strip out <script> tags by design. The only supported way to load custom JS site-wide on beehiiv is via 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 then route payments through beehiiv's Stripe Connect, so attribution flows through Rekomi's Stripe webhook rail once the click cookie is set via GTM.
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 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>
(function(){
var s=document.createElement('script');
s.src='https://js.rekomi.com/v1/rekomi.js';
s.async=true;
s.dataset.programId='YOUR_PROGRAM_ID';
document.head.appendChild(s);
})();
</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.
Your Rekomi program ID is in the Rekomi dashboard at Settings > Tracking.
How attribution works
The click cookie is set on first visit to any beehiiv-served page via the GTM-loaded Rekomi script. When a visitor upgrades to Premium Subscriptions, beehiiv processes the payment through its Stripe Connect setup and Stripe fires customer.subscription.created and invoice.payment_succeeded to Rekomi's webhook listener. Rekomi reads the cookie and credits the affiliate.
No conversion-page snippet is required for this flow. beehiiv's Premium Subscriptions route through Stripe natively.
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 only workaround. beehiiv strips <script> tags from per-post Custom HTML blocks, and the platform does not expose an arbitrary head HTML slot. GTM is the supported path; there is no shortcut.
Per-post Custom HTML blocks won't work. Don't try to install Rekomi by embedding the script in a post-level Custom HTML block. beehiiv sanitizes those blocks server-side to remove script tags. The install will silently fail.
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
Premium Subscription cancellations and refunds fire customer.subscription.deleted and charge.refunded to Rekomi's Stripe webhook listener. Commission clawback is automatic; no beehiiv-side configuration needed.
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.
Click cookie sets but conversion never fires. Premium Subscription is routed through Stripe Connect; check the Rekomi Stripe webhook listener (Settings > Tracking > Stripe webhook) shows recent events from your beehiiv-connected Stripe account.
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.
Related
Install on Ghost
Ghost Members + Stripe Connect handles the conversion fire automatically. The head script in Code Injection captures the click. Optional Handlebars block fires a backup convert on the /portal/ redirect.
Install on Kit (ConvertKit)
Kit has no site-wide head HTML slot and does not expose order data in templating, so installs are per-landing-page for click capture and server-side S2S for conversions.