How to run a Stripe affiliate program, from click to payout

A Stripe affiliate program comes down to four jobs: capture the referral when someone clicks, carry the affiliate's ID into Stripe Checkout or onto the subscription, create commission from money Stripe has collected (invoice.paid for Stripe Billing subscriptions), and take it back when a charge is refunded.

Stripe stores the payment, but nothing on a charge says who sent the customer.

What Stripe records and where an affiliate ID can live

Stripe gives you three places to attach a referral. A Checkout Session takes a client_reference_id. Payment Links, Buy Buttons and pricing tables accept the same value as a URL parameter or an HTML attribute.

Customers, subscriptions and PaymentIntents take metadata, which Stripe's metadata guide caps at 50 key-value pairs, with keys up to 40 characters and values up to 500.

The same guide says metadata does not copy automatically between related objects, with four exceptions, so an ID set on the wrong object never arrives on the invoice you will pay commission on.

How to set up a Stripe affiliate program in 9 steps

Step 1: Set the terms your Stripe data has to support

Four numbers decide what the rest of the setup must record: the commission rate, how long renewals keep earning it, the hold before commission becomes payable, and the click-to-purchase window.

The affiliate benchmark tables list 20% for 12 months as the median B2B SaaS program and 60 days as the median cookie window.

Write the commission base into the terms as well: the invoice amount after discounts and before tax.

Step 2: Capture the click on your own domain

Set the referral cookie from your server, on your own domain.

WebKit documents that Intelligent Tracking Prevention deletes cookies created in JavaScript after 7 days without user interaction, so a 60-day window written by a script shrinks to a week for Safari visitors who do not return.

A cookie on your domain is also invisible on buy.stripe.com, so the ID has to travel in the URL or through your checkout code. The cookie side has its own guide: affiliate tracking without third-party cookies.

Step 3: Pass the affiliate ID into Stripe

When your server creates the Checkout Session, read the cookie and set two fields in one call. client_reference_id labels the Checkout Session. subscription_data.metadata writes the ID onto the subscription Stripe creates, which is what lets renewals find their affiliate.

1// aff_id was set when the visitor clicked the affiliate link2const affiliateId = (await cookies()).get("aff_id")?.value;3 4const session = await stripe.checkout.sessions.create({5  mode: "subscription",6  line_items: [{ price: "price_123", quantity: 1 }],7  client_reference_id: affiliateId,8  subscription_data: { metadata: { affiliate_id: affiliateId } },9  success_url: "https://example.com/welcome",10});

For a Payment Link, append ?client_reference_id= and the affiliate's ID to the URL, and Stripe sends the value in checkout.session.completed after payment. Pricing tables and Buy Buttons take a client-reference-id attribute.

A link-level subscription_data.metadata is set once when you create the link, so it names an affiliate only if you create one Payment Link per affiliate through the API. Stripe Payment Links attribution covers that flow.

A podcast read has no clickable link, so give that affiliate a promotion code. Stripe's Promotion Code object has a metadata field and a max_redemptions limit, so one code per affiliate can name its owner and cap its use.

Coupon code tracking for affiliate programs covers the rest.

Step 4: Make the ID survive to renewals

A Payment Link or Buy Button puts the ID on the Checkout Session only, so the month-2 invoice arrives with no trace of the referral.

Close the gap in your checkout.session.completed handler by writing the ID to the subscription and the customer.

1const session = event.data.object;2const affiliateId = session.client_reference_id;3 4if (affiliateId && session.subscription) {5  await stripe.subscriptions.update(session.subscription, {6    metadata: { affiliate_id: affiliateId },7  });8}9if (affiliateId && session.customer) {10  await stripe.customers.update(session.customer, {11    metadata: { affiliate_id: affiliateId },12  });13}

Stripe's webhook guide says not to depend on event order, so the first invoice.paid can arrive before this write lands. For an invoice with a billing_reason of subscription_create, list the Checkout Sessions with a subscription filter and read client_reference_id there.

For later invoices, check parent.subscription_details.metadata, then the subscription, then the customer.

Step 5: Create commission from collected money

Create the commission for a subscription on invoice.paid, which Stripe's subscription webhook guide describes as sent when an invoice is successfully paid.

Skip any invoice with an amount_paid of 0, and use the invoice ID as the commission row's unique key so a replayed event changes nothing.

Verify the signature and return a 2xx before slow work. Stripe's webhook documentation says failed deliveries are retried for up to three days in live mode and the same event can arrive twice, so log event IDs.

