Track sales

After a customer completes a purchase, call track.sale() from your server to attribute the revenue to the partner who referred them. Refport calculates the commission and queues it for payout.

Prerequisites

• The refp_id click ID must have been captured earlier in the funnel (by refport-js on the frontend)
• A Refport API key (find it in Settings → API Keys)

Basic sale tracking

Read the click ID from the customer's request and call track.sale():

import { Refport, getClickIdFromRequest } from 'refport';

const refport = new Refport({ apiKey: process.env.REFPORT_API_KEY! });

async function handleOrderCompleted(req: Request, order: Order) {
  const clickId = getClickIdFromRequest(req);
  if (!clickId) return; // not a referred customer

  await refport.track.sale({
    clickId,
    customerExternalId: order.userId,
    amount: order.amountCents,        // in smallest currency unit (e.g. cents)
    currency: 'usd',
    eventName: 'Purchase',
    invoiceId: order.id,              // used for deduplication
    paymentProcessor: 'custom',
  });
}

Where to call it

Call track.sale() from a trusted server environment — never from the browser. Good places to call it include:

• Your order confirmation API route
• A Stripe webhook handler (see Stripe integration)
• A background job triggered after payment confirmation

Deduplication

Pass invoiceId with your unique order or invoice ID. Refport uses this to prevent double-counting the same sale if the event is delivered more than once (e.g. from a webhook retry).

await refport.track.sale({
  clickId,
  customerExternalId: order.userId,
  amount: order.amountCents,
  invoiceId: order.id,   // Refport deduplicates on this field
});

Handling the case where the click ID is missing

Not all customers arrive via a referral link. It's normal for clickId to be null — simply skip the tracking call in that case.

const clickId = getClickIdFromRequest(req);
if (!clickId) {
  // organic sale — nothing to attribute
  return;
}

Reading the click ID in different frameworks

The getClickIdFromRequest helper works with standard Request objects, Next.js request objects, and Express-style requests. For more control, use getClickIdFromCookie with the raw cookie header string.

// Express / Node.js HTTP
import { getClickIdFromCookie } from 'refport';
const clickId = getClickIdFromCookie(req.headers.cookie);

// Fetch API / Next.js App Router
import { getClickIdFromRequest } from 'refport';
const clickId = getClickIdFromRequest(request); // Request object

Full parameter reference

See track.sale() in the Node.js SDK reference for all available parameters and the response shape.