Skip to main content
AgentRef uses a lightweight, first-party JavaScript snippet combined with Stripe webhooks to track the entire affiliate journey. This page explains the full pipeline from click to commission.

​
The tracking pipeline

​
How clicks are tracked

When a visitor arrives on your site through an affiliate link (e.g., https://yoursite.com?ref=abc123), the tracking script:
  1. Detects the referral parameter. The script reads the ref parameter from the URL (or any custom aliases you configure).
  2. Records the click server-side. The script sends a request to AgentRef’s click endpoint with the referral code, page URL, UTM data, and ad-click IDs.
  3. Sets first-party cookies. On successful click recording, the script stores attribution data in cookies on your domain.
  4. Cleans up the URL. The ref parameter is removed from the browser address bar so it doesn’t leak into bookmarks or shared links.
The tracking script sets the following first-party cookies on the merchant’s domain:
CookiePurposeExample value
agentref_cidClick token for conversion matchingclk_a1b2c3d4e5
agentref_srcTraffic source identifierscript_direct
agentref_pidProgram ID550e8400-e29b-...
agentref_vidAnonymous visitor IDv_k8m2n4p6...
agentref_tsTimestamp of cookie creation1711234567890
Key characteristics:
  • First-party only. Cookies are set on your domain (e.g., .yoursite.com), not a third-party domain. This means they work reliably across browsers, including Safari’s ITP restrictions.
  • Configurable duration. Default is 30 days. You can change this per program in your program settings.
  • Root domain scoping. Cookies are scoped to your root domain, so they persist across subdomains (e.g., www.yoursite.com and app.yoursite.com).
  • Secure attributes. On HTTPS sites, cookies include the Secure flag. All cookies use SameSite=Lax.

​
Attribution logic

AgentRef uses last-click attribution – the industry-standard model for affiliate programs. When a payment comes in, AgentRef resolves the affiliate using this priority chain:
PriorityMethodHow it works
1Coupon codeIf the customer used a coupon linked to an affiliate, that affiliate gets credit regardless of click history.
2Click tokenThe agentref_cid from session metadata or client_reference_id is matched to the original click record.
If multiple affiliates drove clicks for the same visitor, the most recent click before conversion wins.
Coupon-based attribution always takes priority over click-based attribution. This means an affiliate with a coupon code gets credit even if the visitor originally arrived through a different affiliate’s link.

​
How conversions are created

Once a Stripe payment event fires, AgentRef processes it through the webhook pipeline:
1

Webhook received

Stripe sends checkout.session.completed (for new purchases) or invoice.paid (for subscription renewals) to AgentRef’s Connect webhook endpoint.
2

Metadata extracted

AgentRef reads agentref_cid, agentref_pid, and agentref_source from Stripe metadata for custom checkout flows. For hosted Stripe surfaces (Payment Links, Buy Buttons, Pricing Tables), it uses client_reference_id as the click-token anchor.
3

Affiliate resolved

Using the attribution priority chain above, AgentRef identifies which affiliate (if any) drove the sale.
4

Conversion recorded

A conversion record is created with status pending. The commission amount is calculated based on your program’s rate settings.
5

Fraud checks run

Automated fraud detection (duplicate clicks, self-referral, geographic anomalies) runs on the conversion. Suspicious conversions are flagged for review.

​
Integration points

ComponentWhat it doesRequired?
Tracking scriptCaptures clicks and sets cookies on your domainYes
Stripe ConnectSends payment events to AgentRef via webhooksYes
Checkout metadataPasses attribution cookies into Stripe sessionsDepends on checkout method
Consent modeRespects GDPR consent before setting cookiesOptional
Server-side trackingAPI-based click recording without the JS snippetOptional
Debug modeInspect tracking state and troubleshoot issuesOptional

​
What’s next

JavaScript Snippet

Install the tracking script on your site.

Stripe Checkout

Connect tracking to your Stripe checkout flow.