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

# Links & Attribution

> How affiliate tracking links work and how clicks are attributed to you.

## Your Referral Link

Every affiliate gets a unique referral code. Your tracking link follows this format:

```
https://merchant-site.com/?via=YOUR_CODE
```

AgentRef-generated links default to `?via=YOUR_CODE`. Some programs may still expose `ref`, `r`, `a`, or merchant-configured aliases for inbound attribution.

When someone clicks your link, AgentRef:

1. Records the click with your affiliate ID
2. Sets a first-party cookie on the visitor's browser
3. Tracks the visitor across the cookie window (typically 30-90 days)
4. Attributes any conversion back to you

## Referral Code

Your referral code is set when you join a program. It's usually your name or brand:

```
https://example.com/?via=jane
https://example.com/?via=techreviewer
https://example.com/?via=ai-tools-blog
```

## Creating links via API

Affiliate API keys can create named tracking links for a joined program. Use `destination_path` for a merchant-approved path on the merchant website and `custom_slug` when you want a specific referral code for that link.

`destination_path` must be a relative path such as `/pricing` or `/blog/review`. It must be in the program's allowed destination list. `custom_slug` must be 3-32 lowercase letters, numbers, or hyphens.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://www.agentref.co/api/v1/me/links?program_id=PROGRAM_ID" \
    -H "Authorization: Bearer ak_aff_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-pricing-link" \
    -d '{
      "name": "Pricing page",
      "destination_path": "/pricing",
      "custom_slug": "jane-review"
    }'
  ```

  ```text MCP theme={null}
  create_link({
    program_id: "PROGRAM_ID",
    name: "Pricing page",
    destination_path: "/pricing",
    custom_slug: "jane-review",
    idempotency_key: "create-pricing-link"
  })
  ```
</CodeGroup>

## Updating links via API

The current update contract is narrower than the create contract. `PATCH /api/v1/me/links/{id}` accepts `name`, `targetUrl`, and `isActive`; it does not accept `destination_path` or `custom_slug`. Use `targetUrl` when you need to point an existing link at a full URL, and create a new link when you need a different approved destination path or custom slug.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://www.agentref.co/api/v1/me/links/LINK_ID?program_id=PROGRAM_ID" \
    -H "Authorization: Bearer ak_aff_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Pricing page - updated",
      "targetUrl": "https://merchant-site.com/pricing",
      "isActive": true
    }'
  ```

  ```javascript Node.js theme={null}
  await client.affiliateWorkspace.updateLink(
    'LINK_ID',
    {
      name: 'Pricing page - updated',
      targetUrl: 'https://merchant-site.com/pricing',
      isActive: true,
    },
    { programId: 'PROGRAM_ID' }
  );
  ```

  ```python Python theme={null}
  client.affiliate_workspace.update_link(
      "LINK_ID",
      name="Pricing page - updated",
      target_url="https://merchant-site.com/pricing",
      is_active=True,
      program_id="PROGRAM_ID",
  )
  ```
</CodeGroup>

## Cookie Duration

Each program sets a **cookie window** – the number of days a click stays valid. If a visitor clicks your link today and purchases within the window, you get credit.

| Typical Windows | Duration |
| --------------- | -------- |
| Short           | 30 days  |
| Standard        | 60 days  |
| Long            | 90 days  |

The merchant configures this per program.

## UTM & Sub-ID Tracking

You can append tracking parameters to your links for your own analytics:

```
https://example.com/?via=jane&utm_source=youtube&utm_campaign=review
https://example.com/?via=jane&sub1=header-banner&sub2=homepage
```

### Supported Parameters

| Parameter       | Description                                   |
| --------------- | --------------------------------------------- |
| `utm_source`    | Traffic source (youtube, twitter, newsletter) |
| `utm_medium`    | Medium (video, post, email)                   |
| `utm_campaign`  | Campaign name                                 |
| `utm_content`   | Content variant                               |
| `utm_term`      | Search term                                   |
| `sub1` - `sub5` | Custom sub-IDs for your own tracking          |

These are tracked per click and visible in your affiliate dashboard.

## Attribution Model

AgentRef uses **last-click attribution**: the last affiliate link clicked before conversion gets the commission. If a visitor clicks affiliate A's link, then later clicks affiliate B's link and purchases – affiliate B gets credit.

## Viewing Your Clicks

### In the Dashboard

Your dashboard shows click analytics: total clicks, unique visitors, click-through rates, and geographic breakdown.

### Via API

Use the affiliate self-serve clicks endpoint to inspect a specific reporting window:

<CodeGroup>
  ```javascript Node.js theme={null}
  const stats = await fetch(
    'https://www.agentref.co/api/v1/me/clicks?startDate=START_DATE&endDate=END_DATE',
    {
      headers: { Authorization: 'Bearer ak_aff_YOUR_KEY' },
    }
  ).then((r) => r.json());
  ```

  ```python Python theme={null}
  import httpx

  stats = httpx.get(
      "https://www.agentref.co/api/v1/me/clicks",
      headers={"Authorization": "Bearer ak_aff_YOUR_KEY"},
      params={"startDate": "START_DATE", "endDate": "END_DATE"},
  ).json()
  ```

  ```bash cURL theme={null}
  curl "https://www.agentref.co/api/v1/me/clicks?startDate=START_DATE&endDate=END_DATE" \
    -H "Authorization: Bearer ak_aff_YOUR_KEY"
  ```
</CodeGroup>

<Tip>
  Use sub-IDs (`sub1`-`sub5`) to track which content, placement, or campaign drives the most conversions. This helps you optimize your promotion strategy.
</Tip>