---
id: "api-reference/sdks"
type: "doc"
url: "https://affitor.com/docs/api-reference/sdks"
kind: "reference"
updated: "2026-11-08"
---
# SDKs

> Typed client libraries for browser tracking (@affitor/sdk) and server-side conversion reporting (@affitor/sdk/server).

> **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.

<FeatureCards>
  <FeatureCard icon="monitor" title="@affitor/sdk" href="#affitorsdk-browser">Browser SDK: captures affiliate clicks, persists attribution in a first-party cookie, and reports lead events.</FeatureCard>
  <FeatureCard icon="server" title="@affitor/sdk/server" href="#affitorsdkserver-server">Node SDK: reports leads, sales, clicks, and refunds from your backend with Bearer auth.</FeatureCard>
</FeatureCards>

---

## @affitor/sdk (Browser)

SSR-safe typed npm wrapper over the Affitor tracking endpoints. Captures `?aff=` (or `?via=`) 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, so it is safe to import in Next.js and other SSR frameworks without guards.

### Install

```bash
npm install @affitor/sdk
```

Or include the script tag directly:

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

### Quick start

```ts
import { loadAffitor } from '@affitor/sdk';

// On app load (client-side; resolves to null on the server)
const affitor = await loadAffitor(123);

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

`loadAffitor` loads the tracker script once and resolves to the same instance on every later call. The tracker captures `?aff=` (or `?via=`) from the URL and sets the click id cookie by itself.

The tracker sends events to `https://api.affitor.com`. To send them to a non-production API, set `window.AFFITOR_API_BASE = '<API_BASE>'` before the first `loadAffitor` call, or use the script tag with `data-affitor-api-base`.

---

### `loadAffitor(programId, options?)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `env` | `'production' \| 'local'` | `'production'` | Selects the tracker script URL. |
| `scriptUrl` | `string` | none | Custom tracker script URL; overrides `env`. It only chooses where the script loads from. |
| `debug` | `boolean` | `false` | For testing only: logs `info` and `warn` messages, and makes `signup()` send a [test event](/docs/api-reference/test-mode) instead of a lead, so no real lead is recorded. Turn it off before production. Errors always log. |

---

### Instance methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `signup` | `(customerKey: string, email: string) => Promise<void>` | Report a lead (signup). Pass your internal user id as `customerKey`. |
| `getClickId` | `() => string \| null` | The current click id from memory or the `affitor_click_id` cookie. |
| `getVisitorId` | `() => string \| null` | The visitor id from Affitor's first-party cookie, or `null`. Put it in checkout metadata as `affitor_visitor_id`. With consent mode on, call it after `consent(true)`. |
| `consent` | `(granted: boolean) => void` | With `data-affitor-consent="required"` on the script, nothing is stored or sent until `consent(true)`; `consent(false)` removes Affitor's cookies. |
| `getData` | `() => AffitorData` | A snapshot of tracker state. |
| `trackTest` | `(data?) => void` | Send a test event. |
| `init` | `(options: { programId?: string \| number; debug?: boolean }) => void` | Starts the tracker. It runs on its own when the script loads (through `loadAffitor` or the script tag), so you do not need to call it. |
| `trackLead` | `(data: TrackLeadData) => Promise<void>` | Deprecated: use `signup`. Older alias that calls `signup` with the object's `customer_key` (or `user_id`) and `email`. |

> `signup()` requires `customerKey`, your own user id. By default a browser `signup()` records a provisional lead, which does not bind your customer key to the customer record for later sale matching (the Lead tracking section shows "Browser leads: server/payment confirmation required"). Until the key is stored on a customer (by a server-verified lead or an attributed Stripe payment), a backend sale that sends only `customerExternalId` finds no customer and is refused with `400` `Customer not found`. Send the lead from your server as well (`trackLead` with `customerExternalId` and `clickId`), or pass `clickId` with the sale.

### `AffitorData`

Returned by `getData()`.

| Field | Type | Description |
|-------|------|-------------|
| `clickId` | `string \| null` | The active `affitor_click_id` (in memory or from the cookie). |
| `programId` | `number` | The resolved program id. |
| `hasAttribution` | `boolean` | `true` when a valid click has been tracked. |
| `affiliateUrl` | `string \| null` | The affiliate URL that started the current attribution. |

