Skip to content

Instantly share code, notes, and snippets.

@jghankins

jghankins/referral-system-guide.md

Created April 9, 2026 19:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jghankins/b1183eaa42ea2b9a58ab2372c4c6a143 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jghankins/b1183eaa42ea2b9a58ab2372c4c6a143 to your computer and use it in GitHub Desktop.
Download ZIP
PewPros/CoachPros Referral System Guide
Raw
referral-system-guide.md

Referral System Guide

Two referral programs in one system: Tenant Referrals (your customers referring friends) and Platform Referrals (existing PewPros/CoachPros customers referring new platform subscribers).

Setup (Admin)

1. Configure Tenant Referral Credit

  1. Go to Admin > Site Settings > Payments tab
  2. Scroll to Referral Program section
  3. Enter the Tenant Referral Credit Amount in cents (e.g. 1000 = $10.00)
  4. Click Save Settings
  5. Setting this to 0 or leaving it empty disables the tenant referral program

2. Configure Platform Referral Credit

  1. Same Payments tab, same Referral Program section
  2. Enter the Platform Referral Credit Amount in cents (e.g. 5000 = $50.00)
  3. Click Save Settings
  4. This controls credits given when someone refers a new PewPros/CoachPros subscriber

3. Create Platform Referrers

Platform referrers are people (existing customers, affiliates, partners) who can share a referral link for PewPros/CoachPros subscriptions.

  1. Go to Admin > Referrals
  2. Click the Platform Referrals tab
  3. Under Platform Referrers, enter a Name and Email
  4. Click Add Referrer
  5. A unique referral code is auto-generated
  6. Share the referral link with that person: https://yoursite.com/pricing?ref=THEIR_CODE

Scenario 1: Tenant User Refers a Friend

Who: A registered user on your tenant site (e.g. detroitarms.com) refers a friend.

