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

# Server-Side Tracking

> Record referral clicks server-side when JavaScript tracking isn't available.

Use server-side tracking when the JavaScript snippet isn't an option, such as mobile apps, server-rendered redirects, or checkout flows where your backend owns the attribution handoff.

Server-side tracking records the **click** and returns a `clickToken`. AgentRef does not expose a public `POST /api/v1/conversions` endpoint. Conversions are created by supported payment integrations, primarily Stripe, when the payment event includes the click token in metadata or `client_reference_id`.

## When to Use

* **Custom payment flows** that don't use Stripe Checkout
* **Mobile apps** or native clients
* **Server-rendered redirects** where you intercept the affiliate link yourself

## Workflow

<Steps>
  <Step title="Capture the referral parameter">
    When a visitor arrives with `?via=AFFILIATE_CODE`, extract the referral code server-side. Inbound attribution also accepts `ref`, `r`, `a`, and configured aliases.
  </Step>

  <Step title="Record the click">
    Call `POST /api/tracking/click` with the program ID, page URL, and referral code. The response includes a `clickToken`.
  </Step>

  <Step title="Store attribution">
    Persist the `clickToken` as `agentref_cid` and the program ID as `agentref_pid` in your session, database, or cookie.
  </Step>

  <Step title="Pass metadata to checkout">
    When the visitor converts through Stripe, pass `agentref_cid`, `agentref_pid`, and `agentref_source` into Stripe metadata, or use `client_reference_id` for hosted Stripe surfaces.
  </Step>
</Steps>

## Record a Click

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.agentref.co/api/tracking/click \
    -H "Content-Type: application/json" \
    -H "Origin: https://yourapp.com" \
    -d '{
      "programId": "550e8400-e29b-41d4-a716-446655440000",
      "pageUrl": "https://yourapp.com/?via=john",
      "referralCode": "john",
      "referrer": "https://blog.example.com/review",
      "consentGranted": true
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://www.agentref.co/api/tracking/click', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      // Must match the configured website domain for the program.
      Origin: 'https://yourapp.com',
    },
    body: JSON.stringify({
      programId: '550e8400-e29b-41d4-a716-446655440000',
      pageUrl: 'https://yourapp.com/?via=john',
      referralCode: 'john',
      referrer: 'https://blog.example.com/review',
      consentGranted: true,
    }),
  })

  const { clickToken, programId } = await response.json()
  // Store clickToken as agentref_cid and programId as agentref_pid.
  ```

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

  resp = requests.post(
      "https://www.agentref.co/api/tracking/click",
      headers={"Origin": "https://yourapp.com"},
      json={
          "programId": "550e8400-e29b-41d4-a716-446655440000",
          "pageUrl": "https://yourapp.com/?via=john",
          "referralCode": "john",
          "referrer": "https://blog.example.com/review",
          "consentGranted": True,
      },
  )
  click_token = resp.json()["clickToken"]
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "status": "ok",
  "affiliateCode": "john",
  "programId": "550e8400-e29b-41d4-a716-446655440000",
  "clickToken": "clk_a1b2c3d4e5",
  "cookieDurationDays": 30,
  "cookieDomain": "yourapp.com",
  "cleanupParams": ["ref"],
  "warnings": []
}
```

## Verify Tracking (Optional)

Confirm that a page can verify tracking for a program. This records an install-verification heartbeat; it does not require or accept a click token:

```bash theme={null}
curl -X POST https://www.agentref.co/api/tracking/verify \
  -H "Content-Type: application/json" \
  -H "Origin: https://yourapp.com" \
  -d '{
    "programId": "550e8400-e29b-41d4-a716-446655440000",
    "pageUrl": "https://yourapp.com/pricing",
    "consentGranted": true
  }'
```

## Pass Attribution to Stripe

When the visitor converts through Stripe, pass the stored click token into the same metadata fields used by the JavaScript snippet:

<CodeGroup>
  ```javascript Node.js theme={null}
  const agentrefMeta = {
    agentref_cid: clickToken,
    agentref_pid: programId,
    agentref_source: 'server_side',
  }

  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    line_items: [{ price: 'price_123', quantity: 1 }],
    success_url: 'https://yourapp.com/success',
    cancel_url: 'https://yourapp.com/cancel',
    metadata: agentrefMeta,
  })

  // For subscription checkout sessions, also set:
  // subscription_data: { metadata: agentrefMeta }
  ```

  ```python Python theme={null}
  agentref_meta = {
      "agentref_cid": click_token,
      "agentref_pid": program_id,
      "agentref_source": "server_side",
  }

  session = stripe.checkout.Session.create(
      mode="payment",
      line_items=[{"price": "price_123", "quantity": 1}],
      success_url="https://yourapp.com/success",
      cancel_url="https://yourapp.com/cancel",
      metadata=agentref_meta,
  )

  # For subscription checkout sessions, also set:
  # subscription_data={"metadata": agentref_meta}
  ```

  ```javascript Hosted Stripe surfaces theme={null}
  // For Payment Links, Buy Buttons, and Pricing Tables, use the click token
  // as the Stripe client_reference_id when your integration allows it.
  const clientReferenceId = clickToken
  ```
</CodeGroup>

<Warning>
  The click and verify endpoints are unauthenticated, but they validate `Origin` or `Referer` against the program's configured website domain. For backend calls, forward or set an origin that matches your configured site.
</Warning>

For more checkout examples, see [Stripe Checkout](/tracking/stripe-checkout).