Then choose one amount per invoice and keep to it. total_excluding_tax is the invoice total after discounts and before tax; subtotal is before invoice-level discounts. Take a $49.00 plan billed to a customer in Germany with 19% VAT added.

Commission on the VAT-inclusive total overpays by the tax rate on every renewal.

Step 6: Follow upgrades, downgrades and cancellations

Commission follows invoices, so most plan changes need no special code: an upgrade makes the next invoice larger and a cancellation stops invoices. What needs a rule is the recurring window.

Count paid invoices per subscription using billing_reason (subscription_create for the first, subscription_cycle for each renewal, subscription_update for a mid-cycle change) and stop at your term.

Decide whether proration invoices earn commission, and whether the term counts months or invoices; annual plans make that difference visible.

Step 7: Reverse refunds and hold for chargebacks

Stripe sends charge.refunded for every refund, partial ones included. Recompute the commission from the charge's cumulative refunded amount so a replayed event cannot subtract twice.

If the original commission was already paid, carry the difference as a negative balance on the next payout; the refunds and upgrades guide walks through the ledger states.

Step 8: Pay the affiliates

Stripe settles your customers' payments to you. Getting part of that money to affiliates is a separate job, and the rails differ in reach and cost.

Stripe Connect pays out of your own Stripe balance: Stripe's separate charges and transfers guide says a transfer fails when it exceeds your available balance, with no automatic retry.

Transfers cross borders only between the US, Canada, the UK, the EEA and Switzerland. Stripe's docs now call Standard, Express and Custom accounts legacy and model a payee as a v2 Account with a recipient configuration.

Stripe restricts transfers to permitted use cases, and its cross-border payouts page lists affiliate payouts under Global Payouts, so ask Stripe whether your program fits before you build.

For a first program I would start with the CSV route: Stripe Connect's $2 monthly account fee alone is 1.3% of a $150 payout, and every affiliate must finish Stripe onboarding.

Collect a W-9 or W-8 before the first payout on any rail; how to pay affiliates covers methods and tax forms.

Step 9: Test the whole path with test clocks

Stripe's test clocks (called simulations in the current docs) move a test subscription through time, so a month-2 renewal takes minutes.

Run one referred customer through a payment, a renewal, an upgrade, a partial refund and a cancellation, then compare the ledger with the invoice list.

Repeat with a Payment Link and an API-created Checkout Session, which take different paths through steps 3 and 4, and run an unreferred customer to confirm nothing is paid.

Build it yourself or use an affiliate tool

Steps 3 to 7 stay yours to maintain while the program runs: event order, replays, disputes and payout files all land on you.

A tool connects to Stripe, reads the same events and runs the ledger, and those steps are the checklist for judging one: how it finds the affiliate on a renewal, what it pays on, and what it does with a partial refund.

Entry plans differ on what they cap and how they pay.

Caps are measured differently. The first four cap affiliate-driven revenue; TrackRev caps the commission it tracks, so at a 20% rate $10,000 of commission corresponds to $50,000 of affiliate revenue.

The full comparison is in best affiliate software for Stripe in 2026.

How TrackRev handles the Stripe side

TrackRev connects with a restricted Stripe key and syncs paid charges hourly; an optional webhook cuts the delay to seconds. It never writes metadata onto your customers or subscriptions, which removes step 4.

Its pixel sets a first-party visitor ID and adds it as client_reference_id to Payment Links, Buy Buttons and pricing tables on your pages; for Checkout Sessions you create, pass it as client_reference_id or metadata.vid.

Without either, it matches the customer's email, and renewals inherit the affiliate from the first charge on the subscription.

Per program you set a percentage or flat amount, first sale only or renewals too, a 60-day click window by default, a hold of 0 to 180 days (default 0) and a payout schedule from weekly to quarterly.

Paying means exporting a PayPal or Wise CSV and marking each payout paid.

Against the build above, TrackRev reads charges, so the base is the charge amount, including any tax Stripe collected. Any refund, partial ones too, reverses that charge's whole commission with no proration. The program needs a paid plan.

Pick Tolt (Growth, $99) when automatic payouts with 1099 filing matter more than the entry price, PromoteKit when Stripe is your only billing system and price decides it, and TrackRev when the affiliate program should sit beside link tracking and channel attribution on one data model.

The affiliate program page lists what partners see in their portal.