IA University

client-referral-app-manual.md

Client Referral App — User Manual

What is this doc for? A plain-language guide so anyone on the team can understand what the Client Referral app does, who it's for, and how to use it. No coding knowledge needed.

What is the Client Referral App?

The Client Referral App lets a business owner turn their happy customers into a chain of new customers — automatically.

Here's the idea in one sentence: "Scan a QR code, get a discount, share your own QR code, earn credits when your friends use it."

That's it. It's a word-of-mouth marketing engine, powered by QR codes.

How it works

The business owner shares a QR code (printed on a card, displayed on a screen, posted on social media).
A customer scans it. They land on a simple sign-up page that says, "You've been referred! Fill in your name and phone to get $X off your next visit."
They sign up. They get their discount, AND they get their own personal QR code.
They share their QR code with friends. When a friend scans and signs up, the original customer earns credits — usually a bigger discount or a free product on their next visit.
The chain keeps going. Friend 2 shares with Friend 3, and so on. Every level earns credits when their referral signs up.

The business owner sees everything from a dashboard:

Who joined the program
Who referred whom
How many credits each customer has
Who's actively driving new customers

Who uses this app?

There are two kinds of people who use it:

1. The Business Owner (BO)

The person running the program. Could be a barbershop, a coffee shop, a real estate agent — anyone who wants more referrals from their existing customers.

There are two ways a BO can join:

A. Existing subscriber — already pays for Intelligent Attraction services. They open the app from inside their GHL workspace. Everything is automatic, they're already logged in.

B. Standalone signup — wants to use the referral app only, without paying for the full subscription. They go to the public signup page, create an account with email + password, and they're in.

2. The Customer

The end user — the person who scans the QR code, signs up, and shares their own QR. They never log in to anything. They just scan, fill a form, and get their reward.

What the Business Owner gets

When a BO joins, they can:

Set up their program — name it, choose how much discount each new customer gets, choose what credits the referrer earns
Get a master QR code — the starting QR they share with their first customers
Customize the messaging — what name and business shows up in SMS and email to customers
See a live dashboard — list of all referred contacts, who referred whom, credit balances, conversion log
Look up any customer by code, phone, or email
Confirm visits — when a customer comes in, BO confirms the visit, the system records it
Redeem credits — when a customer wants to cash in their credits, BO clicks "Redeem", enters the amount, and the customer's balance is reduced

What the Customer gets

When a customer scans a QR and signs up:

Instant discount on their next visit (configurable by BO)
Their own QR code to share with friends
A unique referral code (looks like ANA-X7K2)
An SMS or email from the business confirming sign-up + including their referral link and code
Credits every time someone they referred signs up — kept on file by the business

When their friends sign up using their QR:

They get an SMS saying "Hey, your friend just joined using your link! You've earned X credits, total balance is Y."

When they want to use those credits:

They tell the BO their referral code in person
The BO looks them up and applies the credits

How to start using the app (Business Owner)

If you're a paying subscriber

Log in to GHL as usual
In your sidebar, click "Client Referral"
The first time, you'll see a setup form
Fill in your program name, discount amount, credit amount, and what 1 credit means (e.g. "$5 off any service")
Click "Create Program"
Your master QR is ready — download it and share it with your first customers

If you're signing up fresh

Go to the public signup page (your team will share the link)
Enter your name, business name, email, and choose a password
Check your email — click the verification link
You're auto-logged in. Same setup form as above.

That's it. Setup takes about 2 minutes.

How a customer experience looks (step by step)

Day 1 — Customer Sarah scans the BO's master QR

Sarah's phone opens a webpage: "John from Street Credit Barbershop referred you! Get $10 off your next haircut."
Sarah types her name, phone, email. Hits submit.
New page: "Welcome Sarah! Your $10 discount is ready. Show this screen at the counter."
Below the discount, Sarah sees her personal QR code and a button "Download QR" + "Copy Share Link"
Sarah's phone buzzes — text message from the barbershop confirming her sign-up + her referral link

Day 5 — Sarah shares her QR with her friend Mike

Mike scans Sarah's QR
Page says: "Sarah referred you! Get $10 off your first haircut."
Mike signs up the same way Sarah did
Mike gets his own QR
Sarah's phone buzzes — text saying "Hey Sarah! Mike just signed up using your link. You've earned 1 credit (= $10 off). Your balance: 1 credit."

Day 7 — Sarah comes in for her haircut

Sarah tells the BO: "Hi, I'm Sarah, my code is SAR-3K7Q"
BO opens dashboard, types SAR-3K7Q in the lookup box
Sarah's profile appears: name, phone, balance = 1 credit, total visits = 0
BO confirms her check-in (records the visit)
BO redeems Sarah's 1 credit ($10 off) → Sarah pays $10 less

The chain keeps growing as long as people share their QR.

What the Business Owner sees on the dashboard

When the BO opens /dashboard/client-referral/:

