Skip to Content

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.

View as Markdown

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.

Info

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/sdk installed in your backend (the Fastify example also installs stripe)
npm i @affitor/sdk
npm i @affitor/sdk stripe

1. 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 }),
});
Info

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.

Info

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.

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);
      }
    }
  },
);
Info

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 });
  });
}
Info

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"
  }'
Info

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

Verify success
Browser
  • 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=. An affitor_click_id cookie is set in the browser
Network
  • Your /api/signup handler calls trackLead and receives a 2xx response
  • With the Fastify Stripe webhook in Option B: at checkout, your /webhooks/stripe handler verifies the Stripe signature and calls trackSale
Dashboard
  • The click, lead, and sale appear under your program's tracking events
If it doesn't work
  • 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, call POST /api/v1/track/sale directly with your API key and additional_data: { test_mode: true }: the SDK's trackSale() cannot send it

Common mistakes

Common mistakes
  • Not forwarding affitorClickId from the client: your Express or Fastify handler has no access to the browser cookie, so trackLead answers 400 and no lead is recorded.
  • Different customer IDs at signup vs sale: customerExternalId / customer_key / affitor_customer_key must be the exact same stable user ID everywhere.
  • Ignoring the 409 on trackSale: a duplicate invoiceId returns 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 in subscription_data.metadata so it reaches the invoices. Without a click in invoice metadata, Affitor can still match an existing customer or use a valid Affitor client_reference_id from 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's client_reference_id lookup.
  • 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.paid renewal handler: checkout.session.completed only covers the first payment, so every renewal is missed. With Stripe connected, leave the handler out: Affitor records renewals itself.
Next recommended step
Tracking Stripe sales?

See the Stripe guide for one-time payments, subscription renewals, and the attribution fallback chain.

Continue →