Create Program

A program is the core unit in AgentRef. It defines how affiliates earn commissions, how long attribution cookies last, and when payouts happen. You can run multiple programs under one merchant account.

Create a program

Via the dashboard

After connecting Stripe, the onboarding flow walks you through creating your first program. You can also create additional programs from Programs > New Program at any time.

Via the API

curl -X POST https://www.agentref.co/api/v1/programs \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SaaS Affiliate Program",
    "commissionType": "recurring",
    "commissionPercent": 25,
    "cookieDuration": 30,
    "payoutThreshold": 5000,
    "payoutFrequency": "monthly",
    "autoApproveAffiliates": true,
    "currency": "usd"
  }'

import { AgentRef } from 'agentref';

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

const program = await client.programs.create({
  name: 'My SaaS Affiliate Program',
  commissionType: 'recurring',
  commissionPercent: 25,
  cookieDuration: 30,
  payoutThreshold: 5000,
  payoutFrequency: 'monthly',
  autoApproveAffiliates: true,
  currency: 'usd',
});

console.log(program.id);

from agentref import AgentRef

client = AgentRef(api_key="ak_live_YOUR_KEY")

program = client.programs.create(
    name="My SaaS Affiliate Program",
    commission_type="recurring",
    commission_percent=25,
    cookie_duration=30,
    payout_threshold=5000,
    payout_frequency="monthly",
    auto_approve_affiliates=True,
    currency="usd",
)

print(program.id)

Program settings

Required settings

Setting	Type	Description
`name`	string	Display name for your program. Shown to affiliates and in the marketplace. Max 100 characters.
`commissionType`	string	How commissions are calculated. See commission types below.
`commissionPercent`	number	Percentage of each sale the affiliate earns. Range: 1–100.

Optional settings

Setting	Default	Description
`description`	`null`	Program description (max 500 characters). Shown in marketplace listings.
`landingPageUrl`	`null`	Default URL where affiliate links redirect visitors.
`cookieDuration`	`30`	Days the attribution cookie persists. Range: 1–365.
`payoutThreshold`	`5000`	Minimum commission balance (in cents) before an affiliate is eligible for payout. Range: 1,000–100,000.
`payoutFrequency`	`monthly`	How often payouts are processed: `weekly`, `monthly`, or `quarterly`.
`autoApproveAffiliates`	`false`	Whether new affiliates are approved automatically or require manual review.
`commissionLimitMonths`	`null`	For `recurring_limited` type only. Number of months commissions are paid. Range: 1–36.
`portalSlug`	`null`	Custom slug for your affiliate portal URL. Lowercase alphanumeric and hyphens only.
`currency`	`usd`	Currency code for commissions and payouts.

The payoutThreshold is specified in cents. A value of 5000 means $50.00.

Commission types

AgentRef supports three commission models:

One-time (`one_time`)

The affiliate earns a commission on the first payment only. If a customer upgrades, renews, or makes additional purchases, no further commissions are generated. Best for: One-time purchases, lifetime deals, products without subscriptions.

Recurring (`recurring`)

The affiliate earns a commission on every payment the referred customer makes, for the lifetime of the subscription. If the customer pays monthly, the affiliate earns every month. Best for: SaaS with subscriptions. This is the most popular model because it incentivizes affiliates to refer customers who stick around.

Recurring with limit (`recurring_limited`)

Same as recurring, but commissions stop after a configured number of months (commissionLimitMonths). For example, 25% for the first 12 months. Best for: SaaS that wants to cap lifetime affiliate payouts while still rewarding ongoing referrals during the customer’s early months.

Type	First payment	Subsequent payments	Cap
`one_time`	Commission earned	No commission	N/A
`recurring`	Commission earned	Commission earned	None
`recurring_limited`	Commission earned	Commission earned	Stops after N months

Program status lifecycle

Every program has a status that controls whether it is actively tracking conversions:

Status	Behavior
`active`	Tracking is live. New clicks, conversions, and commissions are processed normally.
`paused`	Tracking stops. Existing data is preserved but no new conversions are created. Affiliate links still resolve but clicks are not recorded.
`archived`	Program is soft-deleted. It no longer appears in listings or API responses (unless explicitly filtered). Existing conversions and payouts are preserved for historical records.

Update a program’s status via the API:

curl -X PATCH https://www.agentref.co/api/v1/programs/PROGRAM_ID \
  -H "Authorization: Bearer ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

await client.programs.update('PROGRAM_ID', { status: 'paused' });

client.programs.update("PROGRAM_ID", status="paused")

Program readiness

AgentRef tracks whether your program is fully configured and ready to process conversions. The readiness field on a program can be:

Readiness	Meaning
`setup`	Initial state. Stripe is not connected and tracking is not installed.
`partial`	Some steps are complete but the program is not fully operational. For example, Stripe is connected but the tracking script has not been verified.
`ready`	Stripe is connected, tracking script is verified, and the program can process conversions end-to-end.

Check readiness via the API by fetching the program detail:

curl https://www.agentref.co/api/v1/programs/PROGRAM_ID \
  -H "Authorization: Bearer ak_live_YOUR_KEY"

const program = await client.programs.get('PROGRAM_ID');
console.log(program.readiness); // "setup" | "partial" | "ready"

program = client.programs.get("PROGRAM_ID")
print(program.readiness)  # "setup" | "partial" | "ready"

Recommended starting settings

If you are unsure where to start, these are industry-standard defaults for SaaS affiliate programs:

Setting	Recommendation	Why
Commission type	`recurring`	Incentivizes affiliates to refer customers who stick around.
Commission rate	20–30%	Competitive enough to attract affiliates. Industry standard for SaaS.
Cookie duration	30 days	Balances fair attribution with a reasonable conversion window.
Payout threshold	$50	Low enough to keep affiliates motivated, high enough to avoid micro-payouts.
Payout frequency	Monthly	Standard cadence. Weekly works for high-volume programs.
Auto-approve	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 performance data.

Getting Started

Merchant Guide

Agent Integration

Tracking

Integration Guides

Webhooks

For Affiliates

Resources

Create a program

Program settings

Required settings

Optional settings

Commission types

One-time (`one_time`)

Recurring (`recurring`)

Recurring with limit (`recurring_limited`)

Program status lifecycle

Program readiness

Recommended starting settings

What’s next

Connect Stripe

Install Tracking

​Create a program

​Program settings

​Required settings

​Optional settings

​Commission types

​One-time (one_time)

​Recurring (recurring)

​Recurring with limit (recurring_limited)

​Program status lifecycle

​Program readiness

​Recommended starting settings

​What’s next

Connect Stripe

Install Tracking

Create a program

Program settings

Required settings

Optional settings

Commission types

One-time (`one_time`)

Recurring (`recurring`)

Recurring with limit (`recurring_limited`)

Program status lifecycle

Program readiness

Recommended starting settings

What’s next