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.

On by default

Lead tracking is on by default for every brand. There is nothing to turn on; the automatic capture below and the browser / S2S endpoints work as soon as the tracking loader is installed.

Automatic for Stripe and Paddle

For Stripe and Paddle, 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 Stripe or Paddle 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?

Braintree and Shopify have no pre-payment webhook (Braintree only reports a successful charge, Shopify only a paid order), so there is no event to turn into a lead automatically. Capture those leads with Rekomi.convert() in the browser or the S2S endpoint below.

Browser method: Rekomi.convert()

The browser Rekomi.convert() call records a lead at account creation. With Stripe and Paddle 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 and Shopify, which have no pre-payment webhook (Braintree only reports a successful charge, Shopify only a paid order), so automatic leads are not possible there.
• 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.

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.

Use the S2S path whenever the signup originates on your server and you can keep a secret server-side. It is the right path for Braintree, Shopify, and any other gateway driven from your backend.

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 Stripe and Paddle path, 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, on the campaign's Leads tab and in Insights. The funnel stage appears adaptively: brands that never record a lead do not see an empty Lead row.