Stripe affiliate tracking: attribute sales and pay commissions

An affiliate program needs to answer one question reliably: which affiliate brought this paying customer? Stripe already knows a payment happened. What it does not know is where the visitor came from three days earlier. Connecting the two is the entire job.

Two pieces do it. A snippet on your site remembers which affiliate link a visitor arrived through. A webhook on your Stripe account tells us when that visitor pays. Everything else — commission amounts, approval windows, payouts, invoices — follows from those two facts.

One tag, anywhere in your pages. It reads ?via=CODE from the URL, records the click, and sets a cookie:

<script src="https://earnwithaffiliate.com/snippet.js?program=your-slug" async></script>

The cookie is set on your own domain, not ours. That is what makes the attribution survive ad blockers and the end of third-party cookies: from the browser's point of view it is your site remembering its own visitor, because the script runs inside your page even though the file is served from us.

At checkout, the affiliate code has to reach Stripe. There are three routes, resolved in this order, and most merchants only ever use the second one.

• Checkout metadata — your backend reads the cookie and puts the code on the session and on subscription_data.metadata. The most explicit route, and the one that carries attribution onto renewal invoices.
• client_reference_id, with no backend code — Stripe accepts this field on a Payment Link (as a URL parameter), a Buy Button and a Pricing Table (as an HTML attribute). The snippet fills it in itself, including on elements rendered after page load.
• A tracked coupon — the fallback for when a customer used a promo code instead of clicking a link. Coupons are created in your Stripe account automatically.

The second route has one trap worth knowing about, because it is invisible when you get it wrong: client_reference_id lives only on the Checkout Session. Stripe does not copy it onto the subscription or onto later invoices. Handled naively, the first sale would be credited and then every recurring commission would silently stop. We keep the link on our side so renewals inherit the right affiliate.

You add one endpoint in your Stripe dashboard. It is specific to your account and signed with its own secret — we verify every delivery against it, so an event that did not come from your Stripe is rejected rather than trusted.

These are the events that matter, and what each one does:

• checkout.session.completed— the first sale. Creates the conversion and the affiliate's commission.
• invoice.paid — a renewal. Creates the recurring commission, inheriting the affiliate from the sale that opened the subscription.
• charge.refunded — voids the matching commission, or posts a negative adjustment if it was already paid out.
• charge.dispute.created and charge.dispute.closed — same treatment on a chargeback, and the reverse if you win the dispute.

You also give us a Stripe restricted key. It exists so tracked coupons can be created in your account and so invoices can be read back. It is deliberately narrow:

• Coupons and Promotion codes — write
• Invoices — read
• Subscriptions and Customers — read, only if you import existing subscribers

It cannot read your balance, cannot create a payment, and cannot move money. If it stops working — revoked, rotated, expired — your dashboard says so with the date and the provider's own message, instead of showing a green badge that never turns back.

The day you switch, your existing subscribers keep renewing — but those renewals arrive with no attribution, because the snippet was not on your site when they first subscribed. Left alone, the affiliates who brought those customers stop being paid on the day of the migration.

We scan your live subscriptions and reattach each one to the affiliate who brought it, wherever the proof exists on Stripe's side. Analysis and import are two separate steps: you see who we are about to credit before anything is written.