Skip to main content
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

1

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.
2

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"
  }'

​
Program settings

​
Required settings

SettingTypeDescription
namestringDisplay name for your program. Shown to affiliates and in the marketplace. Max 100 characters.
commissionTypestringHow commissions are calculated. See commission types below.
commissionPercentnumberPercentage of each sale the affiliate earns. Range: 1–100.

​
Optional settings

SettingDefaultDescription
descriptionnullProgram description (max 500 characters). Shown in marketplace listings.
landingPageUrlnullDefault URL where affiliate links redirect visitors.
cookieDuration30Days the attribution cookie persists. Range: 1–365.
payoutThreshold5000Minimum commission balance (in cents) before an affiliate is eligible for payout. Range: 1,000–100,000.
payoutFrequencymonthlyHow often payouts are processed: weekly, monthly, or quarterly.
autoApproveAffiliatestrueWhether new affiliates are approved automatically or require manual review.
commissionLimitMonthsnullFor recurring_limited type only. Number of months commissions are paid. Range: 1–36.
portalSlugnullCustom slug for your affiliate portal URL. Lowercase alphanumeric and hyphens only.
currencyusdCurrency 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.
TypeFirst paymentSubsequent paymentsCap
one_timeCommission earnedNo commissionN/A
recurringCommission earnedCommission earnedNone
recurring_limitedCommission earnedCommission earnedStops after N months

​
Program status lifecycle

Every program has a status that controls whether it is actively tracking conversions:
StatusBehavior
activeTracking is live. New clicks, conversions, and commissions are processed normally.
pausedTracking stops. Existing data is preserved but no new conversions are created. Affiliate links still resolve but clicks are not recorded.
archivedProgram 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"}'

​
Program readiness

AgentRef tracks whether your program is fully configured and ready to process conversions. The readiness field on a program can be:
ReadinessMeaning
setupInitial state. Stripe is not connected and tracking is not installed.
partialSome steps are complete but the program is not fully operational. For example, Stripe is connected but the tracking script has not been verified.
readyStripe 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"
If you are unsure where to start, these are industry-standard defaults for SaaS affiliate programs:
SettingRecommendationWhy
Commission typerecurringIncentivizes affiliates to refer customers who stick around.
Commission rate20–30%Competitive enough to attract affiliates. Industry standard for SaaS.
Cookie duration30 daysBalances fair attribution with a reasonable conversion window.
Payout threshold$50Low enough to keep affiliates motivated, high enough to avoid micro-payouts.
Payout frequencyMonthlyStandard cadence. Weekly works for high-volume programs.
Auto-approveYesReduces 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.

​
What’s next

Connect Stripe

Link your Stripe account if you haven’t already.

Install Tracking

Add the tracking script to your website to start capturing clicks.