Skip to content

Referrals

Menu Location: Reports > Customers > Referrals

Last Updated: 2026-10-06

Overview

The Referrals page manages your customer referral program, tracking when existing customers refer new customers and facilitating the reward process. The system captures referral information during signup and helps you credit referring customers once referrals are confirmed.

Primary Functions:

  • Turn the whole referral program on or off
  • Track new customer referrals and referring customer information
  • Link referrals to existing customers
  • Process referral credits/rewards
  • View referral program performance
  • Manage referral lifecycle from pending to completed

Page Layout

Header Section

  • On/Off toggle: Master switch for the whole referral program. Turn it off and customers stop seeing and sharing referral links and the invite page is disabled. Shown on the main Referrals view only.
  • Page Title: Referrals management with counts
  • Settings Button: Opens the Referral Bonus Settings panel (bonus amounts, limited-time incentive boost, quick-set promo banner)
  • Edit Email Button: Customize referral credit email template
  • Leaders Link: View top referring customers

Tab Navigation

  • New Referrals: Unlinked referrals needing assignment
  • Lost Causes: Referrals that couldn't be matched
  • Pending: Linked but waiting for payment confirmation
  • Credit Due: Ready to receive referral credit
  • Completed: Fully processed referrals
  • All: Complete referral history

Main Table

Displays referrals with new customer info, referring customer, payment count, credit status, and action buttons.

Referral Program Flow

How Referrals Work

  1. Signup: New customer enters referring customer's name during signup
  2. Capture: System records name in how_did_you_hear_text field
  3. Matching: System attempts to find existing customer by name
  4. Linking: Admin links referral to correct existing customer
  5. Tracking: System counts new customer's paid orders
  6. Crediting: After threshold reached, admin applies credit to referring customer
  7. Completion: Referral marked complete, email sent to referring customer

When the new customer signs up through a specific customer's referral link, that referring customer immediately gets a "Referral Signup Started" email so they know the referral registered. It is sent once per friend, well before the credit is due, and is edited on the Email Templates page (see Email Template below).

Referral Criteria

System tracks referrals where:

  • Customer selected "A friend told me!" or "Friend/Family" as acquisition source
  • Customer entered a name in the "how did you hear" text field
  • Name doesn't match filtered keywords (Google, social media, Groupon, etc.)
  • Referral not marked as deleted (referred_by != -1)

Managing Referrals

Tab 1: New Referrals

Purpose: Link new customers to their referring customers

What You See:

  • New customers who entered a referring name
  • System-suggested matches based on name search
  • Input field to enter referring customer ID
  • Payment count (how many boxes new customer has received)

Actions:

  1. Review suggested matches (if any)
  2. Search for referring customer if no matches
  3. Enter referring customer ID in input field
  4. Click "Save" to link referral
  5. Referral moves to "Pending" tab

Tips:

  • System searches first and last name for matches
  • If multiple matches, check customer IDs to find correct one
  • Common names may need phone/email verification
  • Contact new customer if referring name is unclear

Tab 2: Lost Causes

Purpose: Review referrals that can't be automatically matched

What You See:

  • New customers with high payment counts but no linked referring customer
  • Likely cases where referring name doesn't match any customer

Actions:

  1. Contact new customer to clarify referring customer
  2. Search for referring customer using additional info
  3. Link if match found, or delete referral record if invalid

Tab 3: Pending

Purpose: Monitor referrals waiting for payment threshold

What You See:

  • Referrals successfully linked to referring customers
  • Payment count showing progress toward reward threshold
  • Status: Waiting for new customer to reach required number of paid orders

Info Display:

  • Shows referral bonus amount configured in system
  • Displays required payment count (e.g., 4 paid deliveries)
  • No action needed - these automatically move to Credit Due when threshold reached

Tab 4: Credit Due

Purpose: Apply credits to referring customers who earned rewards

What You See:

  • Referrals where new customer has paid for required number of orders
  • "Credit" button pre-filled with the bonus amount that was locked onto that referral at signup (legacy referrals use the current Settings amount)
  • Input to adjust credit amount if needed

Actions:

  1. Review referral is legitimate
  2. Verify payment count is accurate
  3. Click "Credit" button
  4. System automatically:
    • Applies credit to referring customer's account
    • Sends "Referral Credit Applied" email to referring customer
    • Records the credit so the referring customer sees a celebratory "You earned referral credit!" popup the next time they log in (shown once, then cleared)
    • Marks referral as complete
    • Records transaction in payment history

Before Crediting, Check:

  • Referring customer is correct
  • New customer's payments are legitimate (not chargebacks/cancellations)
  • No duplicate referrals for same new customer

Tab 5: Completed

Purpose: Historical record of processed referrals

What You See:

  • All referrals that have been credited
  • Completion date and time
  • Final credit amount applied

Uses:

  • Audit trail for referral program
  • Review program performance
  • Verify credits were applied correctly

Tab 6: All

Shows every referral record regardless of status. Useful for comprehensive searching and reporting.

Referral Leaders

Click "Leaders" button to see top referring customers.

Leaders Page Shows:

  • Customer ID and name
  • Total number of successful referrals
  • "Details" button to view all their referrals

Use Cases:

  • Identify your best advocates
  • Create special recognition programs
  • Target customers for loyalty rewards
  • Understand who drives word-of-mouth growth

Common Use Cases

Use Case 1: Process New Referrals Daily

Goal: Link new customers to referring customers efficiently

Steps:

  1. Go to Referrals page
  2. Click "New Referrals" tab
  3. For each entry:
    • Check if system found possible matches
    • If match looks correct, enter that customer ID
    • If no match or uncertain, search for customer by name
    • Enter correct customer ID and click "Save"
  4. If unable to find match, contact new customer for clarification
  5. Move to next referral

Example: New customer "Jane Smith" referred by "Bob Johnson". System shows possible match: Customer #5432 Bob Johnson. Verify this is correct customer, enter 5432, save. Jane's referral now linked to Bob and will track toward his reward.

Use Case 2: Credit Eligible Referrals

Goal: Reward referring customers once new customers are confirmed

Steps:

  1. Go to Referrals page
  2. Click "Credit Due" tab
  3. Review list of ready-to-credit referrals
  4. For each referral:
    • Verify new customer has legitimate payment history
    • Confirm referring customer is correct
    • Check credit amount is appropriate
    • Click "Credit" button
  5. System applies credit and sends email
  6. Referral moves to "Completed" tab

Tips:

  • Process credits weekly or bi-weekly
  • Batch process to save time
  • Watch for suspicious patterns (same addresses, payment methods)
  • Check that new customers are still active

Use Case 3: Handle Unclear Referral

Goal: Resolve referral when referring customer name is ambiguous

Steps:

  1. Note new customer's ID and contact info
  2. Call or email new customer
  3. Ask for more details: "Can you help us identify who referred you? Do you know their phone number or email?"
  4. Use additional info to search for referring customer
  5. Once identified, link referral
  6. If still can't identify, move to Lost Causes or delete

Referral Configuration

Turning the Program On or Off

The On/Off toggle in the header is the master switch for the referral program. Turn it off and customers stop seeing and sharing referral links and the invite page is disabled. Turn it on to make the program live again.

The program is only fully live when the toggle is On and a new-customer (referee) credit is set above $0. If you turn the toggle on before setting a referee amount, the page shows a warning telling you to open Settings and set the amount, so a program that looks on but has nothing configured cannot go live by accident. When the program is live, the page instead shows a green callout spelling out the current deal (what new customers get, what referrers earn, and how many boxes the friend must complete); if a limited-time boost is running, it also shows the regular amounts and the boost end date.

Referral Bonus Settings

Click the Settings button (top right) to open the Referral Bonus Settings panel. This replaces the old fixed bonus amount, so you can change your referral offer any time without a developer.

Bonus amounts:

  • New customer (referee) gets: credit applied to the new customer at signup
  • Referring customer gets: credit paid to the referring customer once the new customer places their required orders

Boxes before referrer is paid: how many paid boxes the new customer must complete before the referring customer's credit shows as due. Enter the number in the Settings panel (minimum 1). While a referral is below that count it sits on the Pending tab; once it reaches the count it moves to Credit Due. Changing this number applies to all referrals, linked or not.

Referral signup offer code (optional): a store-wide discount code auto-applied to every referred signup, on top of the signup credit. Leave it at None, account credit only for credit-only referrals. To pick one, type in the field and choose from the matching codes; the picker lists only codes that apply to brand-new customers (new + reactivations) and excludes gift certificates and existing-customer-only codes. The friend never types the code, it applies automatically at signup. The chosen code drops if the friend already arrived through a per-link promo code, that link's code wins. Manage the codes themselves on the Discount Codes page.

Limited-time incentive boost:

  • Limited-time incentive boost checkbox turns on a temporary higher offer for a date range. It works any time of year, not just holidays.
  • Start date / End date: the window when the boosted amounts apply
  • Boosted referee amount / Boosted referrer amount: the higher amounts used inside that window

Amounts are locked onto each referral at signup. When a customer signs up through a referral, the bonus amounts in effect at that moment are saved onto the referral record. Changing the settings (including the boost window) later never alters referrals that already exist; only new referrals use the new amounts. Legacy referrals created before this feature fall back to the current settings when credited.

Quick-set promo banner:

Two buttons set your store's promo banner (hello bar) to the referral promo, each with a confirmation warning that it overwrites your current banner. Both audiences get the same message, what the referring customer earns, with a Share your link button that opens the Tell A Friend page:

  • Set logged-out banner: for visitors who are not signed in
  • Set logged-in banner: for signed-in customers

While a limited-time boost is active, the banner shows the higher amount with the regular amount struck through so the uplift is obvious. A View / edit banners link opens the Promotion Banner page, where you can edit the text afterward. A Limited-time bonus badge also appears on the customer share page and invite page while the boost window is open.

Other places this promo shows automatically:

A site-wide referral bar appears at the top of your store automatically for every store with the referral program live, for both signed-in and signed-out visitors, so the program is promoted even if you never set a banner. It is colored with your store's brand color, uses your live amounts ("Refer a friend, you both win: give X, get Y"), and adds a "Boosted for a limited time!" note while a boost is active. It stays out of the way when another promo/hello bar is already showing at the top (two bars never stack), on the Tell A Friend page itself, and in the app.

A referral promo section also appears on your front page, and a "Referral Promo" page-builder block is available to drop onto any page. Both stay hidden on the live site until a limited-time incentive boost is active (set the dates above), then light up on their own, no banner edit needed.

Customers share a clean per-referral link in the form yourstore.com/friend/CODE (for example, yourstore.com/friend/JANE25). The code is generated the first time a customer shares it, and the customer can change it on the Tell A Friend page. Older /share/CODE links keep working. Opening a link shows the friend a personalized "claim your gift" landing; if someone who is already signed in opens a link, they go to their own Tell A Friend tools instead of the new-customer landing.

The Tell A Friend page is now full-width: signed-out visitors get a pitch for the program (the reward, how it works, and a sign-up button), and signed-in customers get their invite-by-email form plus a "Share your link" card with their link and share buttons. The invite landing a referred friend sees is also full-width, with a brand-colored hero showing the referrer's name and the welcome credit, a short how-it-works, your testimonials, terms, and a contact band.

Email Template

Customize the "Referral Credit Applied" email:

  1. Click "Edit Referral Email" button on Referrals page
  2. Edit subject line, message body
  3. Available merge tags:
    • **referral_credit_amount**: Amount of credit
    • **referred_customer**: New customer's name
  4. Save changes

The program also sends an automatic "Referral Signup Started" email to the referring customer the moment their friend signs up through the referrer's link. It is created automatically and is edited on the Email Templates page, not from the Referrals page. Its merge tags include **first_name** (the referring customer), **referred_customer**, **referral_amount**, **boxes_text**, and **referral_link**.

Troubleshooting

Referral Not Appearing

Symptoms: Customer says they referred someone but referral not in system

Check:

  1. New customer actually completed signup
  2. New customer selected "Friend/Family" or similar option
  3. New customer entered a name (not blank)
  4. Name didn't contain filtered keywords
  5. Search "All" tab for the new customer

Solutions:

  • Manually create referral record if needed
  • Verify signup form includes referral question
  • Check filter logic isn't too aggressive

Can't Find Referring Customer

Symptoms: New customer entered name but no matches found

Try:

  • Search by partial name
  • Check for spelling variations
  • Search by phone/email if customer provided
  • Contact new customer for clarification
  • Check if referring customer uses nickname

Solutions:

  • Get more info from new customer
  • Search customer database broadly
  • If can't match, mark as lost cause
  • Some referrals will remain unlinked

Credit Not Applied

Symptoms: Clicked "Credit" but customer balance didn't update

Check:

  1. Look in customer's Payment History
  2. Verify credit transaction was created
  3. Check customer balance increased
  4. Review error logs if available
  5. Check referral moved to Completed tab

If Still Not Applied:

  • Manually add credit via customer account
  • Check system permissions
  • Contact technical support
  • Email Templates (admin_email_edit.php) - Edit referral credit email
  • Customer Info (customer_info.php) - View individual customer referrals
  • Customers Search - Filter customers by acquisition source
  • Reports - Referral program analytics

Best Practices

Daily Management

  1. Review new referrals daily
  2. Link obvious matches immediately
  3. Flag unclear referrals for follow-up
  4. Process credits weekly

Quality Control

  • Verify legitimacy before crediting
  • Watch for fraud patterns
  • Confirm new customers are active
  • Check payment history is real

Customer Communication

  • Thank referring customers promptly
  • Make referral process clear during signup
  • Send reminder emails about referral benefits
  • Recognize top referrers publicly (if they consent)

Things to Avoid

  • Don't credit without verifying legitimacy
  • Don't delete referrals without checking (use Lost Causes)
  • Don't ignore patterns of fake referrals
  • Don't change credit amount without documenting why

Quick Reference Card

Task Action/Location
Link new referral New Referrals tab > Enter customer ID > Save
Apply credit Credit Due tab > Click Credit button
Find customer's referrals Search box > Enter customer ID
View top referrers Click "Leaders" button
Edit credit email Click "Edit Referral Email"
Check referral status Search and check tab
Remove bad referral Click red X button > Confirm
View completed referrals Completed tab

FAQs

How many orders must a new customer complete?

Set by the Boxes before referrer is paid field in the Settings panel (minimum 1). The Credit Due tab and its description use this number, so they always match what you configured.

What if the new customer cancels after credit applied?

This is rare but can happen. You can remove credit if it seems fraudulent, but most programs accept this as a cost of doing business.

Can we change the credit amount per referral?

Yes, when clicking "Credit" you can adjust the amount before applying. However, consistency is recommended.

What if both customers are new?

The referring customer must be an existing customer. If both are new, you can't link the referral until the referring customer completes signup first.

How do we promote the referral program?

Add information to emails, website, packing slips. Mention the benefit during customer service interactions. Include in welcome email.

Change Log

2026-10-06

  • Customer share links are now clean per-referral links in the form yourstore.com/friend/CODE; older /share/CODE links still work and the code can be changed on the Tell A Friend page
  • A site-wide referral bar now advertises the program at the top of every store with the referral program live, signed in or out, without setting a banner; it is suppressed when another top bar is already showing, on the Tell A Friend page, and in the app
  • The Tell A Friend page is full-width: signed-out visitors see a program pitch, signed-in customers see their invite form and share tools (link + share buttons)
  • The invite claim landing a referred friend sees is redesigned and brand-colored (hero with the referrer's name and welcome credit, how-it-works, testimonials, terms, contact)

2026-10-05

  • "Boxes before referrer is paid" is now a settable field in the Settings panel (minimum 1), replacing the fixed system setting; Pending and Credit Due now use this number
  • Added an optional Referral signup offer code picker: a store-wide discount code auto-applied to every referred signup that stacks with the credit (new-customer codes only, no gift certificates or existing-customer-only codes)
  • The main view now opens with a status callout describing the current deal in plain language (off / on-but-not-live-yet / live), and a Limited-time bonus badge shows on the customer share and invite pages while a boost is active
  • Added a master On/Off toggle for the referral program in the page header; the program is only live when the toggle is on and a referee credit is set
  • Renamed "Holiday boost" to "Limited-time incentive boost" (works any time of year, not just holidays)
  • Quick-set promo banners now use one unified message for both audiences; while a boost is active the banner shows the higher amount with the regular amount struck through, and a View / edit banners link opens the Promotion Banner page
  • Documented the front-page referral promo section and the "Referral Promo" page-builder block, both hidden until a boost is active
  • Referrers now get an instant "Referral Signup Started" email when a friend signs up through their link, and a celebratory popup the next time they log in after a credit is applied
  • The customer's My Referrals page now opens with an earnings summary (credit earned so far vs. pending, with a pending count and amount)
  • The invite page a referred friend lands on now offers an optional "leave your email" lead capture (name + email) that adds them to the missed-signup email campaign and prefills signup; the primary signup button skips it
  • The logged-out Tell A Friend page now pitches the program to visitors (reward, how-it-works, sign-up and log-in buttons, limited-time boost badge) instead of redirecting straight to sign-up; the referral-link dispatcher no longer mistakes tracking or dev URL parameters for a referral token

2026-10-03

  • Added Referral Bonus Settings panel (referee/referrer amounts, holiday boost window, quick-set promo banner)
  • Bonus amounts are now configurable and locked onto each referral at signup
  • Removed the retired fixed-bonus constant reference from configuration docs

2026-03-01

  • Initial documentation created
  • Documented referral workflow and tab structure
  • Added common use cases and troubleshooting
  • Included best practices for program management

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.