Attribution

A payment provider does not know which visit a payment came from. PilotFox works it out in two steps:

1. Linking finds the person who paid and the visit the payment belongs to: the visit that started the checkout, else that person's latest visit before paying.
2. Crediting picks which of that person's visits the reports credit with the money: whose channel, referrer, campaign, landing page, country and device the revenue counts for. That is the site's credit model.

Affiliates have their own rule, which follows the browser that paid: see affiliates.

How a payment is linkedCopy Anchor Link

PilotFox tries these in order and stops at the first match. The payments list and the payments API report which one matched as attribution.

Subscriptions come first. Every payment of a subscription (renewals, upgrades) is linked like the subscription's earliest linked payment, normally its first, and credited to the same visit under every credit model, affiliate included. This takes precedence over the steps above, customer included: a renewal stays with the visit that started its subscription, even when it carries a reference of its own. Payments arrive in any order (an import reads the newest first), so when the first payment arrives after its renewals, the renewals follow it. This applies to synced providers; the payments API has no subscriptions.

Customers work both ways. A later payment of the same customer imported before the first one is linked once the first one arrives and is linked.

Option 1: a checkout referenceCopy Anchor Link

When the visitor starts checkout, create a fresh reference, send it with a checkout event, and pass the same reference to the provider when your server creates the checkout.

async function startCheckout() {
  const ref = crypto.randomUUID(); // letters, digits and dashes; needs HTTPS
  window.pilotfox?.event("checkout", { ref }); // "?." so a blocked script never blocks a sale

  const res = await fetch("/create-checkout", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ ref }),
  });
  location.href = (await res.json()).url;
}

Your server then puts ref on the checkout as metadata.pilotfox_ref. Each provider's page has the code: Stripe, Dodo Payments, Polar. On other billing systems, send it as the payments API's ref.

Which fields are checkout referencesCopy Anchor Link

A metadata value is used only when it is at most 500 characters.

References and your own idsCopy Anchor Link

Stripe's client_reference_id and Polar's reference_id often hold the merchant's own id: a user, cart or order id. Those are easy to guess, and anyone can send a checkout event carrying one from their own browser. So these two fields count as a checkout reference only in the format the PilotFox script mints, and otherwise as a user id only, never both:

• A PilotFox reference is pf followed by the decimal digits of four random 32-bit numbers (128 bits). The script adds one to payment links (below); you can make one the same way:

  Copy Text

  const ref = "pf" + crypto.getRandomValues(new Uint32Array(4)).join(""); // e.g. "pf2139954139356687339242114731773333166471"

• Anything else in those two fields (your user id, a UUID, an order number) is matched as a user id (option 2), never against checkout events.

A reference your server makes in another format, such as crypto.randomUUID(), goes in metadata.pilotfox_ref.

The earliest event winsCopy Anchor Link

