Skip to main content
Astro is a good fit for AgentRef because the tracking script can live in one shared layout and still cover static pages, islands, and Stripe embeds.

​
Before you start

  • Set the program website in AgentRef to the same root domain your Astro site uses.
  • Copy the exact script snippet from Settings -> Integration.
  • If checkout starts on a sibling subdomain, install the script there too.
Put the script in the shared layout you use across public pages. 
---
export interface Props {
  title: string;
}

const { title } = Astro.props;
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{title}</title>
    <script
      defer
      src="https://www.agentref.co/api/tracking/script.js?pid=YOUR_PROGRAM_ID"
    ></script>
  </head>
  <body>
    <slot />
  </body>
</html>
You do not need a separate Framer-style helper script in Astro. AgentRef already watches the DOM for late-rendered Stripe links, Buy Buttons, and Pricing Tables.

​
Checkout compatibility in Astro

Checkout patternRecommendation
Stripe Payment Links, Buy Buttons, or Pricing Tables embedded in Astro pagesSupported directly.
Custom server-created Stripe Checkout SessionSupported, but you must pass AgentRef metadata into Stripe on the server.
External checkout on another root domainNot automatic. Keep checkout on the same root or build an intentional server-side handoff.
  • Shared subdomains on one root can work well if AgentRef is installed everywhere the journey can begin.
  • If you use a consent banner script, call window.AgentRef.setConsent('granted') after opt-in.
  • If you run a strict CSP, allow https://www.agentref.co for script-src and connect-src.

​
Verify the installation

1

Publish a real page with the script

Make sure the layout change is on the deployed site, not just in local preview.
2

Run a referral visit

Use a real affiliate link and confirm the AgentRef cookies appear.
3

Run debug mode

Add ?agentref_debug=1 and inspect the console output.
4

Confirm diagnostics in AgentRef

Use the tracking health panel or verify_tracking.

​
Troubleshooting

  • The script exists in the layout but cookies never appear: check whether the program website in AgentRef matches the live domain.
  • Clicks arrive but Stripe conversions do not: your checkout backend still needs the Stripe guide.
  • The script works locally but not in production: verify the deployed layout actually includes the script and that no CSP blocks it.

Stripe Checkout

Metadata bridge for custom Stripe sessions.

JavaScript Snippet

Full tracking-script reference.

Debug Mode

Inspect hosted Stripe instrumentation and warnings.