---

### Full example (Next.js)

```tsx
// app/affitor-tracker.tsx: client component
'use client';
import { useEffect } from 'react';
import { loadAffitor } from '@affitor/sdk';

export function AffitorTracker() {
  useEffect(() => {
    void loadAffitor(YOUR_PROGRAM_ID);
  }, []);
  return null;
}
// render <AffitorTracker /> once in app/layout.tsx
```

After a successful signup, call `signup(customerKey, email)` on the instance (or `window.affitor.signup(...)` for the script-tag path):

```ts
import { loadAffitor } from '@affitor/sdk';

const affitor = await loadAffitor(YOUR_PROGRAM_ID);
await affitor?.signup(userId, email);
```

React apps can also use `AffitorProvider` and `useAffitor()` from `@affitor/sdk/react`.

`@affitor/sdk/pure` exports `loadAffitor` and the types `AffitorInstance`, `AffitorInitOptions`, `TrackSignupData`, `TrackLeadData` and `TrackTestData`. `@affitor/sdk` exports the same, plus the option types `AffitorEnv` and `LoadAffitorOptions`. Both inject the tracker script only when `loadAffitor()` runs; importing from `/pure` makes that explicit.

---

## @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

```bash
npm install @affitor/sdk
```

### Quick start

```ts
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)`.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `apiKey` | `string` | **Yes** | Program API key (Bearer). Find it in your Affitor dashboard under program settings. |
| `apiUrl` | `string` | No | Override the API base URL. Defaults to `https://api.affitor.com`. |
| `fetch` | `typeof fetch` | No | Custom fetch implementation. Required for Node versions below 18 that lack a global `fetch`. |

---

### `AffitorResponse<T>`

