SDKs

Beta — The @affitor/sdk package and CLI are in active development. The documented happy-path works; edge cases may change. Report issues on GitHub.

One package covers the full attribution chain via subpaths: the browser entry captures clicks and leads on the frontend; the /server entry reports conversions from your backend.

@affitor/sdk (Browser)

SSR-safe typed npm wrapper over the Affitor tracking endpoints. Captures ?aff= attribution, persists a affitor_click_id first-party cookie (60-day default), and reports click and lead events. All methods are no-ops on the server — safe to import in Next.js and other SSR frameworks without guards.

Install

npm install @affitor/sdk

Or include the script tag directly:

<script
  src="https://api.affitor.com/js/affitor-tracker.js"
  data-affitor-program-id="YOUR_PROGRAM_ID"
  defer
></script>

Quick start

import { init, signup } from '@affitor/sdk';

// On app load (client-side only — no-op on server)
init({ programId: 123 });

// After the user completes signup / checkout
await signup('user_abc123', 'user@example.com');

AffitorInitOptions

Options accepted by init() and the AffitorTracker constructor.

AffitorData

Returned by getData() — a snapshot of current tracker state.

Methods

signup() requires customerKey — this is your own user id. Affitor uses it to bind the customer to a click so later backend sale calls can resolve attribution by id alone.

Full example (Next.js)

// app/providers.tsx — client component
'use client';
import { useEffect } from 'react';
import { init } from '@affitor/sdk';
export function AffitorInit() {
  useEffect(() => { init({ programId: YOUR_PROGRAM_ID }); }, []);
  return null;
}
// render <AffitorInit /> once in app/layout.tsx

After successful signup, call signup(customerKey, email) from the SDK (or window.affitor.signup(...) for the script-tag path):

import { signup } from '@affitor/sdk';

// After successful signup
await signup(userId, email);

@affitor/sdk/server (Server)

Typed, Bearer-authenticated client over the Affitor conversion API. Use this from your backend to report leads, sales, and refunds for any payment provider (Stripe, Polar, Lemon Squeezy, Paddle, etc.).

Never ship the program API key to the browser.

Install

npm install @affitor/sdk

Quick start

import Affitor from '@affitor/sdk/server';

const affitor = new Affitor({ apiKey: process.env.AFFITOR_API_KEY! });

// On user signup — bind the customer to their affiliate click
await affitor.trackLead({ customerExternalId: user.id, clickId });

// On payment success — report the sale
await affitor.trackSale({
  customerExternalId: user.id,
  amount: 4999,         // cents
  invoiceId: inv.id,    // idempotency key
});

AffitorOptions

Constructor options for new Affitor(opts).

AffitorResponse<T>

All methods return Promise<AffitorResponse<T>>.

Methods

trackLead(input: TrackLeadInput)

Binds customerExternalId to clickId. Once bound, later trackSale calls need only customerExternalId — no click id required.

At least one of customerExternalId or clickId is required; throws synchronously if both are missing.

trackSale(input: TrackSaleInput)

Records a completed sale and creates a commission. Resolves attribution by customerExternalId first, then clickId. Idempotent by invoiceId.

At least one of customerExternalId or clickId is required, and amount must be a positive integer. Both amount and invoiceId throw synchronously if invalid.

trackClick(input?: TrackClickInput)

Track a click server-side. Click tracking is usually handled in the browser by @affitor/sdk; use this only for server-rendered flows or redirect-based affiliate links.

This endpoint does not require authentication.

trackRefund(input: TrackRefundInput)

Reverses the commission for a previously tracked sale. Call from your payment provider's refund webhook. Idempotent by invoiceId.

• Omit refundAmountCents (or pass 0) for a full refund → commission status set to reversed.
• Pass a partial amount → commission status set to refunded (proportional).

invoiceId is required and throws synchronously if missing.

Full example (Stripe webhook)

import Stripe from 'stripe';
import Affitor from '@affitor/sdk/server';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const affitor = new Affitor({ apiKey: process.env.AFFITOR_API_KEY! });

// POST /webhooks/stripe
export async function handleStripeWebhook(rawBody: Buffer, sig: string) {
  const event = stripe.webhooks.constructEvent(
    rawBody,
    sig,
    process.env.STRIPE_WEBHOOK_SECRET!
  );

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session;
    const result = await affitor.trackSale({
      customerExternalId: session.client_reference_id ?? undefined,
      amount: session.amount_total ?? 0,
      invoiceId: session.payment_intent as string,
      currency: session.currency?.toUpperCase(),
      saleType: 'payment',
    });

    if (!result.ok) {
      console.error('Affitor trackSale failed:', result.error);
    }
  }

  if (event.type === 'charge.refunded') {
    const charge = event.data.object as Stripe.Charge;
    await affitor.trackRefund({
      invoiceId: charge.payment_intent as string,
      refundAmountCents: charge.amount_refunded,
    });
  }
}

Related

• Track Click — raw HTTP endpoint reference
• Track Lead — raw HTTP endpoint reference
• Track Sale — raw HTTP endpoint reference
• Track Refund — raw HTTP endpoint reference
• Lead Tracking Guide — implementation walkthrough