Tracking and attribution

This page covers how Rekomi decides which affiliate gets credit for a sale, when that credit becomes payable, and how refunds reverse it.

How tracking works today

Every affiliate has one referral slug (shared across all the campaigns they join). They append it to links to your site as ?via={slug}, for example https://yourbrand.com/?via=abc123. When the visitor lands with that parameter, the tracking script (or the S2S API) records the click and attributes it to that affiliate.

Attribution happens two ways: the install snippet on your site reads ?via={slug} and sets a first-party cookie, or your backend calls the S2S tracking API telling Rekomi "this customer was referred by slug X". Either way the same affiliate gets credited.

Cookie window

cookieWindowDays on a campaign defines how long an affiliate's attribution survives after the initial touch. Default is 60 days. Typical ranges:

• 30 days: short-cycle products with quick conversion (impulse buys, free-to-paid signups).
• 60 days: medium consideration (most SaaS).
• 90 days: longer enterprise sales cycles, high-ticket courses.
• 180 days: very long consideration (annual-only products, enterprise).

The longer the window, the more refund-window exposure you carry, and the harder it is to claw back overpaid commissions if the customer churns early.

Attribution model

attributionModel controls which affiliate wins when multiple have referred the same visitor within the window.

• FirstTouch (default): the affiliate who drove the first tracked click within the window gets the credit. Rewards the affiliate who introduced the product.
• LastTouch: the affiliate who drove the most recent tracked click before the sale gets the credit. Rewards the affiliate who closed the deal.

Most subscription products run FirstTouch because the first introduction is the highest-leverage moment.

What counts as a sale

A sale is any Stripe event that produces a commission. The most common is a paid invoice (invoice.paid). For RevShare campaigns every paid invoice produces a sale (smaller commission than the first one if you set recurringDelayInvoices).

Sales move through statuses:

1. Pending: invoice paid, in the refund-hold window (default 30 days).
2. Approved: the refund window passed; commission is locked in and eligible for payout.
3. Paid: included in a payout batch and transferred to the affiliate's Stripe Connect account.
4. Refunded: Stripe refunded the customer; commission is reversed and clawed back.
5. Denied: manually denied by you (rare; usually only for disputed sales).

Free signups and leads

Not every signup is a paid sale on day one. A lead is a free, identified signup tied to the affiliate who referred it, recorded before any payment. It does two things for you:

• You can see which affiliate drove a free signup, not just paid ones, so your funnel reads visitor, then free signup, then sale.
• When that free user later upgrades to a paid plan, the sale is credited back to the same affiliate by matching the email, even if the click cookie was cleared, blocked, or expired in the meantime.

A lead never pays a commission on its own; the commission still happens when the paid sale comes through. The lead is just the durable link between the free signup and the eventual upgrade.

For Stripe and Paddle, leads are captured automatically. Lead tracking is on by default, so subscription signups, free trials, and fully discounted (100%-off coupon) signups all become leads straight from the processor webhooks you already receive, with no extra code on your site.

Free-plan and freemium signups need one line of code. If signing up for your free tier does not create a Stripe or Paddle subscription or customer, there is no processor event to turn into a lead, so your signup code calls Rekomi.convert({ email }) at account creation. Pass the same email the customer will bill with; that is what lets a later paid upgrade match back to the lead and credit the affiliate. The same one-line call covers Braintree and Shopify, which have no pre-payment webhook.

For the exact code, the email-match details, and the server-to-server option, see Track leads and signups.

Refund-aware attribution

When Stripe sends a charge.refunded or customer.subscription.deleted webhook within the refund-hold window, Rekomi:

1. Sets the sale's Status = Refunded.
2. Subtracts the commission from the affiliate's pending balance.
3. If the commission was already paid out (rare with default 30-day hold), the next payout batch debits the previous overpayment.

This happens automatically. You do not have a "mark as refunded" button in the dashboard today because Stripe is the source of truth.

S2S tracking for non-Stripe events

If you have sales that do not flow through Stripe (mobile app purchases, server-side trials, custom events), use the S2S tracking API. It accepts a POST with an externalEventId for idempotency, an affiliateSlug, an amountCents, and a currency. It is HMAC-signed and de-duped per organization.