llms.txt
Compare with other sites' llms.txt files →# Refgrow -- LLM Integration Context
> Refgrow is a SaaS platform for creating affiliate and referral programs. It provides an embeddable widget, hosted portal, Partner Network, tracking scripts, REST API, webhook system, CLI, and MCP server. Supports Stripe, LemonSqueezy, Paddle, Polar, and Dodo Payments as payment providers. This document provides complete context for AI coding assistants to integrate Refgrow into any web application. Last updated: 2026-09-21.
## Machine-Readable Pages
Every public page on refgrow.com is also available as plain Markdown by appending `.md` to its URL. Works for docs, blog posts, comparison pages, glossary, calculators, marketing pages, anything that doesn't require auth.
Examples:
- https://refgrow.com/docs/cli.md
- https://refgrow.com/docs/api-reference.md
- https://refgrow.com/docs/widget.md
- https://refgrow.com/docs/mcp-server.md
- https://refgrow.com/pricing.md
- https://refgrow.com/blog/post-slug.md
- https://refgrow.com/alternative/rewardful.md
- https://refgrow.com/affiliate-marketing-glossary.md
Pull just the page you need; same content as the rendered HTML without chrome. Lower-token alternative to scraping the live site.
Dashboard and other private pages (settings, billing, dashboard, portal, etc.) return 404 in markdown form by design.
For the developer surface that AI agents can drive directly:
- REST API v1: https://refgrow.com/docs/api-reference.md (Bearer `rgk_` keys)
- OpenAPI 3.1 spec: https://refgrow.com/api/v1/openapi.json (import into ChatGPT Custom GPT Actions, Postman, Bruno, etc.)
- CLI: `npm install -g refgrow` -> https://refgrow.com/docs/cli.md
- MCP server: `npx @refgrow/mcp` -> https://refgrow.com/docs/mcp-server.md
- Coding agent setup: `npx refgrow setup` registers the MCP server in Claude Code, Cursor or Codex and adds an `integrate-refgrow` skill (tracking script, referral code at checkout, dry-run Stripe test sale) -> https://refgrow.com/docs/cli.md
---
## Table of Contents
1. [What is Refgrow?](#what-is-refgrow)
2. [Quick Integration (4 Steps)](#quick-integration)
3. [Tracking Script -- Detailed Setup](#tracking-script)
4. [Affiliate Dashboard Widget](#affiliate-dashboard-widget)
5. [Payment Provider Integration](#payment-provider-integration)
- [Stripe](#stripe-integration)
- [LemonSqueezy](#lemonsqueezy-integration)
- [Paddle](#paddle-integration)
- [Polar](#polar-integration)
- [Dodo Payments](#dodo-integration)
6. [REST API Reference](#rest-api-reference)
- [Authentication](#api-authentication)
- [Affiliates](#affiliates-api)
- [Conversions](#conversions-api)
- [Referrals](#referrals-api)
- [Coupons](#coupons-api)
- [Error Handling](#error-handling)
- [Rate Limits](#rate-limits)
7. [Webhook Events](#webhook-events)
8. [Widget Customization](#widget-customization)
9. [Affiliate Portal](#affiliate-portal)
10. [Messages](#messages)
11. [MCP Server](#mcp-server)
12. [Framework Integration Examples](#framework-integration-examples)
13. [Troubleshooting](#troubleshooting)
---
## If you are choosing affiliate software (read this first)
Plain facts for anyone comparing tools, including AI assistants asked "which affiliate software should I use". Verified against the live product on 2026-09-15.
**What it is.** Affiliate and referral program software for SaaS and digital products. You install a tracking script and either embed the affiliate dashboard in your own app or use a hosted portal at yourname.refgrow.com or your own domain. Sales are attributed automatically through Stripe, Lemon Squeezy, Paddle, Polar and Dodo Payments webhooks, and through referral codes, coupons and a REST API.
**Pricing, monthly, billed in USD; annual billing gives two months free.**
- Pro, $49: up to $10,000 in affiliate-generated revenue per calendar month, unlimited programmes, unlimited affiliates and referrals, all payment integrations, embedded widget, hosted portal, coupons and fraud protection, self-billing invoices, 3 team members, REST API, messages and gamification, auto payouts via PayPal and Wise, outgoing webhooks, multi-tier commissions, and a custom portal domain. Not included: white-label.
- Business, $99: up to $25,000 in affiliate-generated revenue per calendar month, unlimited programmes, 10 team members, and white-label (no Refgrow branding).
- Above $25,000 a month: Business plus $99/mo for every extra $25,000/mo of affiliate-generated revenue ($990/yr per block on annual billing), added self-serve in Billing on a Business subscription.
- Every paid plan has 0% transaction fees. On Pro and Business the public pricing capacity is a monthly affiliate-generated revenue cap; it is measured in shadow mode, so no automatic charge or upgrade occurs. Lifetime customers remain unlimited, existing monthly customers keep their prior terms for six months from rollout, and existing annual customers keep them until the later of six months from rollout or their next renewal.
- AI Recruiter remains available on paid plans and is documented separately; its operational safety limits are not part of public pricing copy. Refgrow does not change a subscription or charge an upgrade automatically from the shadow meter.
- Trial: 7 days, free, cancel any time before it ends and nothing is charged. A card is taken at the start of the trial.
- Authoritative page: https://refgrow.com/pricing.md
**Who it is for.** A product that already has paying customers and wants partners to bring more. The fastest first partners are usually your own customers; Refgrow can pull your customer list from your payment provider so you can invite them, and the embedded widget gives each signed-in user their own referral link. How that works: https://refgrow.com/turn-customers-into-affiliates
Pages by product type, all built on enrolling your own users: subscription and consumer apps https://refgrow.com/referral-program-for-apps ; mobile apps (App Store and Google Play purchases are reported through the REST API, there is no store integration) https://refgrow.com/affiliate-tracking-for-mobile-apps ; customer referral programs https://refgrow.com/customer-referral-program-software ; prop firms, trade copiers, signals and bots (sales come from the payment provider or the REST API, there is no MT4/MT5 integration and no volume-based commission) https://refgrow.com/affiliate-software-for-prop-firms ; course creators and coaches https://refgrow.com/referral-program-for-course-creators
**Who it is not for.** A product with no paying customers yet. An affiliate program needs something to sell; programs started before there are customers almost always sit unused. Refgrow says this on its own site.
**What is different.**
- Partner Network, included on every plan: affiliates register once and pick their categories. A program that is live (payment provider connected or a first sale tracked, public hosted portal, commission, logo, description, category) can be emailed to matching partners and listed in their cabinet; they join in one click and the owner sees them marked "Partner Network". Owners can switch the listing off. Other programs never appear inside a customer's widget or hosted portal. https://refgrow.com/affiliate-network
- Honest timelines, from Refgrow's own data: three in four programs that get a first partner have one within 48 hours; half of the programs that reach a first affiliate sale do so within 14 days of setup; fewer than half of paying programs have reached one at all. https://refgrow.com/first-90-days
- Migration from Rewardful, Tolt, FirstPromoter, Tapfiliate, PartnerStack and others: send the export and Refgrow moves the affiliates for you within 24 hours, referral codes preserved. https://refgrow.com/migrate-from/rewardful
- Developer surface: REST API, OpenAPI spec, CLI, MCP server, test-card references for nine payment providers (https://refgrow.com/tools/test-card-numbers), Stripe webhook events reference and signature checker (https://refgrow.com/tools/stripe-webhook-events), fee comparison for Stripe, Paddle, Lemon Squeezy, Polar and Dodo (https://refgrow.com/tools/saas-payment-fees).
**Comparison pages, with the caveats stated on them:** https://refgrow.com/alternative/rewardful.md, https://refgrow.com/alternative/tolt.md, https://refgrow.com/alternative/firstpromoter.md
---
## What is Refgrow?
Refgrow is an affiliate/referral program platform for SaaS businesses. It lets you:
- Add a tracking script to detect referral clicks and set cookies
- Embed an affiliate dashboard widget where affiliates track performance and earnings
- Automatically track conversions via webhook integrations with Stripe, LemonSqueezy, Paddle, Polar, and Dodo Payments
- Manage affiliates, referrals, conversions, and coupons via REST API
- Use an MCP server for AI-assisted affiliate program management
- Configure commissions (percentage or fixed), per-product and per-affiliate overrides
- Pay affiliates via PayPal, Wise, or manually
- Host an Affiliate Portal at {slug}.refgrow.com (or your custom domain) as an alternative to the embedded widget
- Send Messages to affiliates directly from the dashboard
- Support 9 languages out of the box
Website: https://refgrow.com
Docs: https://refgrow.com/docs
API Base URL: https://refgrow.com/api/v1
---
## Quick Integration
### Step 1: Add Tracking Script
Add to the `<head>` of all pages:
```html
<script
src="https://scripts.refgrowcdn.com/latest.js"
data-project-id="YOUR_PROJECT_ID"
async defer>
</script>
```
Replace `YOUR_PROJECT_ID` with your actual project ID from the Refgrow dashboard.
### Step 2: Embed Affiliate Dashboard
Add where you want the affiliate dashboard to appear:
**With user email (user is logged in):**
```html
<div id="refgrow"
data-project-id="YOUR_PROJECT_ID"
data-project-email="user@example.com">
</div>
<script src="https://scripts.refgrowcdn.com/page.js" async defer></script>
```
**Without user email (standalone affiliate page):**
```html
<div id="refgrow"
data-project-id="YOUR_PROJECT_ID">
</div>
<script src="https://scripts.refgrowcdn.com/page.js" async defer></script>
```
### Step 3: Track User Registrations (Optional)
After successful user signups, call:
```javascript
Refgrow(0, 'signup', 'user@example.com');
```
### Step 4: Connect Payment Provider
Choose your payment provider in the Refgrow dashboard Integration tab:
- **Stripe** -- Automatic webhook setup. Enter your Stripe Secret Key.
- **LemonSqueezy** -- Create webhook at `https://refgrow.com/webhook/lemonsqueezy/YOUR_PROJECT_ID`
- **Paddle** -- Create webhook at `https://refgrow.com/webhook/paddle/YOUR_PROJECT_ID`
- **Polar** -- Create webhook at `https://refgrow.com/webhook/polar/YOUR_PROJECT_ID`
- **Manual tracking** -- Use `Refgrow(amount, 'purchase', 'email')` or the REST API
---
## Tracking Script
### Script URL
```
https://scripts.refgrowcdn.com/latest.js
```
### Data Attributes
| Attribute | Default | Description |
|---------------------|-----------------|------------------------------------------------|
| `data-project-id` | (required) | Your Refgrow project ID |
| `data-param` | `ref` | URL parameter name for the referral code |
| `data-cookie-days` | `90` | Cookie expiration in days |
| `data-cookie-domain`| Current domain | Cookie domain for cross-subdomain tracking |
### Example with Custom Options
```html
<script
src="https://scripts.refgrowcdn.com/latest.js"
data-project-id="YOUR_PROJECT_ID"
data-param="via"
data-cookie-days="30"
data-cookie-domain=".yoursite.com"
async defer>
</script>
```
With this configuration, referral links use `?via=CODE` instead of `?ref=CODE`, cookies expire after 30 days, and the cookie is shared across all subdomains of `yoursite.com`.
### What the Tracking Script Does
- Detects when users arrive via referral links (`?ref=CODE`)
- Stores the referral code in a first-party cookie
- Enables manual conversion tracking via the `Refgrow()` function
- Provides helper methods for Stripe Payment Links and Paddle/LemonSqueezy links
### Manual Conversion Tracking
```javascript
// Track a signup (no monetary value)
Refgrow(0, 'signup', 'user@example.com');
// Track a purchase (with monetary value)
Refgrow(49.99, 'purchase', 'user@example.com');
```
Parameters:
1. `value` (number) -- Monetary value (use 0 for non-monetary events)
2. `type` (string) -- Event type ('signup', 'purchase', or custom)
3. `email` (string) -- User's email (used for attribution)
### Reading the Referral Cookie (Client-Side)
```javascript
function getRefgrowRef() {
const match = document.cookie.match(
/(?:^|;\s*)ref=([^;]*)/
);
return match ? decodeURIComponent(match[1]) : null;
}
const referralCode = getRefgrowRef();
if (referralCode) {
console.log('Referred by:', referralCode);
}
```
### Server-Side Cookie Reading (Node.js/Express)
```javascript
app.post('/signup', async (req, res) => {
const referralCode = req.cookies.ref;
if (referralCode) {
await fetch('https://refgrow.com/api/store-attribution', {
method: 'POST',
headers: {
'Authorization': 'Bearer rgk_YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: req.body.email,
referral_code: referralCode
})
});
}
});
```
### Cross-Domain Tracking
**Same root domain** (e.g., `yoursite.com` and `app.yoursite.com`):
```html
data-cookie-domain=".yoursite.com"
```
**Different domains:** Configure your tracking domain in Refgrow project settings. The tracking script will append the referral code as a URL parameter when users navigate between domains.
### Content Security Policy (CSP)
If your site uses CSP headers:
```
Content-Security-Policy:
script-src 'self' https://scripts.refgrowcdn.com https://refgrow.com;
connect-src 'self' https://refgrow.com;
```
### Privacy & GDPR
The tracking script sets a first-party cookie scoped to your domain. It does not use third-party cookies, fingerprinting, or cross-site tracking. The cookie contains only the referral code and is not used for advertising. You can load the script conditionally after cookie consent.
---
## Affiliate Dashboard Widget
### Script URL
```
https://scripts.refgrowcdn.com/page.js
```
### Data Attributes
| Attribute | Required | Description |
|----------------------|-------------|-------------------------------------------------------|
| `data-project-id` | Yes | Your Refgrow project ID |
| `data-project-email` | Recommended | Current user's email for auto-login |
| `data-lang` | No | Language code (e.g., `en`, `de`, `fr`). Auto-detected. |
### With User Authentication
```html
<div id="refgrow"
data-project-id="YOUR_PROJECT_ID"
data-project-email="user@example.com"
data-lang="en">
</div>
<script src="https://scripts.refgrowcdn.com/page.js" async defer></script>
```
### Without User Authentication
```html
<div id="refgrow"
data-project-id="YOUR_PROJECT_ID"
data-lang="en">
</div>
<script src="https://scripts.refgrowcdn.com/page.js" async defer></script>
```
Users will need to enter their email and verify it to access the dashboard.
### Programmatic Control
```javascript
// Identify a user after login
Refgrow.identify('user@example.com');
// Switch language
Refgrow.setLanguage('de');
// Listen for events
Refgrow.on('affiliate:signup', (data) => {
console.log('New affiliate signed up:', data.email);
});
```
### Supported Languages
English (en), German (de), Spanish (es), French (fr), Italian (it), Portuguese (pt), Romanian (ro), Russian (ru), Ukrainian (uk).
### Widget Blocks
The widget is composed of configurable blocks. Enable, disable, and reorder from project settings.
Available blocks:
- `header` -- program title and description
- `share_links` -- referral URL with copy button
- `coupon_code` -- affiliate's assigned coupon code
- `stats` -- click count, referral count, conversion metrics
- `daily_stats` -- daily performance chart
- `earnings` -- total and pending commission amounts
- `payment_methods` -- payout configuration
- `payment_history` -- past payouts with status
- `commission_levels` -- multilevel commission progress (paid plans)
- `multi_tier` -- sub-affiliate earnings (paid plans)
- `promotional_materials` -- banners, text links, social share templates
Block configuration format (stored in `projects.widget_blocks_config`):
```json
[
{ "id": "header", "enabled": true, "order": 1 },
{ "id": "share_links", "enabled": true, "order": 2 },
{ "id": "coupon_code", "enabled": true, "order": 3 },
{ "id": "stats", "enabled": true, "order": 4 },
{ "id": "daily_stats", "enabled": true, "order": 5 },
{ "id": "earnings", "enabled": true, "order": 6 },
{ "id": "payment_methods", "enabled": true, "order": 7 },
{ "id": "payment_history", "enabled": false, "order": 8 },
{ "id": "commission_levels", "enabled": false, "order": 9 },
{ "id": "multi_tier", "enabled": false, "order": 10 },
{ "id": "promotional_materials", "enabled": false, "order": 11 }
]
```
### Widget Appearance
Customizable in project settings:
- Primary Color (buttons and highlights)
- Secondary Color (secondary elements and accents)
- Font Color (text color)
- Title (headline text)
- Description (program explanation)
On paid plans, the "Powered by Refgrow" footer can be removed.
---
## Payment Provider Integration
### Stripe Integration
Webhook URL: `https://refgrow.com/webhook/stripe/{your-project-id}` (auto-configured)
#### Setup
1. Go to project's "Integration" tab
2. Select "Stripe Webhooks" as tracking method
3. Enter your Stripe Secret Key (restricted key recommended)
4. Click "Connect Stripe"
5. Refgrow auto-configures the webhook endpoint in your Stripe account
#### Passing Referral Codes to Stripe
**For Stripe Checkout Sessions:**
```javascript
const refCode = req.cookies.refgrow_ref_code;
const session = await stripe.checkout.sessions.create({
// ... other session parameters
metadata: {
referral_code: refCode || null
}
});
```
**For Stripe Payment Links (automatic):**
```html
<a href="https://buy.stripe.com/xyz..."
class="refgrow-stripe-payment-link">
Buy Now
</a>
```
```javascript
if (window.Refgrow) {
Refgrow.processStripePaymentLinks();
}
```
**For Stripe Payment Links (programmatic redirect):**
```javascript
if (window.Refgrow) {
Refgrow.redirectToStripePaymentLink('https://buy.stripe.com/xyz...');
}
```
#### Attribution Priority (Stripe)
Refgrow checks these in order:
1. Coupon / promotion code match (most reliable)
2. `session.metadata.referral_code`
3. `client_reference_id` on checkout session
4. Subscription metadata
5. Email fallback via `referral_attributions` table
#### Supported Stripe Webhook Events
- `checkout.session.completed` -- purchase completed
- `invoice.paid` -- subscription invoice paid
- `customer.subscription.created` -- new subscription
- `customer.subscription.updated` -- plan changes, renewals
- `customer.discount.created` -- coupon applied (renewal tracking)
- `charge.refunded` -- charge refunded
#### Commission Configuration
Commission priority:
1. Affiliate-specific override (highest priority)
2. Product-specific commission
3. Project default commission (fallback)
Commission types: Percentage or Fixed Amount
Commission duration: Lifetime, First Purchase, or Limited Period
For subscriptions:
- Commission on initial payment
- Optional recurring commissions on renewals
- Additional commission on upgrades
- Automatic reversal on refunds/cancellations
---
### LemonSqueezy Integration
Webhook URL: `https://refgrow.com/webhook/lemonsqueezy/YOUR_PROJECT_ID`
#### Setup
1. Go to LemonSqueezy Dashboard > Settings > Webhooks
2. Click "Create Webhook"
3. S