Referrals

The referral system lets your existing customers refer new ones and earn rewards. Both the referrer and the new customer (referee) can receive configurable discounts, making it a powerful growth channel.

How It Works

1. Your customer shares their unique referral code with a friend
2. The friend enters the code during enrollment
3. Both the referrer and referee receive their configured rewards

Setting Up the Referral Program

Enable Referrals

1. Go to Settings > Referrals in the dashboard
2. Toggle Referral Program to enabled
3. Configure reward settings (see below)
4. Save changes

Reward Configuration

You can configure separate rewards for the referrer (existing customer) and the referee (new customer):

Example Configurations

"Give 10%, Get 10%"

• Referrer: discount_percent = 10
• Referee: discount_percent = 10

"Refer a friend, get $20 credit"

• Referrer: credit = 20
• Referee: discount_percent = 15

Referral Codes

Each customer is assigned a unique 8-character alphanumeric referral code. Codes are generated using unambiguous characters (no 0/O, 1/I/L confusion):

ABCDEFGHJKLMNPQRSTUVWXYZ23456789

Example code: KH7N4WP3

Customer Portal

Customers can view their referral code and track their referral count from the customer portal. The portal shows:

• Their referral code
• Total number of successful referrals
• Current reward details
• A shareable enrollment link with the code pre-filled

Code Generation

Codes are generated on first access. If a customer doesn't have a referral code yet, one is automatically created when they visit the referral section of the portal.

Referral Validation

When a new customer enters a referral code during enrollment, the system validates it:

1. Checks the tenant slug matches (codes are tenant-specific)
2. Verifies the referral program is enabled for the tenant
3. Looks up the customer associated with the code
4. Returns the referrer's name and the referee's reward details

If the code is invalid, the enrollment can still proceed without a referral.

Tracking Referrals

Dashboard View

Go to Customers > Referrals to see all referrals for your account:

• Referrer name and email — the customer who shared the code
• Referee name and email — the new customer who used the code
• Created date — when the referral was recorded
• Status — whether rewards have been applied

Referral Records

Each referral record links:

• The referrer customer ID
• The referee customer ID
• The tenant
• The timestamp

Promo Code Interaction

Referral codes can be used alongside promo codes, with one important rule:

• Each promo code has a combinable_with_referral flag
• If the promo code is not combinable, the referral code is dropped and only the promo discount applies
• If the promo code is combinable, both discounts are applied

This prevents excessive stacking while still allowing flexible promotions.

API Reference

Get referral configuration

curl "https://api.nextroute.app/api/referrals/config" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "referral_enabled": true,
  "referral_reward_type": "discount_percent",
  "referral_reward_value": 10,
  "referral_reward_referee_type": "discount_percent",
  "referral_reward_referee_value": 10
}

Update referral configuration

curl -X PUT "https://api.nextroute.app/api/referrals/config" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_enabled": true,
    "referral_reward_type": "credit",
    "referral_reward_value": 20,
    "referral_reward_referee_type": "discount_percent",
    "referral_reward_referee_value": 15
  }'

List all referrals

curl "https://api.nextroute.app/api/referrals" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "data": [
    {
      "id": "ref_abc123",
      "referrer_customer_id": "cus_111",
      "referee_customer_id": "cus_222",
      "referrer_name": "John Doe",
      "referrer_email": "john@example.com",
      "referee_name": "Jane Smith",
      "referee_email": "jane@example.com",
      "created_at": "2026-03-20T10:00:00Z"
    }
  ]
}

Get my referral code (customer portal)

curl "https://api.nextroute.app/api/referrals/my-code" \
  -H "Authorization: Bearer CUSTOMER_TOKEN"

Response (200):

{
  "referral_code": "KH7N4WP3",
  "referral_count": 5,
  "referral_enabled": true,
  "referrer_reward_type": "discount_percent",
  "referrer_reward_value": 10,
  "referee_reward_type": "discount_percent",
  "referee_reward_value": 10,
  "enrollment_slug": "acme-waste"
}

Validate a referral code (public)

curl -X POST "https://api.nextroute.app/api/referrals/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "referral_code": "KH7N4WP3",
    "tenant_slug": "acme-waste"
  }'

Response (200):

{
  "valid": true,
  "referrer_name": "John Doe",
  "referee_reward_type": "discount_percent",
  "referee_reward_value": 10
}

Related Pages

• Enrollment — how new customers sign up
• Promos — promo code management
• Customer Portal — portal features for customers
• Field Sales — in-person enrollment