Skip to content

Referrals Documentation

Menu Location: Reports > Customers > Referrals

Access Level: Customer Service / Manager

Last Updated: 2026-03-01

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:

  • 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

  • Page Title: Referrals management with counts
  • Edit Email Button: Customize referral credit email template
  • Leaders Link: View top referring customers
  • Search Box: Find referrals for specific customer

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

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 with amount to apply
  • 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
    • 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

System Settings

Referral program configured via constants and settings:

REFERRAL_ORDER_COUNT: Number of paid orders required before credit (typically 4) REFERRAL_BONUS_AMOUNT: Credit amount for referring customer (e.g., $20)

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

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

Permissions & Access

Required Access Level: Customer Service or higher

Access Level Capabilities:

  • Customer Service: View, link referrals, apply credits
  • Manager: All customer service + edit email templates
  • Administrator: All features
  • Kiva Admin: All features + configuration

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?

Typically 4 paid orders, but this is configurable per system. Check the threshold shown on the page.

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-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.