Affiliates

An affiliate is anyone who sends you visitors through a link that names them, such as https://example.com/?ref=jane. PilotFox records which affiliate each visit came through and, with payments connected or recorded, which payments followed and what commission they earn. Each affiliate can get a read-only portal with their own numbers.

Referral linksCopy Anchor Link

A visit is credited to an affiliate when its page URL carries one of the site's affiliate parameters. The parameter is ref by default; on the Affiliates page, Tracking settings can change it or add others: up to 5 names of 1 to 32 letters, digits, _, . or - (settings.affiliates.params). Names are compared without regard to case.

• The value becomes a slug: lowercased, with every character other than a–z, 0–9, _ and - removed, cut to 64 characters. ?ref=Jane Doe and ?ref=janedoe are the same affiliate, janedoe. Letters outside ASCII are removed, not transliterated (Zoë becomes zo).
• If a URL carries several of the parameters, the first one in the URL with a non-empty slug counts.
• A session's affiliate is the first one it carries; later pages of the session keep it.
• The parameter is read from the full page URL before the site's query-string privacy rules apply, so it is recorded even when you store no query strings. It needs the tracker's Query strings option on (Site settings → Tracking code), since without it the script never sends the query string. To keep query strings out of your data and still track affiliates, leave that option on and set Store query string parameters to None (Site settings → Privacy & identity).

Affiliate links are separate from the Affiliate traffic channel, which comes from campaign tags (utm_medium=affiliate).

Registering affiliatesCopy Anchor Link

The Affiliates page lists your registered affiliates and, below them, slugs seen in traffic that nobody registered yet (the 100 with the most visits). Registering a slug (editors and above: affiliates:write) gives it:

• a name (1 to 80 characters) and its slug, stored in the slug form above;
• a commission rate, from 0 to 100 % with at most two decimals (0 by default);
• a report: visits, visitors, payments and revenue over time, its commission, its top landing pages, referrers and countries, and its latest payments;
• a portal link you can share with the affiliate (affiliate portal).

curl -X POST "https://pilotfox.app/api/v1/sites/SITE_ID/affiliates" \
  -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "slug": "Jane", "commissionPercent": 20}'

{
  "data": {
    "id": "915d611d-0fb1-45c3-8473-b6d8dd90443b",
    "name": "Jane Doe",
    "slug": "jane",
    "commissionPercent": 20,
    "shareEnabled": false,
    "createdAt": "2026-10-27T20:31:19.211Z",
    "updatedAt": "2026-10-27T20:31:19.211Z"
  }
}

A slug the site already has is 409; a slug with nothing left after normalizing is 400. Deleting an affiliate keeps its recorded visits and payments: they show again as the unregistered slug.

Revenue and commissionCopy Anchor Link

A payment linked to a visit is credited to the last affiliate link that the browser of that visit came through within the attribution window before the payment: 30 days by default, 1 to 365 in Tracking settings (settings.affiliates.windowDays). The affiliate is stored with the payment when it is imported or recorded.

Only that browser's own visits count, also for signed-in users you identify on several devices: an affiliate link opened on a phone does not earn a payment made from a laptop. Anyone can send another user's id from their own browser, so a visit under the same user id in another browser never takes the credit, and a checkout event that repeats a reference never moves it either (what a visitor can claim). The revenue credit model never changes which affiliate earns a payment, and renewals of a subscription keep the affiliate of its first payment.

Changes to the parameters or the window apply to new visits and newly imported payments; what was already recorded keeps its affiliate. Report filters and segments do not apply to affiliate figures.

Who sees money. Affiliate figures need affiliates:read (every organization role has it). The numbers read from payments (payments, revenue, commission, conversion_rate, a report's latest payments) need revenue:read too: without it they come back as null (an empty list for latest payments). Share links and public dashboards see no affiliate data.

API endpointsCopy Anchor Link

All under /api/v1/sites/{siteId}. Stats and reports take a time window (last=, start/end, all), without filters or comparison.

GET /affiliates/stats lists every registered affiliate and the top 100 unregistered slugs by visits, with totals over every affiliate session and payment of the period. An affiliate's report adds its link (https://<site domain>/?<first parameter>=<slug>), its series over the period, its top 10 landing_pages, referrers and countries, and its 20 newest payments (time, amount, currency and status: no ids or emails).