Step-by-step:

  1. User gets their referral link

    • User logs in and goes to their Dashboard (/dashboard)
    • Scrolls to the "Refer a Friend" card at the bottom
    • Clicks "Get My Referral Link" (generates a unique 8-character code)
    • Copies the link (e.g. https://detroitarms.com?ref=ab3kx7mn)

  2. Friend clicks the link

    • Friend visits https://detroitarms.com?ref=ab3kx7mn
    • The ref code is captured in their browser session
    • They can browse the site normally

  3. Friend registers

    • Friend creates an account (web registration or mobile app)
    • On registration, the system:
      • Looks up the referrer by code
      • Sets referred_by_user_id on the new user
      • Creates a pending referral record
      • Clears the referral code from the session

  4. Friend makes their first purchase

    • Friend buys an event ticket, course, membership, or shop item
    • After Stripe checkout completes, the system enqueues a referral credit job
    • The job:
      • Checks if the referral program is enabled (credit amount > 0)
      • Finds the pending referral for this user
      • Gets/creates a Stripe customer for the referrer
      • Applies a negative balance transaction (credit) to the referrer's Stripe account
      • Marks the referral as "credited"
      • Creates an in-app notification for the referrer

  5. Referrer sees the credit

    • Referrer gets a notification: "You earned a $10.00 credit from your referral"
    • The credit appears on their Stripe customer balance
    • Next time they make a purchase, Stripe automatically applies the balance

Key rules:

  • One credit per referred user (even if they make multiple purchases)
  • Self-referral is blocked (can't use your own code)
  • If Stripe is not configured on the tenant, tracking still works but credit issuance fails gracefully (status = "failed")
  • Referral codes are generated lazily (only when the user clicks "Get My Referral Link")

Scenario 2: Platform Referral (Referring New PewPros/CoachPros Customers)

Who: An existing PewPros customer or partner refers someone to buy a PewPros/CoachPros subscription.

Step-by-step:

  1. Admin creates a platform referrer (see Setup step 3 above)

    • Referrer gets a code like q9wm4t2k
    • Their referral link: https://pewpros.com/pricing?ref=q9wm4t2k

  2. Prospect clicks the referral link

    • Prospect visits https://pewpros.com/pricing?ref=q9wm4t2k
    • The ref code is captured in their session
    • They see the normal pricing page (Annual $1,250/yr or Monthly $125/mo)

  3. Prospect selects a plan and checks out

    • Clicks "Get Started" on Annual or Monthly
    • Redirected to /pricing/checkout?plan=annual
    • The referral code is passed as metadata in the Stripe Checkout session
    • The code is cleared from the browser session
    • Prospect completes payment on Stripe's hosted checkout page

  4. Purchase completes (webhook)

    • Stripe sends checkout.session.completed webhook
    • System creates a PlatformPurchase record
    • System looks up the referral code from the Stripe metadata
    • Finds the matching platform referrer
    • Creates a pending platform referral record
    • Enqueues a platform referral credit job

  5. Credit is applied

    • The job:
      • Gets/creates a Stripe customer for the referrer (by email)
      • Applies a negative balance transaction (credit) to the referrer
      • Marks the platform referral as "credited"

  6. Referrer benefits

    • Credit shows on their Stripe customer balance
    • Applied automatically to their next invoice/purchase

Key rules:

  • One credit per platform purchase (unique constraint)
  • Platform referrers must be created by an admin (they're not self-service)
  • The referral code travels through Stripe metadata, so it survives the redirect to Stripe's checkout page and back
  • Works for both PewPros and CoachPros brands

Scenario 3: Mobile App Registration with Referral

Who: A user registers through the mobile app with a referral code.

Step-by-step:

  1. Referrer shares their link or code with a friend
  2. Friend opens the mobile app and registers
  3. The app sends referral_code as a parameter in the registration API call: 
    POST /api/v1/auth/register
{
  "email": "friend@example.com",
  "password": "securepassword",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-01-15",
  "referral_code": "ab3kx7mn"
}
  4. The API links the referral (same as web flow)
  5. Credit is earned on their first purchase

Admin Dashboard

Viewing Referral Activity

  1. Go to Admin > Referrals (/admin/referrals)
  2. Tenant Referrals tab shows:
    • Stats cards: Total, Pending, Credited, Total Credits ($)
    • Filterable table with: Referrer, Referred user, Status, Credit amount, Purchase type, Date
  3. Platform Referrals tab shows:
    • Stats cards for platform referrals
    • Platform referrers list with their codes
    • Add new platform referrers form
    • Platform referrals table with: Referrer, Customer email, Plan, Status, Credit, Date

Referral Statuses

Status Meaning
Pending Referred user registered but hasn't made a purchase yet
Credited Credit was successfully applied to the referrer's Stripe balance
Failed Credit could not be applied (e.g. Stripe error, no Stripe configured)

How Credits Work in Stripe

  • Credits are applied as negative customer balance transactions
  • Stripe automatically applies customer balance to future invoices/payments
  • The credit description shows as "Referral credit" or "Platform referral credit"
  • Credits are in USD by default
  • Referrers must have a Stripe customer record (auto-created if needed)

Referral Link Formats

Type Format Example
Tenant (any page) https://yoursite.com?ref=CODE https://detroitarms.com?ref=ab3kx7mn
Tenant (specific page) https://yoursite.com/events?ref=CODE Works on any page
Platform (pricing) https://pewpros.com/pricing?ref=CODE https://pewpros.com/pricing?ref=q9wm4t2k
Platform (landing) https://pewpros.com?ref=CODE Also works from the landing page

The ?ref= parameter is captured on any page that uses the agency, landing, or pricing pipeline. The code persists in the session until registration (tenant) or checkout (platform).

FAQ

Q: What happens if a referred user never makes a purchase? A: The referral stays in "pending" status indefinitely. No credit is issued.

Q: Can a user be referred more than once? A: No. The referred_id has a unique constraint. Only the first referral link used at registration counts.

Q: What if the referral credit amount is changed after a referral is pending? A: The credit amount is read at the time of purchase processing, not at registration. So the current setting applies.

Q: Can I disable the referral program? A: Yes. Set the credit amount to 0 in Site Settings. The referral card will hide from the dashboard, and pending referrals won't earn credits.

Q: Does the referral code expire? A: No. Codes are permanent once generated. The session-stored code persists until the user registers or the session expires (browser close).

Q: What if Stripe isn't configured? A: Referral tracking still works (pending records are created), but credit issuance will fail gracefully and the referral status will be set to "failed".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment