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

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

2. Record the click

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

3. Store attribution

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

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

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

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:

Node.js

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 }

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.