---
id: "brand/tracking/quickstart-integration"
type: "doc"
url: "https://affitor.com/docs/brand/tracking/quickstart-integration"
kind: "quickstart"
updated: "2026-11-08"
---
# 3-Step Integration Guide

> Get Affitor tracking live with the supported click, signup, and server-side tracking flows

Three steps get Affitor tracking live: clicks → signups → sales. Steps 1 and 2 establish attribution; step 3 records revenue.

<AgentPrompt prompt="Follow https://affitor.com/docs/skill.md to integrate Affitor. Program <PROGRAM_ID> on https://api.affitor.com. Key in AFFITOR_API_KEY.">
Using an AI coding agent? Set your program API key as the `AFFITOR_API_KEY` environment variable, then give your agent this line. It follows the [agent skill](/docs/skill.md) to add all three steps and verify them. In Settings, **API keys** shows the same line with your program ID filled in, under **Set up with your AI agent**.
</AgentPrompt>

## Before You Start

Make sure you have:

- Your **program ID**
- Your **program API key** for server-to-server calls
- A decision on how you will track sales (server-side tracking vs Stripe integration):
  - **Server-side tracking**: your backend calls `POST /api/v1/track/sale`, for any backend or payment provider
  - **Stripe integration**: attach Affitor metadata to Stripe Checkout sessions

:::note

Use one naming scheme consistently:
- `customerKey`: browser helper argument (`signup(customerKey, email)`)
- `customer_key`: tracking API field
- `affitor_customer_key`: Stripe metadata field

:::

---

## Step 1: Install the Tracker

Add the tracker to every page where affiliate traffic can land.

:::tip[Verifying the pipeline]

Once the tracker is live on your public site, Affitor detects it automatically, with no debug mode needed. To verify the full pipeline, run the synthetic `click → signup → sale` chain with `npx affitor onboard` or the MCP `affitor_run_verification` tool. See [Testing Integration](/docs/brand/tracking/testing-integration).

:::

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

Replace `YOUR_PROGRAM_ID` with your program ID (program menu → **Program settings** → **Business** → **Program ID**, **Copy**).

### What this does

- Detects affiliate visits through the `?via=` or `?aff=` parameter
- Creates a tracked customer / click relationship
- Stores `affitor_click_id` in a first-party cookie
- Sends click/pageview tracking data to Affitor

### Verify

Visit your site through a real affiliate link, or enable debug mode while testing. Debug mode also makes `signup()` send a test event instead of a lead, so turn it off before production. Then review:
- browser console / network requests
- Affitor dashboard → tracking/integration pages

---

## Step 2: Track Signups

After signup succeeds, tell Affitor which internal user was created.

### Option A: Browser-side helper

Use this when your signup flow runs in the browser and the tracker is already loaded.

```html
<script>
await window.affitor.signup('user_123', 'user@example.com');
</script>
```

Or inside your signup flow:

```html
<script>
document.getElementById('signup-form').addEventListener('submit', async function(e) {
  e.preventDefault();

  const email = document.getElementById('email').value;

  // Run your own signup logic first.
  // After account creation succeeds:
  await window.affitor.signup(currentUser.id, email);
});
</script>
```

**Use this when:**
- you already installed the tracker on the page
- signup happens in the browser
- you want the simplest supported flow

By default a browser-only lead is provisional: it does not count as a signup until your server sends the lead (Option B) or a Stripe Checkout payment for that customer arrives through your connected Stripe account. See [lead auth policy](/docs/brand/tracking/lead-tracking-signup/).

### Option B: Server-side lead API

Use this when signup logic lives on your backend or you want the server to own the tracking call.

```bash
POST https://api.affitor.com/api/v1/track/lead
Authorization: Bearer YOUR_PROGRAM_API_KEY
Content-Type: application/json

{
  "click_id": "cust_42_1234567890",
  "customer_key": "user_123",
  "email": "user@example.com"
}
```

```js
await fetch('https://api.affitor.com/api/v1/track/lead', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AFFITOR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    click_id: req.cookies.affitor_click_id,
    customer_key: newUser.id,
    email: newUser.email,
  }),
});
```

### Lead tracking rules

- Outside test mode, send the `click_id` from the `affitor_click_id` cookie: Affitor finds the customer through it. From your server, a first lead with only `customer_key` answers `400` `Customer not found. Provide a valid click_id or customer_key.`; from the browser, `click_id` is always required.
- For reliable payment attribution later, always send a stable internal customer ID:
  - `customerKey` in `signup()`
  - `customer_key` in the API
- Browser-side `signup()` is the easiest to add, but by default it stays provisional until the server-side lead or a Stripe Checkout payment through your connected Stripe account
- Server-side API is best when signup completes on your backend

