Integrations
Node.js server
Server-side Affitor integration with @affitor/sdk/server: track signups and sales from your Express or Fastify backend, including a raw-body Stripe webhook in Fastify.
This guide wires Affitor into a Node.js server app built with Express or Fastify. Because both are pure server runtimes, the click is captured by a frontend script tag, then the affitor_click_id is forwarded to your server so all tracking calls, lead and sale, happen server-side with @affitor/sdk/server. Where the two differ, the code has an Express and a Fastify tab. Building with Next.js? See the Next.js guide.
The @affitor/sdk package is Beta. The documented happy-path works; report issues on GitHub.
Prerequisites
- Your program ID (program menu → Program settings → Business)
- A program API key for server-side calls (dashboard → API keys)
@affitor/sdkinstalled in your backend (the Fastify example also installsstripe)
npm i @affitor/sdknpm i @affitor/sdk stripe1. Capture the click (frontend)
Add the Affitor script tag to every page of your frontend. It reads ?via= or ?aff= from the URL and stores the affitor_click_id as a first-party cookie automatically, with no JS call required.
<script
src="https://api.affitor.com/js/affitor-tracker.js"
data-affitor-program-id="YOUR_PROGRAM_ID"
defer
></script>When your signup form submits, read the click id and send it to your server along with the form data:
// frontend: read the click id before submitting
const clickId = window.affitor?.getClickId() ?? null;
await fetch('/api/signup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password, affitorClickId: clickId }),
});The affitor_click_id lives in a first-party browser cookie. Your Express or Fastify handlers run with no access to that cookie, so you must forward the click id from the client explicitly. Without it, the lead has no partner to attribute to.
2. Track the signup
Instantiate the SDK once (module-level or via a shared singleton) and call trackLead as soon as you create the user record.
// lib/affitor.js
import Affitor from '@affitor/sdk/server';
export const affitor = new Affitor({ apiKey: process.env.AFFITOR_API_KEY });// routes/signup.js
import express from 'express';
import { affitor } from '../lib/affitor.js';
import { createUser } from '../db/users.js';
const router = express.Router();
router.post('/api/signup', async (req, res) => {
const { email, password, affitorClickId } = req.body;
// 1. Create the user in your database
const user = await createUser({ email, password });
// 2. Track the lead with Affitor
const result = await affitor.trackLead({
customerExternalId: user.id, // stable internal ID; reuse at sale time
clickId: affitorClickId, // forwarded from the browser (may be null)
email: user.email, // optional but improves attribution
});
if (!result.ok) {
// Non-fatal: log and continue; the user is already created
console.error('[affitor] trackLead failed', result.status, result.error);
}
res.json({ userId: user.id });
});
export default router;// routes/signup.js
import { affitor } from '../lib/affitor.js';
import { createUser } from '../db/users.js';
export default async function signupRoutes(fastify) {
fastify.post('/api/signup', async (request, reply) => {
const { email, password, affitorClickId } = request.body;
// 1. Create the user in your database
const user = await createUser({ email, password });
// 2. Track the lead with Affitor
const result = await affitor.trackLead({
customerExternalId: user.id, // stable internal ID; reuse at sale time
clickId: affitorClickId, // forwarded from the browser (may be null)
email: user.email, // optional but improves attribution
});
if (!result.ok) {
// Non-fatal: log and continue; the user is already created
request.log.error({ status: result.status, error: result.error }, '[affitor] trackLead failed');
}
return { userId: user.id };
});
}customerExternalId is your stable internal user ID. Use the exact same value when you track a sale: this is what links a partner's click to a commission.
If you use a server-side auth webhook (e.g. a third-party identity provider firing a user.created event), that webhook runs with no browser context and therefore no affitor_click_id. In that case you must read window.affitor.getClickId() on the client at signup time, store the click id on the user record or pass it through your own API, and then forward clickId to trackLead from the webhook. The client-side path above is simpler and more reliable.
3. Track the sale
Sales must always be tracked server-side, never from the browser.
Option A: Stripe integration (recommended for Stripe Checkout)
Connect your Stripe account under Program settings › Payments, then attach Affitor metadata when you create the Checkout Session. Affitor receives the account's checkout.session.completed and invoice events (invoice.payment_succeeded, invoice.paid) through Stripe Connect (you add no webhook) and attributes the sale automatically, with no extra trackSale call needed.
Attach affitor_click_id, affitor_customer_key, and program_id. For subscriptions, put the same fields in subscription_data.metadata too: only that copy reaches the Subscription and its invoices (the first payment and every renewal).
// server: creating the Checkout Session
const session = await stripe.checkout.sessions.create({
mode: 'subscription', // or 'payment'
line_items: [{ price: 'price_xxx', quantity: 1 }],
success_url: 'https://yoursite.com/success',
cancel_url: 'https://yoursite.com/cancel',
metadata: { // first payment (checkout.session.completed)
affitor_click_id: affitorClickId, // forwarded from the browser
affitor_customer_key: user.id, // SAME id used at signup
program_id: 'YOUR_PROGRAM_ID',
},
// Subscriptions: only this copy reaches the Subscription and its invoices
subscription_data: {
metadata: {
affitor_click_id: affitorClickId,
affitor_customer_key: user.id,
program_id: 'YOUR_PROGRAM_ID',
},
},
});Option B: Server-side tracking (any payment provider)
Call trackSale directly from your payment webhook or post-charge handler.
// routes/webhook.js (or wherever you confirm payment)
import { affitor } from '../lib/affitor.js';
router.post('/webhooks/payment', async (req, res) => {
const event = verifyAndParse(req); // your provider's webhook verification
if (event.type === 'payment.succeeded') {
const { userId, amountCents, invoiceId } = event.data;
const result = await affitor.trackSale({
customerExternalId: userId, // SAME id as trackLead
amount: amountCents, // integer cents, e.g. 4999 for $49.99
invoiceId: invoiceId, // idempotency key; duplicate returns 409
});
if (!result.ok) {
if (result.status === 409) {
// Already tracked; safe to ignore
} else {
console.error('[affitor] trackSale failed', result.status, result.error);
}
}
}
res.sendStatus(200);
});This example tracks the sale from your own Stripe webhook (self-hosted sale tracking). It reads the Affitor metadata from the Checkout Session, so attach it as in Option A.
In Fastify, the Stripe webhook route needs the raw request body so stripe.webhooks.constructEvent can verify the signature. Fastify parses JSON by default, which corrupts the signature, so register a raw-body parser scoped to the webhook route.
Configure the raw body
Add a content-type parser that hands Stripe the untouched Buffer. Keep it scoped so your other routes still get parsed JSON.
// server.js
import Fastify from 'fastify';
const fastify = Fastify({ logger: true });
// Capture the raw body as a Buffer for the Stripe webhook only.
// Stripe signature verification fails if the body is parsed/re-serialized.
fastify.addContentTypeParser(
'application/json',
{ parseAs: 'buffer' },
(request, body, done) => {
if (request.routerPath === '/webhooks/stripe') {
// Leave the raw Buffer untouched for signature verification.
done(null, body);
} else {
try {
done(null, JSON.parse(body.toString()));
} catch (err) {
err.statusCode = 400;
done(err, undefined);
}
}
},
);If you prefer not to override the global JSON parser, the fastify-raw-body plugin exposes request.rawBody on a per-route basis instead. Either way, the Stripe handler must receive the unparsed body.
The webhook handler
// routes/stripe-webhook.js
import Stripe from 'stripe';
import { affitor } from '../lib/affitor.js';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
// The Tracking API reads ISO 4217 minor units. Stripe uses the same units except ISK and UGX
// (sent with two extra decimals) and MGA (sent with none), so convert those three.
const toIsoMinor = (amount, currency) =>
currency === 'isk' || currency === 'ugx' ? amount / 100 : currency === 'mga' ? amount * 100 : amount;
export default async function stripeWebhookRoutes(fastify) {
fastify.post('/webhooks/stripe', async (request, reply) => {
const signature = request.headers['stripe-signature'];
let event;
try {
event = stripe.webhooks.constructEvent(
request.body, // the raw Buffer from the content-type parser above
signature,
process.env.STRIPE_WEBHOOK_SECRET,
);
} catch (err) {
request.log.error({ err }, '[stripe] signature verification failed');
return reply.code(400).send(`Webhook Error: ${err.message}`);
}
switch (event.type) {
case 'checkout.session.completed': {
const session = event.data.object;
// Skip $0 / setup-mode sessions (free trials, $0 invoices): the SDK rejects
// a non-positive amount, and there's no revenue to attribute yet.
if (session.amount_total && session.amount_total > 0) {
const result = await affitor.trackSale({
// The click id the metadata step writes attributes the sale even when only the
// browser sent the lead; the customer key matches once it is stored on the customer.
clickId: session.metadata?.affitor_click_id,
customerExternalId: session.metadata?.affitor_customer_key,
amount: toIsoMinor(session.amount_total, session.currency), // ISO minor units (cents for USD)
currency: session.currency, // Stripe sends lowercase; Affitor reads it case-insensitively
invoiceId: session.id, // idempotency key; a duplicate returns 409
});
if (!result.ok && result.status !== 409) {
request.log.error({ status: result.status, error: result.error }, '[affitor] trackSale failed');
}
}
break;
}
}
return reply.code(200).send({ received: true });
});
}The handler above tracks the first subscription payment (checkout.session.completed). Subscription renewals arrive as a different event (invoice.paid) and need their own case: see Subscription Renewals in the Stripe Checkout metadata guide.
These handlers are only for self-hosted sale tracking. If your Stripe account is connected to the program, Affitor already records your Checkout payments and renewals from Stripe's events, so do not also call trackSale. A one-time payment or a renewal is recorded under the same id on both paths and Affitor refuses the second, but if your call lands first, its sale is not linked to the Stripe payment, so a refund in Stripe does not reverse its commission. A subscription's first payment can be counted twice: this handler records it under the Checkout Session id, and Stripe Connect records it again under the invoice id.
The invoiceId field acts as an idempotency key. If your webhook fires twice for the same payment, the second call returns { ok: false, status: 409 }: handle it as a no-op, not an error.
To track a refund, call trackRefund with the same invoiceId:
await affitor.trackRefund({
invoiceId: originalInvoiceId,
});Raw API fallback (cURL / any HTTP client)
If you cannot use the npm package, call the REST endpoint directly. All server-side endpoints require a Bearer token.
curl -X POST https://api.affitor.com/api/v1/track/sale \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "txn_abc",
"customer_key": "user_123",
"amount_cents": 4999,
"currency": "USD"
}'customer_key in the raw API, customerExternalId in @affitor/sdk/server, and affitor_customer_key in Stripe metadata are all the same value: your stable internal user ID. Keep it consistent.
Verify
- Open a partner link from your program. It carries the partner code in the Partner link parameter set on the Tracking settings page (
?via=by default for new programs; programs created before October 16, 2026 keep?aff=), and the tracker reads both?via=and?aff=. Anaffitor_click_idcookie is set in the browser
- Your
/api/signuphandler callstrackLeadand receives a 2xx response - With the Fastify Stripe webhook in Option B: at checkout, your
/webhooks/stripehandler verifies the Stripe signature and callstrackSale
- The click, lead, and sale appear under your program's tracking events
- Create a test lead from your server:
affitor.trackLead({ customerExternalId: 'test_customer', additionalData: { test_mode: true, program_id: YOUR_PROGRAM_ID } }). For a test sale, callPOST /api/v1/track/saledirectly with your API key andadditional_data: { test_mode: true }: the SDK'strackSale()cannot send it
Common mistakes
- Not forwarding
affitorClickIdfrom the client: your Express or Fastify handler has no access to the browser cookie, sotrackLeadanswers400and no lead is recorded. - Different customer IDs at signup vs sale:
customerExternalId/customer_key/affitor_customer_keymust be the exact same stable user ID everywhere. - Ignoring the 409 on
trackSale: a duplicateinvoiceIdreturns 409 by design; treat it as a no-op, not a failure. - Subscriptions missing
subscription_data.metadata. On your own Checkout Session, put the click insubscription_data.metadataso it reaches the invoices. Without a click in invoice metadata, Affitor can still match an existing customer or use a valid Affitorclient_reference_idfrom the subscription's Checkout Session, subject to account and program checks. The self-hosted renewal handler reads its identifiers from subscription metadata; it does not perform Affitor Connect'sclient_reference_idlookup. - Tracking a sale from the browser: sales are server-side only (Stripe metadata or the server SDK / REST API).
- Parsing the Stripe webhook body: Fastify's default JSON parser re-serializes the body and breaks signature verification. Register a raw-body parser scoped to
/webhooks/stripe. - Self-hosted sale tracking without the
invoice.paidrenewal handler:checkout.session.completedonly covers the first payment, so every renewal is missed. With Stripe connected, leave the handler out: Affitor records renewals itself.