Skip to main content
Debug mode gives you a console readout of the tracking script’s state – what cookies are set, what parameters were detected, and whether anything went wrong during initialization.

​
Enabling debug mode

You can enable debug mode in two ways: Option 1: URL parameter (temporary, no code change) Append ?agentref_debug=1 to any page URL on your site: 
https://yoursite.com/pricing?ref=abc123&agentref_debug=1
Open the browser console – you’ll see an [AgentRef] log entry immediately after the script initializes. Option 2: Script attribute (always-on) Add data-debug="true" to your script tag to log on every page load: 
<script
  src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
  data-debug="true"
  async
></script>
Do not ship data-debug="true" to production. It logs tracking state to the browser console on every page visit, which is noisy for real users and exposes internal state.

​
What debug mode shows

The console output is the return value of window.AgentRef.getDebugInfo(). Here is an example: 
{
  "params": {
    "referralParam": "ref",
    "referralCode": "abc123",
    "clickToken": null,
    "debug": true,
    "subIds": { "sub1": null, "sub2": null, "sub3": null, "sub4": null, "sub5": null },
    "utm": { "utmSource": "twitter", "utmMedium": "social", "utmCampaign": null, "utmTerm": null, "utmContent": null },
    "adClickIds": { "gclid": null, "fbclid": null, "msclkid": null, "ttclid": null, "liFatId": null }
  },
  "cookies": {
    "clickToken": "clk_a1b2c3d4e5",
    "source": "script_direct",
    "programId": "550e8400-e29b-41d4-a716-446655440000",
    "visitorId": "v_k8m2n4p6q7",
    "timestamp": "1711234567890"
  },
  "lastResolution": {
    "clickToken": "clk_a1b2c3d4e5",
    "programId": "550e8400-e29b-41d4-a716-446655440000",
    "source": "script_direct"
  },
  "trackingScope": {
    "trackingDomain": "yoursite.com",
    "mode": "root"
  },
  "warnings": []
}

​
Field reference

FieldWhat it tells you
params.referralCodeThe affiliate code detected in the URL (null if none)
params.clickTokenPre-existing click token from a redirect URL (null for direct clicks)
cookies.clickTokenThe agentref_cid cookie value – this is what goes into Stripe metadata
cookies.programIdThe agentref_pid cookie – confirms which program the current attribution belongs to
trackingScope.mode"root" = cookies scoped to root domain; "host" = scoped to exact hostname only
warningsArray of warning codes if anything went wrong (empty = clean init)

​
Warning codes

WarningMeaning
consent_pendingConsent is required but not yet granted – tracking was skipped
host_outside_website_domainThe current hostname doesn’t match your program’s website domain
cleanup_failedURL parameter cleanup via history.replaceState failed
stripe_payment_link_rewrite_failedCould not append client_reference_id to a Stripe Payment Link
direct_click_failedThe click recording request to AgentRef failed
tracking_verify_failedThe verification request failed

​
Calling getDebugInfo() manually

You can call it any time from the browser console: 
window.AgentRef.getDebugInfo()
This is useful after navigation, after granting consent, or after a manual AgentRef.refresh() call – any time you want to see the current state without reloading the page.

​
Troubleshooting checklist

  1. Open the Network tab in DevTools and filter for script.js. Check the response status.
  2. A 404 means your ?pid= value is invalid or the program does not exist. Verify the program ID in your AgentRef dashboard.
  3. A 400 response with // Missing program ID means the ?pid= query string is missing entirely.
  4. Check for Content Security Policy (CSP) headers blocking https://www.agentref.co. Add it to your script-src and connect-src directives.
  1. Enable debug mode and check params.referralCode – if it’s null, no referral parameter was found in the URL. Make sure your affiliate link includes ?ref=<code>.
  2. Check warnings – consent_pending means consent mode is enabled and the visitor hasn’t granted consent yet.
  3. Check trackingScope.mode – if it’s "host" and your checkout is on a subdomain, cookies may not be shared across subdomains. Set your website URL in program settings to the root domain (e.g., yoursite.com not www.yoursite.com).
  4. If the referral code is present but no click token is in cookies, the click recording request may have failed. Check the Network tab for a failed POST to /api/tracking/click.
  1. Verify that getCheckoutMetadata() returns a non-empty object before checkout. Call it from the console: window.AgentRef.getCheckoutMetadata().
  2. Confirm the metadata is being passed to Stripe. Check the session object in your Stripe dashboard – look for agentref_cid in the metadata fields.
  3. For Payment Links, confirm the link on your page has data-agentref-instrumented="true" after the script loads – this attribute is set by the script when it successfully instruments a link.
  4. Check that your Stripe Connect integration is active in AgentRef. If the webhook is not receiving events, no conversions will be created.
AgentRef uses last-click attribution. If a visitor clicked multiple affiliate links before purchasing, the most recent click wins.Coupon codes take priority over click tokens – if the customer uses a coupon linked to a different affiliate, that affiliate gets credit regardless of which link the visitor clicked.Check the conversion detail in your dashboard to see which attribution method was used (click token vs. coupon code).