The `track*` methods return `Promise<AffitorResponse<T>>`. [`readiness()`](#readinessopts) returns the verdict itself.

| Field | Type | Description |
|-------|------|-------------|
| `ok` | `boolean` | `true` when the HTTP status was 2xx. |
| `status` | `number` | HTTP status code. `0` on network error. |
| `data` | `T \| null` | Parsed response body when `ok` is `true`; `null` on error. |
| `error` | `string \| undefined` | Error message or HTTP status text when `ok` is `false`. |

---

### Methods

#### `trackLead(input: TrackLeadInput)`

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

The SDK throws synchronously only when both `customerExternalId` and `clickId` are missing. Send `clickId` on every lead: Affitor finds the customer through the click. A first lead with only `customerExternalId` returns `ok: false` with status `400` (`Customer not found. Provide a valid click_id or customer_key.`).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `customerExternalId` | `string` | Conditional | Your own user id. Binds the customer to the click for downstream sale attribution. |
| `clickId` | `string` | Conditional | `affitor_click_id` cookie value from the browser. Send it on every lead. |
| `email` | `string` | No | Customer email (hashed server-side). |
| `eventName` | `string` | No | Custom event label for segmentation. |
| `additionalData` | `Record<string, unknown>` | No | Arbitrary metadata passed through to the event record. |

---

#### `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.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `customerExternalId` | `string` | Conditional | Your own user id. It resolves attribution when it matches a key already stored on a customer in your program, for example by a server-verified lead or an attributed Stripe payment. |
| `clickId` | `string` | Conditional | `affitor_click_id` cookie value (fallback if no prior lead). |
| `amount` | `number` | **Yes** | Sale amount as an integer in the currency's [minor unit](/docs/api-reference/track-sale#minor-units-and-conversion): cents for USD (`4999` = $49.99), whole units for JPY or VND. |
| `taxCents` | `number` | No | The tax included in `amount`, same unit. Commissions are calculated on `amount - taxCents`. Requires `@affitor/sdk` 2.1.2 or later. |
| `invoiceId` | `string` | **Yes** | Unique invoice or transaction id, used as an idempotency key to deduplicate retries. |
| `currency` | `string` | No | A [supported ISO 4217 code](/docs/api-reference/track-sale#request-fields); another code returns `422`. Defaults to `USD`. Commissions and platform fees are calculated on the pre-tax amount [converted to USD](/docs/api-reference/track-sale#minor-units-and-conversion), and invoices are issued in USD. |
| `saleType` | `'payment' \| 'subscription'` | No | Categorize the sale type. |
| `isRecurring` | `boolean` | No | `true` for recurring subscription charges. |
| `subscriptionId` | `string` | No | External subscription id from your payment provider. |
| `subscriptionInterval` | `'monthly' \| 'quarterly' \| 'annual'` | No | Billing cadence for subscription sales. |
| `eventName` | `string` | No | Custom event label for segmentation. |

---

#### `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.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `affiliateUrl` | `string` | No | The full affiliate URL containing the `?aff=` or `?via=` parameter. |
| `pageUrl` | `string` | No | The landing page URL. |
| `referrerUrl` | `string` | No | The HTTP referrer. |
| `existingClickId` | `string` | No | An existing click id. Affitor reuses the customer that has this click id, so that customer's partner does not change. `trackClick` sends no `program_id`, so this lookup is not limited to one program. When no customer has the click id, a new customer is created with it. |

---

#### `trackRefund(input: TrackRefundInput)`

Reverses the commission for a previously tracked sale. Call it once per refund, from your payment provider's refund webhook.

- Omit `refundAmountCents` to refund everything not yet refunded → commission status set to `reversed`. Do not pass `0`: for a sale recorded from November 5, 2026 (16:00 UTC) with a commission to reverse, it answers `400` and nothing is refunded.
- Pass **this refund's own amount** → it is added to what was already refunded on the sale. Once the total reaches the sale amount, the commission is `reversed`. Before that, a partial refund reduces a commission already approved and cancels one still `pending` (in its hold period, not yet approved); both end `refunded`.
- Do not pass a running total (such as Stripe's `charge.amount_refunded`): each call with a new amount is added as a new refund.
- A retry with the same amount is ignored. To report two separate refunds of the same amount, call the [HTTP endpoint](/docs/api-reference/track-refund) with a distinct `refund_id` for each.

`invoiceId` is required and throws synchronously if missing.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `invoiceId` | `string` | **Yes** | The `invoiceId` you passed to `trackSale`; identifies which sale to refund. |
| `refundAmountCents` | `number` | No | This refund's amount in the sale currency's minor unit (not the running total). Omit it to refund the rest of the sale; do not pass `0`. |
| `refundReason` | `string` | No | Optional reason string passed through to the refund record. |

---

#### `readiness(opts?)`

Returns the program's readiness verdict from `GET /api/v1/programs/me/readiness`; the program comes from the API key. Pass `{ forceRecheck: true }` (`?force_recheck=true`) to check your site for the tracker again instead of using the cached result; a forced check runs at most once per minute per program.

It resolves to the verdict object (`ReadinessResult`: `state`, `integration_verified`, `blocker`, `gates`, and more), not an `AffitorResponse`, and throws `AffitorApiError` (with `status`, `code` and `retryAfterSeconds`) on a non-2xx response.

---

### Full example (Stripe webhook)

```ts
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! });

// 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.
function toIsoMinor(amount: number, currency: string): number {
  if (currency === 'isk' || currency === 'ugx') return amount / 100;
  return currency === 'mga' ? amount * 100 : amount;
}

// 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: toIsoMinor(session.amount_total ?? 0, session.currency ?? 'usd'),
      invoiceId: session.payment_intent as string,
      currency: session.currency?.toUpperCase(),
      saleType: 'payment',
    });

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

  // One event per refund, carrying that refund's own amount.
  if (event.type === 'refund.created') {
    const refund = event.data.object as Stripe.Refund;
    await affitor.trackRefund({
      invoiceId: refund.payment_intent as string,
      refundAmountCents: toIsoMinor(refund.amount, refund.currency),
    });
  }
}
```

---

## Related

- [Track Click](/docs/api-reference/track-click): raw HTTP endpoint reference
- [Track Lead](/docs/api-reference/track-lead): raw HTTP endpoint reference
- [Track Sale](/docs/api-reference/track-sale): raw HTTP endpoint reference
- [Track Refund](/docs/api-reference/track-refund): raw HTTP endpoint reference
- [Lead Tracking Guide](/docs/brand/tracking/lead-tracking-signup): implementation walkthrough