**Response:**

```json
{
  "success": true,
  "message": "Lead tracked successfully"
}
```

---

## Step 3: Track Sales

When a customer pays, choose **one** revenue-tracking path.

### Option A: Server-side tracking (works with any payment provider)

Send a server-to-server request once payment succeeds.

**Endpoint:** `POST https://api.affitor.com/api/v1/track/sale`

```json
{
  "transaction_id": "txn_abc123",
  "customer_key": "user_123",
  "click_id": "cust_42_123456",
  "amount_cents": 9999,
  "currency": "USD",
  "sale_type": "payment",
  "is_recurring": false,
  "subscription_id": "sub_xyz",
  "subscription_interval": "monthly",
  "product_id": "prod_456",
  "line_items": [
    { "name": "Pro Plan", "amount_cents": 9999, "quantity": 1 }
  ]
}
```

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `transaction_id` | **Yes** | string | Unique transaction identifier used for deduplication |
| `amount_cents` | **Yes** | number | Positive integer amount in the currency's [minor unit](/docs/api-reference/track-sale#minor-units-and-conversion) (cents for USD) |
| `tax_cents` | No | number | The tax included in `amount_cents`. Commissions are calculated on `amount_cents - tax_cents` |
| `customer_key` | Conditional | string | Your internal customer ID |
| `click_id` | Conditional | string | Tracked click identifier |
| `currency` | No | string | A [supported ISO 4217 code](/docs/api-reference/track-sale#request-fields). Default: `USD` |
| `sale_type` | No | string | `payment` or `subscription`. Default: `payment` |
| `is_recurring` | No | boolean | Use `true` for recurring charges |
| `subscription_id` | No | string | External subscription ID |
| `subscription_interval` | No | string | e.g. `monthly`, `quarterly`, `annual` |
| `product_id` | No | string | External product identifier |
| `line_items` | No | array | Optional item breakdown |

```js
await fetch('https://api.affitor.com/api/v1/track/sale', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AFFITOR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transaction_id: order.id,
    customer_key: currentUser.id,
    click_id: req.cookies.affitor_click_id,
    amount_cents: order.totalCents,
    currency: 'USD',
    sale_type: 'payment',
  }),
});
```

**Response:**

```json
{
  "success": true,
  "sale_id": 42,
  "commission_id": 18,
  "message": "Sale tracked successfully"
}
```

:::note

`transaction_id` must be unique. Reusing the same value returns `409 Conflict`.

:::

### Option B: Stripe integration

If you already use Stripe Checkout, keep taking payment in your own Stripe account. Connect it under **Program settings** › **Payments** (Affitor receives its events through Stripe Connect, with no webhook to add), then attach Affitor metadata to the checkout session, and to `subscription_data.metadata` for a subscription. The code and the rules are on the [Stripe](/docs/brand/tracking/payment-tracking-stripe#option-b-stripe-integration) page.

---

## Which Sales Path Should You Use?

| Path | Best for |
|------|----------|
| **Server-side tracking**: `POST /api/v1/track/sale` | Any backend, any payment provider, custom checkout, Paddle/LemonSqueezy/manual server events |
| **Stripe integration** | Existing Stripe Checkout integration |

Use server-side tracking when your backend controls the revenue event. Use Stripe integration when you want Affitor to attribute sales directly from the payment events of your connected Stripe account.

---

## Verify it worked

<VerifySuccess
  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"]}
  network={["Your signup handler's `trackLead` call returns 2xx; with the Server API, your server's `trackSale` call on a test payment returns 2xx; with Stripe connected, a one-time test-mode payment shows under Commissions as Test"]}
  dashboard={["Click, lead, and sale all appear under your program's tracking events, or run `npx affitor onboard` to fire the whole synthetic chain in one command (it also offers to add a `trackSale` call; with Stripe connected, read [the CLI warning](/docs/brand/cli/commands#affitor-onboard) before accepting it)"]}
  ifNotWorking={["Use `additional_data: { test_mode: true }` so test events never create real commissions"]}
/>

## You're Done

All three steps working means your integration is live:

| Step | Event | Outcome |
|------|-------|---------|
| Tracker installed | Click/pageview tracking | affiliate visit captured |
| Signup tracked | Lead event | customer linked to partner |
| Sale tracked | Sale + commission flow | revenue attributed |

Next:
- [Testing Integration](/docs/brand/tracking/testing-integration/)
- [Stripe](/docs/brand/tracking/payment-tracking-stripe/)
- [Tracking Overview](/docs/brand/tracking/tracking-overview/)
