Track leads and signups

A lead is a free identified signup: an email tied to a referral, recorded before any payment. Recording a lead buys you two things:

1. Durable email-match attribution. When the same email later pays, the sale is credited to the referring affiliate even if the click cookie was cleared, blocked, or expired in the meantime.
2. A Visitor → Lead → Sale funnel. Free signups become a real acquisition stage in your dashboard and insights, not just clicks and sales.

A lead does not mint a commission on its own. It records email + name against the referral; the commission still happens when the paid sale comes through your processor or the S2S API.

Enabled by default

Lead tracking is enabled for every brand by default. The automatic capture below and the browser / S2S endpoints work as soon as the tracking loader is installed.

Automatic for Stripe, Paddle, Chargebee, Recurly, and Creem

For Stripe, Paddle, Chargebee, Recurly, and Creem, leads are captured automatically, with zero brand code. You need nothing beyond what you already have:

• the normal tracking loader (loader.js) on your site, and
• your existing processor connection.

When a referred visitor signs up for a subscription or a free trial, Rekomi records a lead straight from the processor webhook your brand already receives. No convert() call, no signup form wiring. The first real payment is then recorded as the Sale, and it is attributed back to the same affiliate (the paid charge matches the lead by customer history).

Which processors capture leads automatically?

Leads are captured automatically, with zero code, for Stripe, Paddle, Chargebee, Recurly, and Creem: when a referred visitor starts a subscription or trial, the processor webhook records the lead. For Braintree, Shopify, Lemon Squeezy, Gumroad, and Dodo Payments there is no automatic lead capture; Rekomi does not receive a usable pre-payment signup event for them, so capture those leads with Rekomi.convert() in the browser instead. Polar sits in between: an attributed trial-start subscription automatically records a $0 lead (the trial's $0 order carries the referral), but non-trial checkouts have no pre-payment signup event, so capture those with Rekomi.convert(). The S2S lead endpoint is reserved for organizations without a native processor connection: while Stripe (via the Rekomi app for Stripe), Paddle, Braintree, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, Dodo Payments, or the Shopify app is connected, it returns a 409 (*_connect_active) to keep one conversion source per workspace.

Browser method: Rekomi.convert()

The browser Rekomi.convert() call records a lead at account creation. With Stripe, Paddle, Chargebee, Recurly, and Creem you do not need it for subscription / trial signups; those are already automatic. It is the primary lead path in the cases below.

Freemium and free plans

If your product has a free tier where signing up does not create a Stripe or Paddle subscription or customer, there is no processor event for Rekomi to turn into a lead automatically. This is roughly half of SaaS, so for those products Rekomi.convert() is the main way leads are captured, not a fallback.

Call Rekomi.convert({ email }) at account creation, the moment the free account is made:

Rekomi.convert({ email: "user@example.com" });

Pass the same email the customer will use for billing. When that free user later upgrades to a paid plan, Rekomi matches the sale back to this lead by email (the email-match attribution below), so the referring affiliate is still credited even though the click cookie is long gone. This is what carries attribution across the free-to-paid gap, which can be weeks or months:

Visitor (click) -> free signup (lead via convert) -> later upgrade (sale, email-matched to the lead)

Other cases for convert()

Rekomi.convert() is also the right tool for:

• Braintree, Shopify, Lemon Squeezy, Gumroad, and Dodo Payments, where Rekomi does not capture a lead automatically, so convert() is how you record the signup. On Polar, trial starts already record a $0 lead automatically; convert() covers non-trial signups.
• Capturing the lead earlier or richer: at the signup form, before checkout, or together with a name.

This is also the direct replacement for Rewardful's rewardful('convert', { email }), which makes it the easy path for teams migrating from Rewardful.

After the tracking script (loader.js) is installed, call Rekomi.convert(...) at signup, the moment a user creates an account:

Rekomi.convert({ email: "user@example.com", name: "Jane Doe" });

name is optional. There is also an identify alias and a string shorthand, all equivalent:

Rekomi.identify({ email: "user@example.com", name: "Jane Doe" });
Rekomi.convert("user@example.com");

The call posts to /api/v1/r/lead/signup and is a no-op when there is no referral context or no email, so it is safe to call unconditionally. To be explicit and only fire for referred visitors, wrap it in a ready() callback:

Rekomi.ready(function (R) {
  if (!R.referral) return; // visitor was not referred, nothing to record

  Rekomi.convert({
    email: signupForm.email,
    name: signupForm.name,
  });
});

ready() waits for the referral context to resolve, so you can read R.referral reliably before deciding whether to record the lead. See the full window.Rekomi API for referral, affiliate, campaign, and ready().

Server-to-server method

When signups happen on your backend, record the lead server-side instead:

POST /api/tracking/lead

It uses the same authentication as the S2S sale postback: a Authorization: Bearer rk_live_* API key plus an X-Rekomi-Signature HMAC-SHA256 header. The signing computation is identical to the sale endpoint, so reuse the same helper. See Server-to-server tracking for the signing details and code in Node.js, Python, and other languages.

The endpoint requires a Starter or higher plan (14-day trials accepted; lower tiers get 402 plan_tier_required) and an approved affiliate (a non-approved affiliate returns 400 affiliate_not_active). An optional programId body field disambiguates account-level slugs that span multiple campaigns.

Body:

{
  "affiliateSlug": "jane-recommends",
  "email": "user@example.com",
  "name": "Jane Doe",
  "externalEventId": "signup_abc123"
}

• affiliateSlug (required): the affiliate to credit. From the affiliate's tracking URL.
• email (required): the customer's email. This is what a later sale is matched against.
• name (optional): the customer's display name.
• externalEventId (optional): your unique id for this signup. Used for de-duplication, so retries are safe. Omit it unless you need your own retry key: without it, duplicate signups for the same affiliate and email collapse into one lead across the browser, server, and webhook paths. Supplying your own id keys the lead on that id instead, so the same person recorded through both the browser and a backend call with a custom id can become two lead rows.

Use the S2S path whenever the signup originates on your server, you can keep a secret server-side, and your workspace has no native processor connection. While Stripe (via the Rekomi app for Stripe), Paddle, Braintree, Lemon Squeezy, Chargebee, Polar, Recurly, Gumroad, Creem, Dodo Payments, or the Shopify app is connected, this endpoint returns 409 with the matching *_connect_active error (one conversion source per workspace); capture leads with Rekomi.convert() there instead. It is the right path for gateways you drive entirely over S2S.

MCP method

For AI-assistant and automation flows, the MCP server exposes a record_lead tool. Inputs: affiliateSlug, email, optional name, and optional campaignId. It records a signup lead the same way the browser and S2S paths do.

How attribution works

Email-match is a fallback only. It never overrides an attribution Rekomi already has. The resolver still tries, in order:

1. Coupon-code override
2. Processor metadata (e.g. the Stripe rekomi_affiliate_id)
3. Prior conversion by customer history
4. Coupon

Only when all of those miss does Rekomi fall back to matching the sale's email against a recorded lead. The match is:

• Scoped to your own workspace. A lead in one workspace can never credit a sale in another.
• Aged to 90 days. A sale is matched only against a lead recorded within the last 90 days; the newest qualifying lead wins.

Because it is the last step, existing attribution is unchanged and sales are never mis-credited. For the automatic processor path (Stripe, Paddle, Chargebee, Recurly, Creem), the later paid charge already attributes by customer history (step 3 finds the lead row by customer id), so email-match is not even needed for the same-customer case. Brands not using leads see no difference at all.

Where leads show up

Once leads are flowing, the dashboard surfaces a Visitor → Lead → Sale funnel and lead counts alongside clicks and conversions, in the campaign's Performance tab, Leads section, and in Reports. The funnel stage appears adaptively: brands that never record a lead do not see an empty Lead row.