This article was originally published on Jo4 Blog.
Every SaaS founder eventually asks the same question: "How do I get my existing users to bring me new ones?"
The answer is referral programs. The problem is the tools.
The Problem with Referral Tools
I spent a week evaluating referral platforms for jo4. Here's what I found:
| Tool | Price | What's Missing |
|---|---|---|
| Rewardful | $29-299/mo | No link analytics, Stripe-only payouts |
| FirstPromoter | $49-149/mo | Complex setup, steep learning curve |
| ReferralCandy | $47-299/mo | E-commerce only, no API |
Every single one required a separate URL shortener for tracking. Every one locked you into Stripe for payouts. And the cheapest option started at $29/mo for basic features.
Meanwhile, I was already running a URL shortener with click analytics, device tracking, and geo-location built in. The referral link infrastructure was already there. I just needed to add programs, referrers, and reward tracking on top.
What Referral Kit Actually Does
The pitch is simple: create a referral program in 10 minutes, not 10 days.
For Program Owners
You create a program at /rk with a name, reward structure, and destination URL. You choose between two reward types:
Fixed Points — every conversion earns the referrer the same amount. "Refer a friend, earn 100 points."
Percentage — referrers earn a cut of the conversion value. "Earn 10% of every purchase your referral makes."
You get a public landing page at /rk/{your-program-slug} where anyone can sign up as a referrer. They pick a custom referral code (like JOHN20), enter their payout email, and get a unique tracking link.
For Referrers
After enrolling, you get a link like https://jo4.io/r/{shortUrl}. Share it anywhere. Every click is tracked with the same analytics jo4 already provides — device, location, referrer source, timestamp.
When someone converts (buys something, signs up, whatever your program defines as a conversion), you earn points. Your dashboard shows clicks, conversions, conversion rate, and pending/approved/paid points across all programs you're in.
The Conversion Flow
This is where it gets interesting. Program owners trigger conversions via API:
curl -X POST https://jo4-api.jo4.io/api/v1/public/referral/conversion \
-H "X-Jo4-Conversion-Key: your_secret_key" \
-H "Content-Type: application/json" \
-d '{
"programSlug": "summer-referral",
"referralCode": "JOHN20",
"conversionValue": 99.00,
"externalId": "order_12345"
}'
The API attributes the conversion to the referrer, calculates the reward (fixed or percentage), and creates a pending reward. The program owner reviews and approves. The referrer requests payout. The owner pays (offline — no Stripe lock-in) and marks it done.
Status flow: PENDING → APPROVED → PAYOUT_REQUESTED → PAID
No payment processor dependency. No percentage-of-a-percentage. You pay your referrers however you want — PayPal, Venmo, bank transfer, gift cards, crypto. We just track the state.
Why Points Instead of Cash
Most referral tools deal in dollars. We deal in points.
Points are flexible. "100 points = $10" works. So does "100 points = 1 free month" or "100 points = a t-shirt." The program owner defines what points mean. We track the math.
This matters for non-SaaS businesses. A nail salon running a referral program doesn't want to wire $10 to a customer's bank account. They want to give them a free manicure. Points let you do that.
The Technical Bits
Attribution Window
Every program has a configurable attribution window (default: 30 days). If someone clicks a referral link and converts within that window, the referrer gets credit. After the window closes, the conversion is organic.
Event Deduplication
The conversion API uses externalId for idempotency. Send the same order ID twice, and we only credit the referrer once. This matters when your payment webhook fires multiple times (and it will).
Test Mode
Prefix your externalId with test_ and the conversion validates against your API secret but doesn't persist. Test your integration without polluting production data.
Webhooks
Every state change fires a webhook if you've configured one:
-
referral.signup— new referrer enrolled -
referral.conversion— conversion attributed -
referral.reward.approved— reward approved by owner -
referral.reward.paid— payout completed
Pipe these into Zapier, Slack, your CRM — whatever your workflow needs.
What I Got Right
Building on existing infrastructure. The URL shortener already had click tracking, device fingerprinting, and geo-location. Referral links are just URLs with attribution metadata. We didn't rebuild tracking — we extended it.
Offline payouts. Forcing Stripe integration would have narrowed our market to SaaS-only. The confirm-payout workflow is more manual, but it works for salons, clinics, restaurants, freelancers — anyone who pays referrers in-person or via their preferred method.
Points abstraction. Cash rewards sound simpler, but they're actually harder. Currency conversion, tax implications, minimum payout thresholds — points sidestep all of that. Let the program owner decide what points are worth.
What I Got Wrong
Underestimating the UI complexity. The /rk page serves three audiences: program owners viewing their programs, referrers viewing their enrolled programs, and new users discovering programs. Getting the information hierarchy right took more iterations than the entire backend.
The reward approval workflow. My first implementation auto-approved everything. Turns out program owners want to verify conversions before committing to payouts. Fraud is real, even in referral programs. Adding the PENDING → APPROVED step was the right call, but I should have started there.
The Numbers
The whole feature is:
- 1,084 lines of referral program service (Java)
- 3 new database tables with proper indexes and constraints
- 15+ API endpoints (public + protected)
- 6 new frontend pages
- Full webhook integration
- Test mode for safe integration development
And it ships with every jo4 plan. No add-on pricing. No "referral features start at Enterprise tier."
Running a referral program or thinking about adding one to your product? I'd love to hear what's working (or not) for you. Drop your experience in the comments.
Building jo4.io - URL shortener with analytics, QR codes, and now referral program management. Because your links should do more than redirect.
Top comments (0)