> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How Tracking Works

> Conceptual overview of AgentRef's click-to-commission tracking pipeline – cookie-based attribution, Stripe webhook matching, and the full conversion flow.

AgentRef uses a lightweight, first-party JavaScript snippet combined with Stripe webhooks to track the entire affiliate journey. This page explains the full pipeline from click to commission.

## The tracking pipeline

```mermaid theme={null}
graph TD
    A["Affiliate shares referral link"] --> B["Visitor clicks link"]
    B --> C["Tracking script loads on merchant site"]
    C --> D["Script records click + sets first-party cookies"]
    D --> E["Visitor browses the site"]
    E --> F["Visitor purchases via Stripe"]
    F --> G["Stripe webhook fires to AgentRef"]
    G --> H["AgentRef matches metadata to click"]
    H --> I["Conversion created, commission calculated"]
```

## How clicks are tracked

When a visitor arrives on your site through an affiliate link (e.g., `https://yoursite.com?via=abc123`), the tracking script:

1. **Detects the referral parameter.** Generated links use `via` by default. The script also accepts `ref`, `r`, `a`, and any [custom aliases](/tracking/javascript-snippet#url-parameters) you configure.

2. **Records the click server-side.** The script sends a request to AgentRef's click endpoint with the referral code, page URL, UTM data, and ad-click IDs.

3. **Sets first-party cookies.** On successful click recording, the script stores attribution data in cookies on your domain.

4. **Cleans up the URL.** The referral parameter is removed from the browser address bar so it doesn't leak into bookmarks or shared links.

## Cookie details

The tracking script sets the following first-party cookies on the merchant's domain:

| Cookie         | Purpose                             | Example value       |
| -------------- | ----------------------------------- | ------------------- |
| `agentref_cid` | Click token for conversion matching | `clk_a1b2c3d4e5`    |
| `agentref_src` | Traffic source identifier           | `script_direct`     |
| `agentref_pid` | Program ID                          | `550e8400-e29b-...` |
| `agentref_vid` | Anonymous visitor ID                | `v_k8m2n4p6...`     |
| `agentref_ts`  | Timestamp of cookie creation        | `1711234567890`     |

**Key characteristics:**

* **First-party only.** Cookies are set on your domain (e.g., `.yoursite.com`), not a third-party domain. This means they work reliably across browsers, including Safari's ITP restrictions.
* **Configurable duration.** Default is 30 days. You can change this per program in your program settings.
* **Root domain scoping.** Cookies are scoped to your root domain, so they persist across subdomains (e.g., `www.yoursite.com` and `app.yoursite.com`).
* **Secure attributes.** On HTTPS sites, cookies include the `Secure` flag. All cookies use `SameSite=Lax`.

## Attribution logic

AgentRef uses **last-click attribution** – the industry-standard model for affiliate programs. When a payment comes in, AgentRef resolves the affiliate using this priority chain:

| Priority | Method          | How it works                                                                                                  |
| -------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
| 1        | **Coupon code** | If the customer used a coupon linked to an affiliate, that affiliate gets credit regardless of click history. |
| 2        | **Click token** | The `agentref_cid` from session metadata or `client_reference_id` is matched to the original click record.    |

If multiple affiliates drove clicks for the same visitor, the most recent click before conversion wins.

<Note>
  Coupon-based attribution always takes priority over click-based attribution. This means an affiliate with a coupon code gets credit even if the visitor originally arrived through a different affiliate's link.
</Note>

## How conversions are created

Once a Stripe payment event fires, AgentRef processes it through the webhook pipeline:

<Steps>
  <Step title="Webhook received">
    Stripe sends `checkout.session.completed` (for new purchases) or `invoice.paid` (for subscription renewals) to AgentRef's Connect webhook endpoint.
  </Step>

  <Step title="Metadata extracted">
    AgentRef reads `agentref_cid`, `agentref_pid`, and `agentref_source` from Stripe metadata for custom checkout flows. For hosted Stripe surfaces (`Payment Links`, `Buy Buttons`, `Pricing Tables`), it uses `client_reference_id` as the click-token anchor.
  </Step>

  <Step title="Affiliate resolved">
    Using the attribution priority chain above, AgentRef identifies which affiliate (if any) drove the sale.
  </Step>

  <Step title="Conversion recorded">
    A conversion record is created with status `pending`. The commission amount is calculated based on your program's rate settings.
  </Step>

  <Step title="Fraud checks run">
    Automated fraud detection (duplicate clicks, self-referral, geographic anomalies) runs on the conversion. Suspicious conversions are flagged for review.
  </Step>
</Steps>

## Integration points

| Component                                        | What it does                                     | Required?                  |
| ------------------------------------------------ | ------------------------------------------------ | -------------------------- |
| [Tracking script](/tracking/javascript-snippet)  | Captures clicks and sets cookies on your domain  | Yes                        |
| [Stripe Connect](/merchant-guide/connect-stripe) | Sends payment events to AgentRef via webhooks    | Yes                        |
| [Checkout metadata](/tracking/stripe-checkout)   | Passes attribution cookies into Stripe sessions  | Depends on checkout method |
| [Consent mode](/tracking/consent-gdpr)           | Respects GDPR consent before setting cookies     | Optional                   |
| [Server-side tracking](/tracking/server-side)    | API-based click recording without the JS snippet | Optional                   |
| [Debug mode](/tracking/debug-mode)               | Inspect tracking state and troubleshoot issues   | Optional                   |

## What's next

<CardGroup cols={2}>
  <Card title="JavaScript Snippet" icon="code" href="/tracking/javascript-snippet">
    Install the tracking script on your site.
  </Card>

  <Card title="Stripe Checkout" icon="credit-card" href="/tracking/stripe-checkout">
    Connect tracking to your Stripe checkout flow.
  </Card>
</CardGroup>