Stripe affiliate tracking: how referral attribution works end to end

The chain from click to commission

Stripe knows who paid and how much, but it has no idea which partner sent that customer. Affiliate tracking is the job of carrying one small piece of information, the partner’s referral code, from the moment someone clicks a link to the moment Stripe records a payment. Every tracking tool does some version of these five steps:

1. 1

   Click

   A visitor follows a partner link such as example.com/?ref=JANE. A script on your site reads the code and records the click.

2. 2

   Store

   The script saves the code in a first-party cookie so it survives the visitor browsing around, leaving and coming back within the attribution window.

3. 3

   Sign up

   When the visitor creates an account, the stored code is linked to their user id in your app.

4. 4

   Link to Stripe

   At checkout, your server attaches the code and the user id to the Stripe Checkout Session, customer or subscription.

5. 5

   Pay

   Stripe sends webhooks for each paid invoice and refund. The tracking tool looks up which partner owns that customer and creates or reverses a commission.

If any link in this chain breaks, the payment still goes through, but the partner is not credited. Most “my referral wasn’t tracked” complaints come from step 4, where the code never reaches Stripe.

Cookies and the attribution window

The attribution window is how long after a click a sign-up still counts for the partner. Thirty days is the most common default for SaaS, and 60 or 90 days is typical for products with long evaluation cycles. The window only needs to cover the time between click and sign-up; once the customer is linked to a partner, recurring commissions follow the customer, not the cookie.

Two rules decide who wins when several partners are involved. Last click credits the most recent link a visitor followed before signing up. First click credits whoever reached them first. Whichever you choose, the common practice is to lock attribution once a customer exists, so that a later click on another partner’s link does not move an existing paying customer. See affiliate attribution and cookie duration for the trade-offs.

Linking the Stripe customer to the partner

Stripe gives you two places to carry the referral: client_reference_id and metadata. They do different jobs, and a robust setup uses both.

The subscription metadata matters most. A Checkout Session happens once, but invoices keep arriving for months, and each invoice webhook includes the subscription’s metadata. Putting the code there means every renewal can be attributed without a lookup.

The browser side is simple: read the stored code from the tracking script and send it to your server along with the checkout request. The server then creates the session with client_reference_id set to your user id, the code in metadata, and the same values in subscription_data.metadata. Never trust a code for anything beyond attribution; it is a label, not a credential.

In Affiliatops this is how the Stripe integration works: the tracker keeps the code in a first-party cookie for the program’s attribution window (30 days by default), the first code that resolves to an active partner owns the customer, and the integration reads the affiliatops_ref and affiliatops_customer_id metadata keys from Stripe’s webhooks. The integration is webhook-only, so it never needs a Stripe API key. The exact checkout snippet is in the docs.

The Stripe webhooks that create commissions

Webhooks are what make recurring commissions automatic. You add an endpoint in the Stripe dashboard, choose the events to send, and the tracking tool verifies each request with the endpoint’s signing secret before trusting it.

Three details prevent most double counting and phantom commissions:

• Pick one payment event. invoice.paid and invoice.payment_succeeded fire for the same payment; handling both pays the partner twice.
• Skip zero-amount invoices. Trials and 100% off coupons produce invoices marked paid at $0, which are not revenue.
• De-duplicate by the Stripe event id. Stripe retries webhooks, so the same event can arrive more than once.

For refunds, note that charge.refunded carries the charge’s total refunded so far, not just the latest refund. If a customer receives two partial refunds, the commission reduction must be based on the difference, or the second refund will be counted twice.

Attributing sales by coupon or promotion code

Coupon codes let partners earn from audiences that never click a link: podcast listeners, video viewers, people who heard a recommendation in person. The customer types the partner’s code at checkout, and the code itself identifies the partner.

The catch with Stripe is that the customer-facing promotion code is not always visible in webhook payloads. Stripe usually sends it as a promo_ id rather than the text the customer typed, unless the object was expanded. There are two reliable ways around this:

• Copy the code the customer entered into the session and subscription metadata when you create the checkout, so the webhook carries it as text.
• Create the Stripe coupon with an id or name equal to the partner’s code, so it can be matched even without metadata.

Decide in your terms which wins when a customer has both a referral cookie and a typed code. Many programs let the typed code win, since it is the clearer signal of intent, but only for customers not already attributed to another partner.

Common pitfalls and how to handle them

Finally, test the whole chain in Stripe test mode before inviting partners: click a partner link, sign up, pay with a test card, issue a partial refund, then cancel. You should see a sign-up, a commission, a reduced commission and a cancelled subscription, each against the right partner. Once that works, the SaaS demo shows what the resulting dashboard looks like.

Frequently asked questions