Install on beehiiv

On beehiiv, attribution does not depend on a script in the reader's browser: readers who subscribe on your site are credited through beehiiv's own record, and readers who go straight to the paid checkout are credited through the checkout door below. beehiiv itself records how every subscriber arrived, and every affiliate link Rekomi hands out carries a tag beehiiv stores at signup. When a subscriber later pays for a Premium Subscription, Rekomi reads that record back and credits the affiliate. The whole install is two connections in Rekomi and nothing on beehiiv's side. A Google Tag Manager tag is optional: it adds click counts and covers the one case the record cannot (readers who were already on your list before they clicked).

Step 1: Connect the Stripe account beehiiv bills through

beehiiv bills Premium Subscriptions through a Standard Stripe account it creates under your own Stripe login, separate from any other Stripe account you run. That is the account that sends Rekomi the sale, so it is the one to connect.

1. In Rekomi, open Setup > Connect payment gateway and click Connect Stripe.
2. In Stripe's consent screen, pick the account beehiiv created for your publication. If you sign in to Stripe and see more than one account, it is the one whose payments are your newsletter subscriptions.
3. Approve the Rekomi app. Sales and refunds from that account now reach Rekomi.

If your beehiiv plan runs on a managed Stripe account you cannot open the full Stripe Dashboard for, the Stripe rail is not connectable; run a lead-based program instead (see Lead tracking).

Step 2: Connect beehiiv under Integrations

1. In Rekomi, open Integrations, click the beehiiv card, and paste your beehiiv API key and Publication ID (both under Settings → Integrations → API Keys in beehiiv).
2. Click Connect. Rekomi verifies the key and checks that it can look subscribers up.
3. Leave Credit sales through beehiiv on. It is on from the moment you connect. Sync affiliates into beehiiv is the other switch on the same page and adds your approved affiliates to the publication; keep or turn it off as you like.

That is the install. The beehiiv CRM page covers the switch, the status line, the signup alerts and the limits in detail.

Test it

1. Sign in as one of your affiliates (or use a test affiliate) and copy their link. It looks like https://newsletter.example.com?via=jane&utm_source=rekomi&utm_campaign=jane: the last two parameters are the tag beehiiv stores.
2. Open the link in a private window and subscribe with a fresh email address.
3. Back on the beehiiv integration page in Rekomi, enter that address under Check a subscriber's email. It should say the subscriber exists, the tag names your affiliate, and a sale from that email would be credited.
4. Upgrade with that address on your beehiiv site. The purchase appears in the campaign's Activity view as a credited sale, with beehiiv as the source.

How attribution works

