Integration Guide

How to Trigger Referral Plan Upgrades in Chargebee with GrowSurf

Name: GrowSurf
Rating: 4.74 (47 reviews)
Author: GrowSurf

Automatically upgrade referrer subscription plans in Chargebee when they hit referral milestones in GrowSurf.

Plan upgrades are a powerful referral reward for SaaS businesses — they give referrers access to premium features without you paying cash out. When a referrer hits a milestone (like 5 successful referrals), automatically upgrading their Chargebee subscription plan creates a win-win: the referrer gets more value, you deepen their product engagement, and premium feature usage often leads to permanent plan upgrades even after the referral reward expires.

This guide covers building an automated plan upgrade system triggered by GrowSurf referral milestones, using Chargebee's Subscription API. You'll learn how to upgrade plans, set temporary upgrades with automatic reversion, and handle edge cases like mid-cycle plan changes and prorated billing.

Integration Steps

Step 1: Define Your Plan Upgrade Reward Structure

Plan which subscription plan changes map to which referral milestones.

Define milestone-to-upgrade mapping:
- 3 referrals: Free → Starter plan (permanent upgrade)
- 5 referrals: Starter → Pro plan (free for 3 months, then revert)
- 10 referrals: Any plan → Enterprise features for 6 months
Decide on upgrade duration: permanent, time-limited, or feature-based
Handle upgrade conflicts: what if someone is already on the target plan?

Step 2: Set Up Referral Plans in Chargebee

Create special subscription plans in Chargebee for referral rewards.

Go to Product Catalog > Plans in Chargebee
Create referral-specific plan variants (e.g., "Pro - Referral Reward" with $0 price for 3 months)
Or use add-ons to unlock features without changing the base plan
Configure trial periods on referral plans if offering time-limited upgrades

Step 3: Build the Plan Upgrade Handler

Create a webhook handler that upgrades Chargebee subscriptions when GrowSurf milestones are reached.

Listen for PARTICIPANT_REACHED_REWARD or track referral counts via PARTICIPANT_REFERRED
Check the participant's current referral count against milestone thresholds
Look up their Chargebee subscription
Apply the appropriate plan change using Chargebee's Subscription API

Step 4: Handle Temporary Plan Upgrades

For time-limited upgrade rewards, set up automatic reversion to the original plan.

Before upgrading, store the customer's current plan in your database
Apply the upgrade using chargebee.subscription.update()
Set a scheduled job to revert the plan after the reward period (e.g., 90 days)
Alternatively, use Chargebee's scheduled changes feature: subscription.update({ changes_scheduled_at: revertDate })
Send the customer a warning email before the revert date

Step 5: Handle Billing and Proration

Manage the financial impact of mid-cycle plan changes.

For upgrades: decide whether to prorate (charge the difference) or give the upgrade free
Use Chargebee's prorate: false option for free upgrades
For reversions: use end_of_term: true to revert at the next billing cycle (no prorated refund)
Track the financial impact of plan upgrades for your referral program ROI calculation

Step 6: Notify Participants About Their Upgrade

Send clear communication about the plan upgrade, its benefits, and its duration.

Send an email via your email provider explaining: what changed, what features they now have, how long it lasts
Update GrowSurf participant metadata with the upgrade status
Display the upgrade in your product UI with a "Referral Reward" badge
Send a reminder email 7 days before a temporary upgrade reverts

Code Snippets

// Chargebee Plan Upgrade for Referral Milestones
const chargebee = require('chargebee');
chargebee.configure({
  site: process.env.CHARGEBEE_SITE,
  api_key: process.env.CHARGEBEE_API_KEY
});

const UPGRADE_MILESTONES = {
  3: { planId: 'starter-plan', permanent: true },
  5: { planId: 'pro-plan-referral', durationMonths: 3 },
  10: { planId: 'enterprise-plan-referral', durationMonths: 6 }
};

async function upgradeSubscription(referrerEmail, milestone) {
  const upgradeConfig = UPGRADE_MILESTONES[milestone];
  if (!upgradeConfig) return null;

  // Find customer
  const customers = await chargebee.customer.list({
    'email[is]': referrerEmail, limit: 1
  }).request();

  if (customers.list.length === 0) return null;
  const customerId = customers.list[0].customer.id;

  // Find active subscription
  const subs = await chargebee.subscription.list({
    'customer_id[is]': customerId,
    'status[is]': 'active',
    limit: 1
  }).request();

  if (subs.list.length === 0) return null;
  const subscription = subs.list[0].subscription;

  // Store current plan for potential reversion
  await db.planUpgrades.create({
    customerId: customerId,
    subscriptionId: subscription.id,
    originalPlan: subscription.plan_id,
    upgradePlan: upgradeConfig.planId,
    milestone: milestone,
    permanent: upgradeConfig.permanent || false,
    revertDate: upgradeConfig.durationMonths
      ? addMonths(new Date(), upgradeConfig.durationMonths)
      : null
  });

  // Apply the upgrade
  const result = await chargebee.subscription.update(subscription.id, {
    plan_id: upgradeConfig.planId,
    prorate: false // Free upgrade, no proration charge
  }).request();

  // If temporary, schedule reversion
  if (upgradeConfig.durationMonths) {
    const revertDate = addMonths(new Date(), upgradeConfig.durationMonths);
    await scheduleReversion(subscription.id, subscription.plan_id, revertDate);
  }

  return result.subscription;
}

