Server-Side Tracking

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

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.

Record the click

Call POST /api/tracking/click with the program ID, page URL, and referral code. The response includes a clickToken.

Store attribution

Persist the clickToken as agentref_cid and the program ID as agentref_pid in your session, database, or cookie.

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.

Record a Click

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
  }'

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.

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"]

Response:

{
  "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:

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:

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 }

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}

// 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

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.

For more checkout examples, see Stripe Checkout.

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

Server-Side Tracking

When to Use

Workflow

Record a Click

Verify Tracking (Optional)

Pass Attribution to Stripe

​When to Use

​Workflow

​Record a Click

​Verify Tracking (Optional)

​Pass Attribution to Stripe

When to Use

Workflow

Record a Click

Verify Tracking (Optional)

Pass Attribution to Stripe