1. Every affiliate link Rekomi generates for your campaign carries utm_source=rekomi and utm_campaign set to the affiliate's link slug, on top of the usual ?via= parameter.
2. When a reader lands on your beehiiv site from that link and subscribes, beehiiv stores those values on the subscriber. It writes them once, at signup, and never overwrites them.
3. When the subscriber upgrades to a Premium Subscription, the payment runs through the connected Stripe account and Stripe fires customer.subscription.created and invoice.paid to Rekomi, recording the sale. One-time digital products sold through the same account are not recorded yet; they will be, the same way, once the Rekomi app for Stripe update is live.
4. Rekomi first tries everything it already knows about the sale (a coupon, checkout metadata, the customer's history, an email lead it recorded itself). Only when none of those names an affiliate does it ask beehiiv for the subscriber by email and credit the affiliate the stored tag names. An upgrade started while the reader is logged in is credited the same way, because nothing needs to be typed.
5. Renewals keep crediting the same affiliate through the customer's history, and refunds claw back automatically (see below).

The one case this cannot cover: a reader who was already on your free list before they clicked an affiliate link. beehiiv already has an arrival record for them and does not replace it. The optional click-stats tag below records a lead the moment such a reader types their email anywhere on your site after the click, and that lead credits the sale by email match within 90 days.

Readers who go straight to the paid checkout: the checkout door

beehiiv writes the affiliate tag only when a reader types their email into a subscribe form on your site. A reader who lands on your upgrade page from an affiliate link, picks a plan, enters their email in beehiiv's Confirm your email box and pays on Stripe is created on beehiiv's servers with no tag, and beehiiv does not copy the visit onto that subscriber. With the cookie banner on, beehiiv also loads Google Tag Manager only from the next page load after Accept, so no script can see that first page either. The checkout door covers exactly this reader, with nothing running on beehiiv at all.

Turn it on in the campaign's settings, Tracking tab, "Track sales through a Rekomi link". Two things change:

1. Every affiliate link becomes https://rekomi.link/{code}?p={campaign}. The click is recorded on Rekomi's side, a cookie is set on rekomi.link, and the reader is sent straight on to your page with the affiliate's code and the tag, exactly as before. Links to a specific page keep working: the link maker and the product links go through the same hop.
2. In beehiiv, under Settings, Paid subscriptions, set the redirect after purchase to the URL the settings page shows you: https://rekomi.link/thanks?p={campaign}&session_id={CHECKOUT_SESSION_ID}. Keep the curly braces exactly as they are; Stripe fills in the session id when it sends the buyer back. That page reads the cookie and the Stripe session on your connected account, records the buyer, credits the sale (whether Stripe told us first or the buyer's browser did), shows a short thank-you and sends the buyer on to your page or the thank-you page you set.

If beehiiv refuses to save the braces, switch the link mode to "Ask for the email first". Readers then see a one-field Rekomi page before your upgrade page; Rekomi records them and writes the affiliate tag onto their beehiiv subscriber record through your beehiiv connection, so the purchase credits through the connection itself. The reader types the same email in beehiiv's box a moment later, and beehiiv links the payment to that record.

Without a session id and without the email step, the thank-you page still credits a purchase when it is the only unattributed sale from your account in the last five minutes and no other buyer came back in that window; anything ambiguous is left uncredited rather than guessed.

Renewals credit through the customer's history once the first payment is credited. Refunds reverse the commission as on every other rail.

Optional: click stats with Google Tag Manager

You do not need this for sales to credit. Add it if you want click counts in the dashboard, or to cover readers who were already subscribed before they clicked.

beehiiv does not expose a site-wide <head> HTML slot (per-page HTML blocks exist on website pages, but nothing covers every page at once, and newsletter posts strip scripts). 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. You need a Google Tag Manager account; a free container at tagmanager.google.com gives you an ID that looks like GTM-XXXXXXX.

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

Create a Custom HTML tag in GTM. Open your container and go to Tags > New > Tag Configuration > Custom HTML. Paste the Rekomi script:

<script async src="https://api.rekomi.com/api/v1/r/loader.js?program=YOUR_PROGRAM_ID&capture=auto"></script>

The settings ride on the URL on purpose. Google Tag Manager rebuilds a script tag when it injects it and keeps only the address, so anything written as a data- attribute (for example data-program-id) is silently dropped. Putting the program id and capture=auto in the URL survives that. Copy the snippet with your program ID already filled in from Setup > Install in Rekomi.

Rekomi records an email a referred visitor types into any email or text field on the pages where the tag runs (signup, login, checkout and other forms) so the sale can be credited even when the checkout passes no referral. Nothing is recorded without a referral. Remove capture=auto from the address to turn this off; explicit Rekomi.convert() calls still work.

Set the trigger to All Pages and publish. Under Triggering, select All Pages. Then click Submit (top-right), name the version, and Publish. beehiiv pages start loading Rekomi on the next page load.

Your cookie banner gates every tag. With beehiiv's cookie banner switched on, Google Tag Manager (and with it Rekomi, Meta, GA4 and every other pixel) does not load until the reader clicks Accept, and only from the next page load. Readers who decline or ignore the banner are not counted by anything. That only affects this optional tag; sales credit through the connection regardless of the banner.

If you installed a separate "lead capture" Custom HTML tag from an earlier version of this page, delete it; the capture=auto setting replaces it.

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

Only beehiiv-hosted pages store the tag. A beehiiv subscribe form embedded on another website does not record the arrival unless beehiiv's own attribution script runs on that page. Send affiliate traffic to your beehiiv site itself.

The tag is written once. beehiiv keeps the first arrival record and never overwrites it, which is why a reader who subscribed before clicking is the one case the connection cannot credit.

Signup alerts need beehiiv Scale or above. With Credit sales on, Rekomi registers a webhook so tagged signups appear as leads before any sale. beehiiv offers webhooks on Scale and above; on other plans the integration page shows one line under the sales status saying so, and sales still credit.

GTM container ID is per-publication, not per-account. If you add the optional tag and run multiple beehiiv publications, paste the same GTM container ID into each publication's settings.

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.

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

A test purchase shows as a purchase but not as a credited sale. Enter the buyer's address under Check a subscriber's email on the beehiiv integration page. If beehiiv has no subscriber for it, the reader paid before subscribing or subscribed on a page that is not beehiiv-hosted. If the subscriber exists but carries no tag, they were on your list before the click; the optional tag above covers that case. If the tag is there and the sale still did not credit, check that the Stripe account connected under Setup > Connect payment gateway is the one beehiiv bills through, and that Credit sales through beehiiv is on.

Purchases never appear at all. The connected Stripe account is not the one beehiiv bills through. Reconnect under Setup > Connect payment gateway and pick the account beehiiv created for your publication.

The optional tag does not load on beehiiv pages. Check three things in order: the GTM container ID is correctly pasted in beehiiv Settings > Pixels; the Custom HTML tag in GTM has its trigger set to "All Pages"; the GTM container is published (not just saved as a draft). The most common cause is forgetting to hit Publish in GTM. Test in GTM's Preview mode first, and remember the cookie banner: click Accept, then reload.

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

• beehiiv CRM connection: the two switches, the status line, signup alerts and limits
• No-code and non-Stripe checkout tracking
• Tracking and attribution overview
• Google Tag Manager docs