From Free Trial to Affiliate Revenue: A Complete Stripe Integration
How I built a comprehensive subscription billing system for JobLogr, featuring trials, multi-tier pricing, affiliate tracking, and user referral rewards-all powered by Stripe and Next.js.
Project Overview
JobLogr needed a robust subscription system to monetize their job search platform for both job seekers and recruiters. I implemented a complete solution handling 7-day free trials, dual affiliate and referral attribution, and automated commission tracking.
Background & Context
JobLogr operates a dual-market SaaS platform serving both job seekers and recruiters with a freemium model. They needed to monetize premium features through subscriptions while supporting an affiliate partner program and user-to-user referral rewards.
Key Challenges
Dual Attribution Tracking
JobLogr needed to track both affiliate partners (who drive signups) and user referrals (existing users who refer friends) simultaneously. A user could come through an affiliate link AND use a referral code from another user, requiring accurate attribution for both revenue streams.
Implemented a multi-layer attribution system using Stripe metadata and Firebase. Affiliate information is captured first in session cookies, then attached to the Stripe Customer object. Referral codes are validated separately and stored in promotion code metadata. Both systems work independently, ensuring accurate commission calculations for affiliates and reward credits for referring users.
Backfilling Missing Attribution
Early users signed up before the affiliate tracking system was perfected, resulting in customers without affiliate attribution. This created gaps in commission calculations and reporting.
Built an automated backfill system that queries Firebase for historical attribution data and updates Stripe Customer metadata retroactively. The system runs idempotently, safely updating missing data without overwriting existing correct attributions.
First-Month Referral Discount Structure
JobLogr wanted to offer a first-month discount for referrals (50% off) but then apply ongoing credits ($5/month) for subsequent months. Stripe promotion codes are either one-time OR recurring, not both, and we needed to avoid creating infinite unique promo codes per referrer.
Designed a hybrid approach: referral codes provide the first-month discount via Stripe promotion codes, then webhook automation adds $5 in customer balance credits after the first successful payment. This gives the best UX (one code does everything) while maintaining clean commission tracking.
Organization Assignment via Checkout
Recruiter users needed to be automatically assigned to their company's organization when subscribing with an organization-specific promo code, enabling immediate access to team features without manual onboarding.
Extended Stripe promotion code metadata to include organization IDs. Webhook handlers detect organization codes, validate permissions, and automatically assign the user to the correct organization in Firebase upon successful subscription. This creates a seamless onboarding flow for enterprise customers.
Technical Approach
The implementation centers around Stripe's robust API combined with Next.js Server Actions and comprehensive webhook event handling. I prioritized idempotent operations, detailed logging, and fail-safe fallbacks to ensure billing operations never create duplicate charges or miss attribution data. The architecture separates concerns cleanly: checkout flows handle user intent, webhooks handle state synchronization, and Firebase maintains the source of truth for business logic.
Dual Checkout Flows
Separate checkout sessions for consumer ($20/mo with trial) and recruiter ($20/mo without trial) plans, each with customized metadata for attribution and organization assignment.
Webhook Event Processing
Comprehensive webhook handlers for subscription lifecycle events (created, updated, canceled), payment events, and customer portal changes. All operations are idempotent with detailed error logging.
Affiliate Attribution Pipeline
Multi-stage attribution capture: landing page → session storage → checkout metadata → Stripe Customer → Firebase commission records. Includes backfill automation for historical data.
Referral Rewards System
Promotion codes provide first-month discounts, then automated webhook logic applies customer balance credits ($5/month) for ongoing rewards. Referrer earns credits when referred users convert to paying customers.
Customer Portal Integration
Self-service billing management using Stripe Customer Portal, allowing users to update payment methods, view invoices, and manage subscriptions without support intervention.
Commission Automation
Automated commission calculations based on attribution metadata, with monthly reports generated for affiliate payouts. Zero manual reconciliation required.
Results & Impact
The subscription system launched successfully and has been running in production for over 90 days with zero payment-related support tickets. Affiliate partners receive accurate commission tracking, users enjoy seamless self-service billing, and JobLogr's team can focus on product development instead of billing support. The system handles trial conversions, referral rewards, and organization assignments automatically, reducing operational overhead significantly.
“The Stripe integration handles everything we need-trials, referrals, affiliate tracking-and it just works. We haven't had a single billing support ticket since launch.”
Key Takeaways
- Stripe metadata is incredibly powerful for custom attribution tracking when used systematically
- Webhook idempotency is critical-always design for duplicate delivery and out-of-order events
- Hybrid approaches (promo codes + balance credits) can solve limitations in payment platform features
- Comprehensive logging and error handling prevent silent failures in billing operations
- Self-service billing portals dramatically reduce support burden for SaaS applications
- TypeScript + Server Actions provide type-safe, secure server-side payment processing
- Plan complex promotion structures carefully-one-time vs. recurring promos have different use cases
- Backfill systems should be idempotent and safe to run multiple times on the same data
"I highly recommend Dean to anyone looking for a reliable and professional partner for their software development needs."
Ben Harris - CEO of Lunar Cow Publishing
Need similar work for your project?
Book a free consultation to discuss how we can help you achieve results like these.