app.post('/webhooks/growsurf/plan-upgrade', async (req, res) => {
  const { event, participant, referrer } = req.body;

  if (event !== 'PARTICIPANT_REFERRED' || !referrer) {
    return res.json({ skipped: true });
  }

  const count = referrer.referralCount;
  if (UPGRADE_MILESTONES[count]) {
    const upgraded = await upgradeSubscription(referrer.email, count);
    if (upgraded) {
      console.log(`Upgraded ${referrer.email} to ${upgraded.plan_id} at milestone ${count}`);
      // Send notification email
      await sendUpgradeEmail(referrer, UPGRADE_MILESTONES[count]);
    }
  }

  res.json({ success: true });
});

Tips

Use Plan Add-Ons Instead of Full Plan Changes

Instead of changing the entire subscription plan, consider using Chargebee add-ons to unlock specific premium features. This is less disruptive to billing, easier to revert, and lets referrers keep their current plan while getting bonus features. Create a "Referral Bonus Features" add-on with the desired premium capabilities.

Send Countdown Emails Before Reversion

For temporary plan upgrades, send emails at 14 days, 7 days, and 1 day before the plan reverts. Include a CTA to permanently upgrade at a discounted rate. Many users who've experienced premium features will choose to keep them — converting referral rewards into permanent revenue.

Track Feature Usage During Upgrade Period

Monitor which premium features the upgraded referrer actually uses during their reward period. If they heavily use certain features, mention those features in your reversion warning emails. Showing them what they'll lose is more effective than generic "your upgrade is ending" messaging.

FAQ

How does the plan upgrade affect the customer's billing cycle?

By default, Chargebee prorates plan changes — charging or crediting the difference for the remaining billing period. For referral rewards, set prorate: false to avoid charging the customer for the upgrade. For reversions, use end_of_term: true to revert at the next billing cycle without mid-cycle disruption.

What if the referrer is already on the plan I want to upgrade them to?

Check the customer's current plan before attempting an upgrade. If they're already on the target plan (or a higher plan), skip the upgrade and offer an alternative reward like account credits or extended billing cycle. Log this for your records and notify the referrer of their alternative reward.

Can I offer a permanent plan upgrade as a referral reward without losing revenue?

Yes, strategically. Calculate the lifetime value increase from having a deeply engaged user on a premium plan — they're less likely to churn and more likely to refer others. Many SaaS companies find that users who earn a free plan upgrade through referrals have 40% lower churn rates than users who never engaged with the referral program.

GrowSurf for Startups Program

Startups get a 50% discount

GrowSurf Deals

Get $234k+ In Software Savings

LoyaltySurf

Reward Your Customers For Their Loyalty

Startup Growth Tactics Quiz

How to Trigger Referral Plan Upgrades in Chargebee with GrowSurf

Integration Steps

Step 1: Define Your Plan Upgrade Reward Structure

Step 2: Set Up Referral Plans in Chargebee

Step 3: Build the Plan Upgrade Handler

Step 4: Handle Temporary Plan Upgrades

Step 5: Handle Billing and Proration

Step 6: Notify Participants About Their Upgrade

Code Snippets

Tips

Use Plan Add-Ons Instead of Full Plan Changes

Send Countdown Emails Before Reversion

Track Feature Usage During Upgrade Period

FAQ

How does the plan upgrade affect the customer's billing cycle?

What if the referrer is already on the plan I want to upgrade them to?

Can I offer a permanent plan upgrade as a referral reward without losing revenue?

Unlock the power of word-of-mouth marketing anddeepen your bond with customers

Set up your refer a friend program with customer referral and affiliate program software that lowers your acquisition costs, increases customer loyalty, and saves you gobs of time.

Built for startups,scaled for unicorns

View GrowSurfCustomer Examples

Unlock the power of word-of-mouth marketing and
deepen your bond with customers

Built for startups,
scaled for unicorns

View GrowSurf
Customer Examples