Quickstart

This guide walks you through setting up a complete affiliate program. By the end, you’ll have tracking installed, an API key ready, and a working integration.

Prerequisites

A Stripe account (for payment tracking)
A website where you sell your product (for the tracking script)

Setup

Create your account

Sign up at agentref.co. No credit card required.After signing up, you’ll land on the onboarding flow that walks you through the next steps.

Connect Stripe

Click Connect Stripe in the onboarding flow. You’ll be redirected to Stripe’s OAuth page to authorize AgentRef.AgentRef uses Stripe Connect to:

Listen for payment events (checkout completions, invoice payments, refunds)
Match payments to affiliate referrals
Track subscription renewals for recurring commissions

AgentRef needs read access to your Stripe payment events. It does not process payments or access your bank account.

Create your program

After connecting Stripe, create your first affiliate program. Here are recommended starting settings:

Setting	Recommendation	Why
Commission type	`recurring`	Incentivizes affiliates to refer customers who stick around.
Commission rate	20–30%	Industry standard for SaaS. Competitive enough to attract affiliates.
Cookie duration	30 days	Balances fair attribution with reasonable conversion windows.
Payout threshold	$50	Low enough to keep affiliates motivated, high enough to avoid micro-payouts.
Payout frequency	Monthly	Standard cadence. Weekly is fine for high-volume programs.
Auto-approve affiliates	Yes	Reduces friction. You can always block bad actors later.

You can change all of these settings later. Start simple and adjust based on real data.

Install the tracking script

Add the AgentRef tracking script to your website. Place it in your <head> tag 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 the ID shown in your program settings.The script handles:

Capturing affiliate referral codes from URL parameters
Setting first-party attribution cookies (agentref_cid, agentref_pid, agentref_src)
Providing getCheckoutMetadata() for Stripe session integration

For Stripe Payment Links / Buy Buttons / Pricing Tables: No additional code needed. The tracking script instruments hosted Stripe surfaces with the click token via client_reference_id.For server-created Checkout Sessions: Pass the metadata to your server:

// Read referral context captured by the tracking script
const metadata = window.AgentRef.getCheckoutMetadata();
// Send metadata to your server along with the checkout request

const session = await stripe.checkout.sessions.create({
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  mode: 'subscription',
  metadata: metadata,                          // top-level metadata
  subscription_data: { metadata: metadata },   // subscription metadata
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
});

Get your API key

Go to Settings > API Keys in your AgentRef dashboard and create a new key.

Merchant keys start with ak_live_ and can access your programs, applications, affiliates, conversions, payouts, webhooks, and marketing resources based on selected scopes.

Keep your API key secret. Never expose it in client-side code, public repositories, or browser requests.

Make your first API call

Verify everything works by fetching your program stats:

curl -X GET https://www.agentref.co/api/v1/programs \
  -H "Authorization: Bearer ak_live_your_key_here"

import { AgentRef } from 'agentref';

const client = new AgentRef({ apiKey: 'ak_live_your_key_here' });

const programs = await client.programs.list();
console.log(programs);

from agentref import AgentRef

client = AgentRef(api_key='ak_live_your_key_here')

programs = client.programs.list()
print(programs)

You should see your program in the response. If you get a 401 error, double-check your API key.

Verify your setup

After completing the steps above, confirm everything is working:

Tracking script loaded. Open your website, open browser DevTools, and check the Network tab for a request to agentref.co/api/tracking/script.js. It should return 200.
Cookies set. Visit your site through a test referral link (create one in the dashboard). Check DevTools > Application > Cookies for agentref_cid and agentref_pid.
1. API responds. The API call from the previous step returns your program data.
Stripe connected. Your AgentRef dashboard shows the Stripe connection as active.

Use the Merchant MCP verify_tracking tool for an agent-assisted setup check, or call GET /api/v1/programs/{id}/tracking/status to inspect tracking health from REST/SDK.

What’s next

Agent Setup

Connect AgentRef to Claude, Codex, Cursor, OpenClaw, or any AI assistant.

Invite Affiliates

Start recruiting affiliates to your program.

Marketing Resources

Publish campaign material for affiliates.

API Reference

Explore the full REST API documentation.

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

Prerequisites

Setup

Verify your setup

What’s next

Agent Setup

Invite Affiliates

Marketing Resources

API Reference

​Prerequisites

​Setup

​Verify your setup

​What’s next

Agent Setup

Invite Affiliates

Marketing Resources

API Reference

Prerequisites

Setup

Verify your setup

What’s next