Top row: program name, total contacts referred, total successful conversions
Master QR section: their starting QR with download button + a link they can copy and paste
Edit Program Settings: collapsible panel to change discount amount, credit value, business info
Look Up Contact: search box — type a referral code, phone, or email to find any customer
Referred Contacts table: every customer who's joined, with name, code, phone, who referred them, visits, credits, "Manage" button
Conversion Log: every time someone signed up, who via, what discount, when
Redemption History: every time the BO redeemed credits for a customer

When BO clicks "Manage" on a customer:

See their full profile, QR code, stats
Confirm a check-in
Redeem credits (with optional note like "2 free haircuts")
See their personal redemption history

Common questions

Q: Does the customer need an account or to install an app? A: No. They scan a QR, fill a one-time form, and they're in. Their QR works as their identity from then on.

Q: How does the customer "log in" to use their credits? A: They don't. They show the BO their referral code (or QR). The BO looks it up and applies the credits in person.

Q: What if a customer loses their referral code? A: They can search their text messages or email — the code was sent to them. If they truly lost it, the BO can look them up by phone or email from the dashboard.

Q: What stops people from cheating (e.g. signing up with fake info to earn credits for themselves)? A: The BO is the gatekeeper. Credits only get redeemed when the BO confirms it in person. So fake signups can rack up credits but can't cash them in.

Q: How does the customer get notified that someone used their referral? A: Through GHL workflows — the system fires a webhook every time a conversion happens. The GHL workflow sends a text message and/or email to the referrer with their updated balance.

Q: Does the customer's data go into GHL? A: Yes. Every new contact is pushed to GHL via the webhook so the BO can run their normal marketing campaigns to them later.

Q: Can a customer have multiple QR codes? A: No, one customer = one QR code. They can share that one QR with as many people as they want.

Q: What's the difference between "Confirm Check-In" and "Redeem Credits"? A: Check-in is just recording that the customer visited the business — useful for visit-count-based discounts (visit #1 vs visit #5). Redeeming credits is when the customer actually uses their accumulated credits to pay less. They're separate actions.

Things to know about the business owner accounts

Subscribers and standalone users are kept separate. A standalone signup user can't see subscriber-only pages, and vice versa.
The login page for standalone users is different from the GHL subscriber login. Subscribers come in through GHL; standalone users go to /referral-app/login/.
One email = one standalone account. A standalone user can't create two accounts with the same email.
A subscriber can also have a standalone account. They're treated as completely separate — different password, different login page, different data. (This is rare but allowed.)
Standalone users can upgrade to subscriber by purchasing through the regular registration page. Their existing referral program stays attached.

Things the BO can do from the GHL side

(Done by the technical team or admin, not the BO)

Customize the email content customers receive when they sign up (welcome email, verification, password reset)
Customize the SMS content the referrer gets when their code is used
Branch on different events — different message for new sign-up vs return visit vs password reset
Send promotional follow-up messages to anyone who joined the program

This is all configured in GHL workflows. The Django app just fires the webhook with all the relevant data; GHL workflow decides what to actually send.

What's safe and what's not

Safe (by design)

Standalone users can't access subscriber pages, even by typing the URL directly
Bots can't sign up in bulk — there's reCAPTCHA on every public form
Brute-force login attempts are blocked after 5 wrong tries per minute
The signup, login, and password-reset pages can't be embedded in another website (clickjacking-proof)
Verification and password reset links expire (24 hours and 1 hour respectively)
Old or already-used links don't work

Worth knowing

A subscriber with multiple GHL accounts sharing the same email must use GHL SSO to log in. They can't use email/password directly because the system can't tell which account they want.
If a customer's email is wrong on signup, they can't recover their referral code via email — they'd have to ask the BO to look them up.
2-factor authentication is not available yet. Users should use strong passwords.

Where to send people

Person	Where to point them
New BO who wants to try the referral product but doesn't want a full subscription	`/referral-app/signup/`
BO with a paying subscription	Their existing GHL workspace — it'll show up in their sidebar
BO who forgot their password	`/referral-app/login/` → click "Forgot password?"
Customer who wants to look at their own profile	They can't — only the BO can. They can find their referral code in their original SMS/email.
Anyone reporting a bug or odd behaviour	The technical team — include a screenshot, the URL, and what they tried to do

Glossary

BO — Business Owner. The person running the referral program.
Subscriber — A BO who pays for the full Intelligent Attraction subscription.
Standalone / Referral-only — A BO who signed up just for the referral app.
Master QR — The first QR code in a program, owned by the BO. Used to start the chain.
Conversion — A new customer signing up through someone's QR.
Credit — The reward unit the referrer earns. Defined by the BO ("$5 off", "1 free coffee", etc.).
Redemption — When the BO uses up a customer's credits at the counter.
Check-in — Recording that a customer visited. Separate from redemption.
Referral chain — The tree of who-referred-whom, going as deep as people keep sharing.
GHL — GoHighLevel, the CRM platform that handles all SMS/email sending.
SSO — Single sign-on. How a paying subscriber gets logged in automatically when they open the app from inside GHL.