Skip to main content
The tracking script is a lightweight JavaScript snippet that runs on your domain. It captures affiliate referral codes from URL parameters, sets first-party attribution cookies, and passes referral metadata to Stripe during checkout.

​
Quick install

Add this script tag to every page where you want to track affiliate visits. Place it in your <head> or before the closing </body> tag: 
<script
  src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
  defer
></script>
Replace YOUR_PROGRAM_ID with your program’s ID from the dashboard or API. That’s it. For most setups, this single script tag handles everything.

​
Framework examples

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
  <script
    src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
    defer
  ></script>
</head>
<body>
  <!-- Your site content -->
</body>
</html>

​
What the script does

When loaded, the tracking script performs these steps automatically:
  1. Reads URL parameters. Checks for ref, via, or any custom tracking parameter aliases you’ve configured. If found, this is an affiliate referral.
  2. Sets first-party cookies. Stores attribution data on your domain:
    • agentref_cid – a click identifier used for conversion matching
    • agentref_src – the traffic source (e.g., link, coupon)
    • agentref_pid – the active program ID
  3. Records the click. Sends a click event to AgentRef’s tracking endpoint. This appears in your analytics immediately.
  4. Exposes window.AgentRef. Provides a client-side API for reading referral metadata during checkout.
The script uses only first-party cookies on your domain. It does not use third-party cookies, fingerprinting, or local storage.

​
Passing metadata to Stripe

The tracking script sets cookies, but conversions are matched through Stripe metadata. How metadata reaches Stripe depends on your checkout integration: No additional server code needed. The tracking script automatically instruments Stripe-hosted surfaces with the click token via client_reference_id.

​
Server-created Checkout Sessions

For Checkout Sessions you create on your backend, read the metadata from the tracking script on the client side and send it to your server: 
// Read referral context captured by the tracking script
const metadata = window.AgentRef.getCheckoutMetadata();
// Returns: { agentref_cid: "clk_abc123", agentref_pid: "550e8400-e29b-41d4-a716-446655440000", agentref_source: "redirect" } or {} if no referral

// Send to your server with the checkout request
const response = await fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ metadata }),
});
For subscriptions, always set metadata on both the session and subscription_data. This ensures AgentRef can attribute the initial checkout and all recurring invoice payments.

​
Direct charges (Payment Intents)

If you create Payment Intents directly instead of using Checkout Sessions: 
const paymentIntent = await stripe.paymentIntents.create({
  amount: 2000,
  currency: 'usd',
  metadata: metadata, // Include agentref_cid
});

​
Verify your installation

After installing the script, verify that tracking is working correctly.

​
Browser check

  1. Open your website in a browser.
  2. Open DevTools > Network tab.
  3. Look for a request to agentref.co/api/tracking/script.js – it should return 200.
  4. Visit your site through a test referral link (create one in the dashboard).
  5. Check DevTools > Application > Cookies for agentref_cid and agentref_pid.

​
API check

Use the tracking status endpoint to verify your setup programmatically: 
curl https://www.agentref.co/api/v1/programs/PROGRAM_ID/tracking/status \
  -H "Authorization: Bearer ak_live_YOUR_KEY"
The response includes:
FieldDescription
stripeConnectedWhether Stripe is connected to this program.
trackingScriptVerifiedWhether the tracking script has been detected on your domain.
websiteConfiguredWhether a landing page URL is set.
clicksLast7DaysClick counts broken down by type (redirect, direct).
conversionsLast30DaysConversion counts broken down by attribution method.

​
Troubleshooting

ProblemSolution
Script returns 404Double-check your program ID in the pid parameter.
Cookies not being setMake sure the script is loading on the same domain where users check out. Cross-domain cookies will not work.
window.AgentRef is undefinedThe script has not loaded yet. Make sure you access it after the script loads (e.g., on a button click, not immediately on page load).
Conversions not appearingVerify that agentref_cid is present in your Stripe session metadata. Check Stripe’s event logs to confirm the metadata is attached.
Ad blockers blocking the scriptThe script is served from agentref.co. Some aggressive ad blockers may block it. Consider using a custom tracking domain for better reliability.

​
What’s next

How Tracking Works

Deep dive into the tracking architecture, cookie mechanics, and attribution logic.

Invite Affiliates

Start recruiting affiliates to your program.