How to Set Up a Stripe Affiliate Program: Complete Setup Guide
Set up a Stripe affiliate program step by step: connect Stripe, create a campaign, install tracking, pass attribution to Checkout, and test clicks through to commissions.
If you run a SaaS business, you probably use Stripe to take payments. Stripe is excellent at billing, but it has no affiliate tracking. You need a second system that records who referred each customer and keeps commissions in step with what Stripe does afterward.
A good Stripe affiliate setup does more than count clicks. It follows the subscription lifecycle: new signups, renewals, upgrades, downgrades, refunds and chargebacks. Then commissions match real revenue, and you do not reconcile a spreadsheet at month end.
This guide shows the full setup. The worked examples use Rally, but the principles apply to any affiliate platform that reads Stripe events.
What you will do:
- Connect Stripe to your affiliate platform
- Create a campaign with commission rules
- Install the tracking script
- Pass attribution data into Stripe Checkout
- Test the flow from click to commission
- Handle multiple products, coupons and refunds
Prerequisites
Before you start, make sure you have:
- A Stripe account with at least one product and price (subscription or one-time)
- Admin access to the Stripe dashboard
- A website or app where you can add one script tag
- A server route that creates Stripe Checkout Sessions (or a developer who can add one line to it)
Plan for about 45 minutes in total, including testing. If you are not technical, a developer can handle the tracking code and the Checkout change.
Understanding Stripe Integration Types
Not all "Stripe integrations" are equal. There are two common approaches.
Basic Integration (Referral Links Only)
This approach tracks clicks with cookies. You then match referrals to Stripe customers by hand.
How it works:
- Affiliate clicks are tracked with a cookie.
- When someone signs up, you note the referral source.
- You export Stripe data periodically and match it against referral records.
- You calculate commissions in a spreadsheet.
Limitations:
- Reconciliation is manual, slow and error-prone
- Upgrades and downgrades are not tracked
- Refunds need manual commission adjustments
- Affiliates cannot see their results in real time
This approach only suits a very small program or a test.
Deep Integration (Stripe Events)
This approach is what you want for a program that scales.
How it works:
- A tracking script records the click and stores attribution data in a first-party cookie.
- At checkout, you pass that attribution data to Stripe as Checkout Session metadata.
- The affiliate platform reads Stripe events and creates commission records.
- When a customer renews, changes plan, is refunded or disputes a charge, the commission follows.
Why it matters:
- Accuracy: Commissions reflect actual payments, not just signups.
- Less manual work: You do not reconcile by hand.
- Transparency: Affiliates see clicks, conversions and commissions in a portal.
- Fairness: Affiliates are not paid for customers who immediately refund.
Step-by-Step Stripe Affiliate Setup
Step 1: Create Your Affiliate Platform Account
Choose a platform with a native Stripe integration. Rally has a free plan for up to 10 active affiliates, which is enough to build and test this setup. See pricing for the details.
Create an account and verify your email address. Some actions, such as connecting Stripe and creating payouts, need a verified email address.
Step 2: Connect Stripe
In Rally, open Settings > Integrations and connect Stripe. The connection uses Stripe Connect, so you approve access on a Stripe page. You do not paste secret API keys into the affiliate platform.
Whatever platform you use, check these points:
- You can see which Stripe account is connected.
- You can revoke access from your Stripe dashboard if you need to.
- You know whether you are connecting a test or a live Stripe account.
Test mode first. Test the whole flow with Stripe's test cards before you take real payments through affiliate links.
Step 3: Know Which Stripe Events Matter
You do not set up webhooks by hand for most platforms. It still helps to know which events drive commissions, because it tells you what to test.
Rally reads these Stripe events:
checkout.session.completedcreates the initial conversion and commission.- Recurring invoices create recurring commissions.
- Subscription changes (upgrades and downgrades) adjust commissions.
- Refunds reverse the commission.
- Disputes (chargebacks) reverse the commission.
If a Checkout Session has no refhero_program_id in its metadata, Rally skips it. That is the most common reason a sale does not appear. Step 5 explains how to avoid it.
Step 4: Set Up Your First Campaign
In Rally, go to Campaigns > New campaign. A campaign holds your commission rules and attribution settings.
Fields to fill in:
- Name: For example "SaaS Affiliate Program".
- Website URL: Where referral links point, usually your homepage or pricing page.
- Commission: A percentage or a flat amount.
- Recurring commission: Optionally, pay the commission for N months.
- Attribution model: First click or last click.
- Cookie duration: In days. The default is 30.
- Payout currency and minimum payout.
- Approve new affiliates automatically: On or off.
Commission structure options:
Option 1: Percentage of the first payment. 25% of the first month on a $99 plan is $24.75. This is simple and pays out fast.
Option 2: Recurring percentage. 20% of a $99 monthly plan for 12 months is $19.80 per month, or $237.60 in total. This keeps affiliates interested in retention.
Option 3: Flat amount per conversion. $50 per paid subscription, whatever the plan. Costs are predictable.
Option 4: Hybrid. For example, a flat amount up front plus a recurring percentage. Check that your platform supports this mix before you promise it to affiliates.
For the rest of this guide, assume 25% recurring for 12 months. See the optimal commission structure for SaaS affiliate programs for how to choose.
Cookie duration. This sets how long after a click the visitor can still convert for the affiliate. A common range is 30 to 90 days. Choose a window that matches the time between a first visit and a purchase. Short sales cycles fit 30 days. Products that need a longer evaluation fit 60 or 90 days.
Attribution model. If a visitor clicks two affiliate links, one affiliate gets the credit:
- First click: the first affiliate who referred the visitor.
- Last click: the most recent affiliate.
First click rewards the affiliate who introduced your product. Last click rewards the one who closed the sale. Pick one and tell your affiliates which you chose.
Affiliate approval. Affiliates apply on the campaign signup page (/c/<slug>). Turn on automatic approval to speed things up, or leave it off to review each applicant.
Step 5: Install Tracking and Pass Attribution to Stripe
This step has two parts: the tracking script and the Checkout change.
Part 1: the tracking script. Add the tag to every page where visitors can arrive from a referral link. Place it in your main layout:
<script src="https://api.refhero.io/tracker.js" data-program="YOUR_PROGRAM_ID"></script>Use a plain tag, without async or defer. Replace YOUR_PROGRAM_ID with your campaign's program ID.
The script records the click and sets a first-party, host-only cookie for the campaign's cookie window. Referral links look like https://yoursite.com/?ref=CODE. The parameter ?via=CODE also works.
You can read the stored attribution in the browser console:
window.Rally.getAttribution();
// { visitor_id, affiliate_id, program_id } or nullThe cookie is host-only. Call the Rally functions on the same host where the script loaded. If your marketing site and your app run on different hostnames, load the tracker on the host where visitors start checkout, or pass the data across yourself.
Part 2: pass attribution to Stripe Checkout. In the browser, read the checkout metadata and send it to your server together with the request that starts checkout:
// Browser: when the visitor clicks "Subscribe"
const attribution = window.Rally ? window.Rally.getCheckoutMetadata() : {};
const res = await fetch('/api/create-checkout-session', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ priceId: 'price_123', attribution }),
});
const { url } = await res.json();
window.location.href = url;getCheckoutMetadata() returns an object like this, or {} when there is no attribution:
{
"refhero_program_id": "...",
"refhero_affiliate_id": "...",
"refhero_visitor_id": "..."
}On your server, set that object as the Checkout Session metadata:
// Server (Node, Stripe SDK)
app.post('/api/create-checkout-session', async (req, res) => {
const { priceId, attribution } = req.body;
const session = await stripe.checkout.sessions.create({
mode: 'subscription',
line_items: [{ price: priceId, quantity: 1 }],
success_url: 'https://yoursite.com/welcome',
cancel_url: 'https://yoursite.com/pricing',
metadata: attribution || {},
});
res.json({ url: session.url });
});This is the one change to your Stripe code. Without these three metadata keys, the Checkout Session is skipped and no commission is created.
Verify the installation:
- Open your site with
?ref=TESTCODEadded to the URL. - Open the browser console and run
window.Rally.getAttribution(). - Confirm that it returns an object and not
null. - Confirm that
window.Rally.getCheckoutMetadata()returns the threerefhero_keys.
Step 6: Create Affiliate Links and Coupons
Affiliates apply on your campaign signup page and then use the partner portal. The portal shows their referral link, clicks, conversions, commissions and payouts. You can also send affiliates an invite link from the Affiliates page.
Coupon attribution. Many programs pair links with discount codes. A podcast listener cannot click a link, but can type a code. In Rally:
- Create the code in your billing system, for example
JOHN20. - Map the code to the affiliate under Campaigns > Coupons.
- When a customer uses the code, report the sale with the server-side conversions API and send the code as
coupon_code. Rally credits the affiliate who owns the code, even without a click.
Rally does not read promotion codes from Stripe Checkout events yet, so coupon sales need the API call. Choose one reporting path per sale: for an API-reported coupon sale, omit Rally referral metadata from that Checkout Session so the Stripe webhook skips it. Use the Checkout Session ID as external_id and do not send a second conversion under an invoice or payment ID. Coupons are a good backup when cookies are blocked or the customer switches devices.
This API path needs your own lifecycle handling. Unlike the Stripe-tracked sales elsewhere in this guide, an API sale does not create Stripe billing references. A normal Stripe refund or dispute does not carry the Checkout Session ID, so using that ID alone does not let Rally match and reverse the commission. Keep these sales pending through your refund window; deny refunded sales while pending, and reconcile approved or paid amounts outside Rally.
For example, report a paid coupon checkout once from your server:
curl -X POST https://api.refhero.io/api/v1/track/conversion \
-H "X-API-Key: $RALLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"program_id": "YOUR_PROGRAM_ID", "external_id": "cs_example", "amount": 99, "currency": "USD", "coupon_code": "JOHN20", "customer_email": "buyer@example.com"}'For subscriptions on this manual path, leave external_subscription_id out of API requests so Stripe invoices cannot also generate renewal commissions. Store the subscription and the returned affiliate ID on your server. Report each eligible paid renewal once with that affiliate_id, customer_email, type: "recurring", and a unique sale ID. Your handler must enforce the commission term and stop after cancellation, denial or refund; the conversions API does not enforce recurring eligibility. The automatic refund and renewal steps below apply to sales recorded by the Stripe integration.
Step 7: Test the Full Flow
Test every step before you invite real affiliates.
Create a test affiliate. Add an affiliate with an email address you control. Copy their referral link.
Make a test purchase.
- Open a private browser window.
- Click the test affiliate's referral link.
- Go through your normal signup and checkout.
- Pay with the Stripe test card
4242 4242 4242 4242, any future expiry and any CVC.
Verify the conversion. Within a short time, check:
- A new conversion appears for the test affiliate.
- The commission amount matches your campaign rule.
- The commission is pending. All commissions start pending until you approve or deny them.
Test a refund.
- In the Stripe dashboard, refund the test charge.
- Check that the commission is reversed.
A commission that you already paid becomes a clawback balance. The affiliate's next payout reduces by that amount.
Test an upgrade.
- Make another test purchase through the affiliate link.
- Upgrade the test customer to a higher plan.
- Check that the commission reflects the new plan price.
- Test a downgrade too.
Test a missing-metadata case. Start a checkout without the referral cookie. It should create no commission. This confirms that unreferred sales are not credited.
Advanced Configuration
Handling Multiple Products
Most SaaS businesses sell more than one plan or add-on. A campaign has one default commission. Tiered and per-affiliate overrides exist through reward policies, so you can pay a top affiliate more than a new one.
If you want different rates for different products, create separate campaigns and pass the matching campaign attribution at checkout. Reward policies select rates by affiliate override or affiliate totals, not by Stripe product or price. Keep it simple at the start. You can add complexity once you have data.
Subscription Lifecycle Events
Upgrades. A customer starts on a $49 plan, then upgrades to a $99 plan after 2 months. With 25% recurring for 12 months:
- Months 1 and 2: $12.25 per month ($24.50 in total)
- Months 3 to 12: $24.75 per month ($247.50 in total)
- Total over 12 months: $272.00
Downgrades. The customer starts on $99 and downgrades to $49 after 4 months:
- Months 1 to 4: $24.75 per month ($99.00 in total)
- Months 5 to 12: $12.25 per month ($98.00 in total)
- Total over 12 months: $197.00
Cancellations. When a customer cancels, recurring payments stop, so recurring commissions stop. Commissions that you already approved stay valid unless the payment is refunded.
Refunds and chargebacks. State your policy in your affiliate terms. A common policy:
- A full refund reverses the full commission.
- A chargeback reverses the commission, and you should look at the account for abuse.
Hold Commissions Until the Refund Window Passes
Rally does not hold commissions on a timer. Instead, every commission starts pending, and you approve it. You can approve one at a time or in bulk.
So you can run your own holdback. If your refund window is 30 days, approve only commissions that are older than 30 days. This keeps you from paying for customers who refund fast.
Custom Attribution Windows
Match the cookie window to your sales cycle:
- 30 days: low-priced products and quick decisions.
- 60 days: mid-priced products that need a trial.
- 90 days: higher-priced products with a longer evaluation.
To choose a window from data, look at how long your customers take from first visit to purchase. Pick a window that covers most of them.
Common Setup Issues and Solutions
A Sale Does Not Appear
Symptoms: A payment succeeds in Stripe, but no conversion appears.
Checklist:
- Is the tracking script on the page where the visitor landed?
- Does
window.Rally.getAttribution()return an object, and notnull? - Does your server pass
metadatawhen it creates the Checkout Session? A missingrefhero_program_idmeans the session is skipped. - Does the Checkout Session in the Stripe dashboard show the three
refhero_metadata keys? - Is the affiliate approved? Is the campaign active when recording the referral click? Inactive campaigns reject clicks and API conversions, but Stripe webhooks do not check campaign activity.
- Did the customer use the same browser and host where the cookie was set?
- Are Stripe and your affiliate platform both in the same mode (test or live)?
Self-Referrals Are Not Credited
If the customer email equals the affiliate email, the conversion is blocked. This is expected. Use a different email when you test.
Wrong Commission Amounts
Check:
- Which amount is the commission based on: the gross price, or the price after discounts?
- Did the customer use a coupon that lowered the price?
- Is the campaign set to a percentage or to a flat amount?
- Do you have a reward policy or per-affiliate override that changes the rate?
Stripe amounts are in the smallest currency unit, such as cents. Platforms must convert correctly for each currency. Some currencies, such as JPY, have no minor unit.
Test Mode and Live Mode Confusion
Symptoms: The flow works in test mode and fails in production.
Common cause: The Stripe account connected to the affiliate platform is in a different mode than the checkout you test.
Fix:
- Confirm which Stripe account is connected.
- Confirm that the checkout uses keys from the same account and mode.
- Run one small live transaction to confirm.
Keep test and live setups separate. Do not mix them.
Best Practices for Stripe Affiliate Programs
Keep Commissions Pending Until You Are Sure
Approve commissions after the refund window. Deny any that look wrong. This gives you a simple review step, and it needs no extra setup.
Use Stripe Metadata for Reporting
Metadata on the Checkout Session also lives in Stripe. This gives you a permanent record of how a customer arrived. You can filter and export Checkout Sessions that carry refhero_affiliate_id when you audit.
Run a Monthly Reconciliation
Even with automatic tracking, do a short monthly check:
- Compare the number of affiliate conversions with the Stripe sessions that carry referral metadata.
- Spot-check 10 to 20 conversions for correct attribution.
- Check that the commission amounts match your campaign rules.
- Review denied and reversed commissions.
Pay Affiliates Outside the Platform
Rally records payouts but does not move money. Use Payouts > Create payout to group approved commissions per affiliate and currency that reach your minimum payout. Then pay the affiliate with PayPal, Wise or another method. After that, mark the payout as sent, and the affiliate gets an email. You can export payouts to CSV for your records.
If you sell in several currencies, commissions and payouts stay separate per currency.
Write Down Your Rules
Put your commission rate, cookie window, refund policy and payout method in plain words on your affiliate page. Clear rules prevent most disputes.
Illustrative Example: How Attribution Works in Principle
This sketch is illustrative pseudo-code. It is not Rally's API. It shows the idea that every Stripe affiliate system uses: carry a referral identifier from the click to the payment.
// Illustrative pseudo-code only
function onCheckoutCompleted(session) {
const referral = session.metadata.referral_id;
if (!referral) return; // no referral, no commission
if (alreadyRecorded(session.id)) return; // never count a payment twice
createPendingCommission(referral, session.amount_total);
}Conclusion
A Stripe affiliate program has three working parts. The first is a tracking script that records clicks. The second is one change in your Checkout code that passes attribution as metadata. The third is a platform that reads Stripe events and keeps commissions in step with refunds, upgrades and chargebacks.
Your checklist:
- Connect Stripe.
- Create a campaign with a commission, cookie window and attribution model.
- Add the tracking script to your site.
- Pass
window.Rally.getCheckoutMetadata()into the Checkout Session metadata. - Test a purchase, a refund and an upgrade.
- Invite your first three to five affiliates.
If your checkout runs outside Stripe Checkout, or you bill another way, Rally also has a server-side conversions endpoint. See the docs for details.
Ready to start? Read the docs for the quickstart, or see the pricing page for the free plan.
Related Resources: