Install on Stripe
Stamp affiliate attribution onto your Stripe Checkout Sessions and Payment Links so Rekomi credits the right affiliate. Pairs with Stripe Connect, which delivers the sale events.
Stripe is Rekomi's deepest integration, and it has two halves. The sale and refund events reach Rekomi automatically once you link your account through Stripe Connect, so you do not host or configure any webhook yourself. This page is the other half: putting the referring affiliate onto each Stripe sale so Rekomi knows who to credit. Connect delivers the sale; the stamping below names the affiliate. Both are needed. Still evaluating? See Why Rekomi for Stripe →.
This page covers the three Stripe checkout shapes Rekomi supports: server-created Checkout Sessions, Payment Links, and the legacy client-redirect flow. If you have not connected your Stripe account yet, start with Stripe Connect.
Prefer to manage your program inside Stripe? The Rekomi Marketplace app lets you see referred customers, attribute sales, approve, adjust, void, or claw back commissions, issue credits, and run payouts from the Stripe Dashboard. It is a pathway to the same native tracking described here, not a separate processor, and it works alongside Stripe Connect.
How attribution works
Rekomi captures the click on the browser side via a head script that sets a first-party cookie and exposes window.Rekomi.getReferral(). When the buyer completes checkout, Stripe delivers the event to Rekomi over the Stripe Connect rail. Rekomi reads client_reference_id first (canonical across Subscription, Payment, and Setup modes), then falls back to subscription_data.metadata.rekomi_affiliate_slug if present. The matched referral closes the loop and the commission lands on the affiliate's ledger automatically. This is why stamping client_reference_id below matters: without it, Connect still delivers the sale but it has no affiliate to credit.
Refund clawback is automatic too. Stripe fires charge.refunded and customer.subscription.deleted events; Rekomi reverses the commission and updates the affiliate's pending balance the same day.
Install the head script
Paste the Rekomi head script in your site's <head> so the click cookie is set on every landing page that affiliates send traffic to.
<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>Your program ID is shown on your campaign page in the Rekomi dashboard, and in every install recipe. Once installed, window.Rekomi.getReferral() returns the affiliate slug for the current visitor (or null if no affiliate cookie is present).
Stripe Checkout (server-created Sessions)
This is the modern Stripe pattern. Your backend creates a Session and returns the URL; the browser redirects.
On the client, forward the referral to your create-session endpoint as a header:
const referral = window.Rekomi && window.Rekomi.getReferral();
const res = await fetch('/api/create-checkout-session', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-rekomi-referral': referral || '',
},
body: JSON.stringify({ priceId: 'price_xxx' }),
});
const { url } = await res.json();
window.location.href = url;On the server, attach the referral to BOTH client_reference_id and subscription_data.metadata:
const referral = req.headers['x-rekomi-referral'] || undefined;
const session = await stripe.checkout.sessions.create({
mode: 'subscription',
line_items: [{ price: priceId, quantity: 1 }],
success_url: 'https://yourdomain.com/thanks',
cancel_url: 'https://yourdomain.com/pricing',
client_reference_id: referral,
subscription_data: referral
? { metadata: { rekomi_affiliate_slug: referral } }
: undefined,
});client_reference_id is the canonical field Rekomi reads. The metadata mirror is a backup that only fires for subscription mode, so the dual attach guarantees attribution across Subscription, Payment, and Setup modes.
Stripe Payment Links
Payment Links are Stripe-hosted URLs you cannot inject server-side code into. Rekomi supports two attribution paths.
Path A: auto-stamping (recommended)
Paste this MutationObserver snippet alongside the head script. It watches the DOM for any buy.stripe.com anchor and appends ?client_reference_id=<referral> automatically. Robust against SPAs, lazy-loaded modals, and dynamically rendered Pricing Tables.
(function(){
function stamp(node){
var links = node.querySelectorAll('a[href*="buy.stripe.com"]');
var ref = window.Rekomi && window.Rekomi.getReferral();
if (!ref) return;
links.forEach(function(a){
try {
var u = new URL(a.href);
if (!u.searchParams.get('client_reference_id')) {
u.searchParams.set('client_reference_id', ref);
a.href = u.toString();
}
} catch (e) {}
});
}
document.addEventListener('DOMContentLoaded', function(){ stamp(document); });
new MutationObserver(function(muts){
muts.forEach(function(m){ m.addedNodes.forEach(function(n){
if (n.nodeType === 1) stamp(n);
}); });
}).observe(document.body, { childList: true, subtree: true });
})();Path B: coupon codes
In the Stripe dashboard, open Payment Links > [link] > Settings > After payment and toggle Allow promotion codes on. Without this toggle the ?prefilled_promo_code parameter silently no-ops at checkout.
Each affiliate gets a unique Stripe promo code minted from the campaign detail page in Rekomi. They share a link like https://buy.stripe.com/xxx?prefilled_promo_code=THEIRCODE. When the buyer completes checkout, Rekomi extracts discounts[].promotion_code from the Stripe webhook and matches it to the affiliate.
Stripe Checkout (legacy client-redirect)
Stripe deprecated the client-only stripe.redirectToCheckout flow in 2023. If you are still on it, the modern Server Session pattern above is the upgrade path. The legacy flow can still attribute by appending client_reference_id to the redirect call, but new integrations should use Server Sessions.
Troubleshooting
Sale completes but no conversion appears in Rekomi. First confirm your Stripe account is connected via Stripe Connect (the Connect payment processor step of setup, or your settings). The Connect link is what makes Rekomi receive your events; you do not set up a Stripe webhook yourself. If Connect is linked and the sale still does not appear, the sale most likely arrived without an affiliate: check that client_reference_id was stamped (the head script was present on the landing page and the affiliate link carried a slug).
client_reference_id is empty on the Session. The browser did not have an affiliate cookie at the moment of the create-session call. Check that the head script is installed on the page the affiliate sends traffic to, and that the affiliate link includes the slug query parameter (?via=, ?ref=, or one of the 16 attribution params Rekomi recognizes).
Payment Link conversions attribute to the wrong affiliate. Promotion codes are global in Stripe; if two affiliates were issued the same promo code by mistake, the most recent assignment wins. Rotate the promo code from the affected affiliate's detail page in Rekomi.
Refund did not reverse the commission. Rekomi listens to charge.refunded and customer.subscription.deleted. If your Stripe account is on a custom event configuration that excludes these, enable them in Stripe's webhook settings.
Related
- Stripe Connect (sales tracking): connect your account so Rekomi receives the sale events this page attributes
- Track leads and signups: with Stripe, free signups and trials are captured as leads automatically, no extra code
- Tracking and attribution overview
- Coupon-code attribution
- How the JS pixel works
Install tracking
Pick the platform you bill on. Each install doc covers the exact UI navigation, the specific quirks, and the conversion-fire pattern for that platform.
Stripe Marketplace app
Manage your Rekomi affiliate program from inside the Stripe Dashboard. A different entry point to the same native Stripe tracking, not a separate processor.