A reference counts from the first checkout event that carried it: the payment is linked to the session of the earliest matching event within the 7 days before the payment. A later checkout event repeating the reference, from any browser, never moves the link or the affiliate. So make a fresh, unguessable reference for every checkout, and send the event before the redirect to the provider (an event up to a minute after the provider's payment time still counts, for clock differences).

The checkout's visit is also where crediting stops: visits the buyer made after starting the checkout are not credited with that sale.

Option 2: the user idCopy Anchor Link

If you already call identify when people sign in, put the same id in the checkout's metadata as pilotfox_user_id:

// In the page, after sign-in:
window.pilotfox?.identify(user.id);

// On your server, when creating the checkout:
metadata: { pilotfox_user_id: user.id },

Where PilotFox reads a user id, in order:

Only sessions of identified users count for this step. Use ids that cannot be guessed, such as random ids, rather than sequential numbers or email addresses: see what a visitor can claim.

Option 3: the email (fallback)Copy Anchor Link

Send each signed-in user's email from your server, with the server-side identify and an API key that has the ingest:write permission, for example when they sign in (the IP address and user agent of that request name their browser):

curl -X POST "https://pilotfox.app/api/v1/ingest/identify" \
  -H "Authorization: Bearer $PILOTFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site": "SITE_ID", "uid": "usr_8f3k2", "ip": "203.0.113.7", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/605.1.15", "traits": {"email": "buyer@example.com"}}'

A payment whose customer email matches that address, ignoring case, is then linked to that user's latest identified visit before the payment.

Use email as a fallback: references and user ids are exact.

What a visitor can claimCopy Anchor Link

The script runs in your visitors' browsers, so anyone can send a checkout event, call identify with any user id or set any trait from their own browser. None of that alone moves money:

• A checkout reference counts from the first event that carried it, and a Stripe client_reference_id or Polar reference_id counts as one only in the PilotFox format.
• Only an email sent by your server links a payment.
• An affiliate is credited only from the affiliate links of the browser the payment is linked to (affiliates).
• The ref values of checkout events are shown only to people and API keys with sessions:read. Without it (for example on a share link without sessions, or a public dashboard), GET /events/properties?name=checkout leaves the ref property out, and a prop:ref filter on any report is refused with 400, so references cannot be read off the reports and replayed.

One case remains. A payment linked by user id or email (or by a return page of a signed-in user) goes to that user's latest visit before the payment, whichever browser made it. Someone who knows a user's id and opens your site with it in the minutes between that user's checkout and their payment becomes the linked visit, and their own affiliate link would then count. Use user ids that cannot be guessed, and prefer a checkout reference, which is exact.

Credit modelsCopy Anchor Link

A buyer often visits several times before paying. Say someone found you through Hacker News on Monday, came back on Friday by typing your address, and paid. The payment is linked to that person and their Friday visit; the credit model decides which of their visits the reports credit.

• The lookback window is how far before the payment last_non_direct and first_visit look: 90 days by default, 1 to 365. With a 3-day window in the example, Monday's visit is too old and both models credit Friday's. When no visit fits the window, the payment is credited to its linked visit.
• Only visits up to the linked one count, and none more than 365 days before the payment.
• Choose the model and the window in Site settings → Revenue (settings.revenue.attributionModel and attributionWindowDays). Every report applies them as soon as you save, without importing anything again: totals and charts under filters and segments, breakdowns, the payments list, journeys and the API.
• The API's model=last_non_direct, first_visit or last_visit compares another model on one request without changing the setting (/revenue/summary, /revenue/timeseries, /revenue/breakdown, /revenue/subscriptions/breakdown, /payments and a payment's journey).

Who the person is. A signed-in user you identify is recognized on every visit and device, so all their visits count. Without cookies, a visitor who never signs in is recognized across days only while their network and browser stay the same (how visitors are counted): a buyer who first came from a phone and paid later from a laptop looks like two people, and the earlier visit cannot get the credit. In the daily identity mode an anonymous visitor's earlier days are never linked.

AffiliatesCopy Anchor Link

When a payment is linked to a visit, PilotFox also credits it to the last affiliate link that the browser of that visit arrived through within the affiliate attribution window (30 days by default, 1 to 365) before the payment. Only that browser's own visits count, even for a user you identify on several devices: anyone can send another user's id, so an affiliate link opened under the same user id in another browser earns nothing. The credit model never changes which affiliate earns a payment.

Payment links and return pagesCopy Anchor Link

With Payment links and return pages on (Site settings → Tracking code, settings.tracking.paymentLinks, on by default), the script links payments to visits in two cases without any code of yours.

Payment linksCopy Anchor Link

When a visitor clicks a link to a hosted payment page (a left click, a middle click, or a click that opens a new tab), the script adds a fresh PilotFox reference to the link, in the parameter the provider copies onto the payment, and sends a checkout event with it:

The link otherwise behaves exactly as before: the other parameters keep their exact encoding, target and modifier keys are left alone, and the link's own href is restored right after the click, so the next click gets a fresh reference. A link that already carries the parameter is left as it is and no event is sent. Nothing happens for a visitor who opted out. Links on your own domain (a custom domain for payment links) and buttons that open the checkout from code are not recognized: pass the reference yourself (option 1).

Return pagesCopy Anchor Link

When the page the provider sends the buyer back to carries the payment's own id in its address, the script sends a checkout event with that id as its ref. PilotFox matches it up to an hour after the payment and links the payment to that person's latest session started before it.

A checkout reference sent before the checkout wins over a return page: it names the visit the buyer started the checkout from. A payment the sync reads in the few seconds before its return page is recorded is linked by user id or email instead, if it can be.