Skip to main content
Next.js is one of the cleanest AgentRef integrations because you can install the tracking script once in a shared layout and cover the whole app.

​
Before you start

  • In AgentRef, set the program website to the same root domain your Next.js app serves.
  • Copy the exact script snippet from Settings -> Integration.
  • If you split traffic between www.example.com and app.example.com, install the script on both surfaces if either one can receive affiliate traffic or start checkout.
Use next/script in app/layout.tsx so the script loads once for the whole application.
import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}
Do not append the script from a React effect unless you have a strong reason. In Next.js, next/script is the cleanest and least error-prone installation path.

​
Checkout compatibility in Next.js

Checkout patternRecommendation
Stripe Payment Links, Buy Buttons, or Pricing Tables rendered in your appSupported directly. Keep the AgentRef script on the same page.
Server-created Checkout Sessions in API routes, server actions, or route handlersSupported, but you must bridge window.AgentRef.getCheckoutMetadata() into Stripe metadata. Use the Stripe guide.
Checkout starts on a different root domainFirst-party cookies will not carry across roots. Move the flow onto one root or build a server-side handoff intentionally.
  • If you use a cookie banner, call window.AgentRef.setConsent('granted') after the visitor accepts tracking. See Consent and GDPR.
  • If you use a Content Security Policy, allow https://www.agentref.co in script-src and connect-src.
  • If your marketing site and app live on sibling subdomains, install AgentRef on both when both can begin the journey.

​
Verify the installation

1

Run a real affiliate click

Open a live test link from AgentRef and land on your Next.js app.
2

Check browser cookies

Confirm that agentref_cid and agentref_pid exist in DevTools.
3

Use debug mode

Add ?agentref_debug=1 to the URL and inspect the browser console.
4

Check AgentRef diagnostics

Open the tracking health panel or call /api/v1/programs/:id/tracking/status.

​
Troubleshooting

  • window.AgentRef is undefined: the script has not loaded yet. Trigger checkout only after the page is interactive.
  • Cookies exist on www but not in your app subdomain: install the script on both subdomains and make sure the program website points at the shared root.
  • Clicks are recorded but conversions are missing: your Next.js checkout path probably creates Stripe sessions server-side and still needs the Stripe metadata bridge.

Stripe Checkout

Custom Checkout Session metadata bridge for Next.js backends.

JavaScript Snippet

Full cookie, parameter, and API behavior.

Consent and GDPR

Gate tracking until the visitor grants consent.