Integration Guide

How to Apply Referral Credits to Chargebee Subscriptions with GrowSurf

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

Automatically apply referral reward credits to subscriber accounts in Chargebee when referrals convert through GrowSurf.

Chargebee manages your subscription billing — and subscription credits are one of the most natural referral rewards for SaaS businesses. When a referrer's friend becomes a paying subscriber, automatically crediting the referrer's Chargebee account creates a seamless experience: the credit appears on their next invoice, reducing their bill without any manual intervention.

This guide covers connecting GrowSurf referral conversions to Chargebee's promotional credits system. You'll learn how to apply credits to subscriber accounts, handle credit stacking, configure credit expiration, and track credit usage for financial reporting.

Integration Steps

Step 1: Set Up Chargebee API Access

Configure Chargebee API credentials for your webhook handler.

Go to Settings > Configure Chargebee > API Keys in your Chargebee dashboard
Create a full-access API key for your referral integration
Note your Chargebee site name (used in the API URL: https://{site}.chargebee.com)
Store credentials securely as environment variables

Step 2: Design Your Credit-Based Reward Structure

Plan how referral credits will work within your Chargebee billing setup.

Decide on credit amounts:
- Flat credit: $10 per successful referral
- Percentage credit: 1 month free (credit = subscription plan price)
- Tiered credits: $10 for 1st referral, $20 for 5th, $50 for 10th
Define credit behavior:
- Do credits stack? (multiple referral credits on one account)
- Do credits expire? (e.g., must be used within 90 days)
- Are credits transferable between subscription plans?

Step 3: Build the Credit Application Handler

Create a webhook handler that receives GrowSurf reward events and applies credits in Chargebee.

Listen for PARTICIPANT_REACHED_REWARD or CAMPAIGN_REFERRAL_CONVERTED
Look up the referrer's Chargebee subscription by email
Apply a promotional credit to their account using Chargebee's API
Log the credit for auditing and reconciliation

Step 4: Apply Credits Using Chargebee's API

Use Chargebee's Promotional Credits API to add referral credits to subscriber accounts.

Use POST /api/v2/promotional_credits/add to add credits
Specify the customer ID, credit amount, and description
Credits automatically apply to the next invoice in Chargebee
Track the credit in both Chargebee and your referral database

Step 5: Handle Credit Stacking and Limits

Implement business rules for managing multiple referral credits on a single account.

Query existing promotional credits before adding new ones
If you have a maximum credit cap, check the total before applying
For percentage-based credits, look up the customer's plan price dynamically
Handle edge cases: customer on free plan, customer with existing credits, customer who cancelled

Step 6: Track and Report on Referral Credits

Monitor credit issuance and usage for financial reporting.

Build a tracking table: credit_id, customer_id, amount, source (referral_id), status, created_at, used_at
Track total credits outstanding (liability on your balance sheet)
Monitor credit utilization rate: what percentage of issued credits are actually used?
Create monthly reports for finance: credits issued, credits used, credits expired

Code Snippets

// Apply referral credits to Chargebee subscriptions
const chargebee = require('chargebee');
chargebee.configure({
  site: process.env.CHARGEBEE_SITE,
  api_key: process.env.CHARGEBEE_API_KEY
});

async function applyReferralCredit(referrerEmail, creditAmount, referralId) {
  // Find the customer in Chargebee
  const result = await chargebee.customer.list({
    'email[is]': referrerEmail,
    limit: 1
  }).request();

  if (result.list.length === 0) {
    throw new Error(`Customer not found: ${referrerEmail}`);
  }

  const customer = result.list[0].customer;

  // Check existing credits (optional: enforce cap)
  const existingCredits = await chargebee.promotional_credit.list({
    'customer_id[is]': customer.id
  }).request();

  const totalCredits = existingCredits.list.reduce(
    (sum, pc) => sum + pc.promotional_credit.amount, 0
  );

  const MAX_CREDIT = 10000; // $100 cap in cents
  if (totalCredits + creditAmount > MAX_CREDIT) {
    creditAmount = MAX_CREDIT - totalCredits;
    if (creditAmount <= 0) {
      console.log(`Credit cap reached for ${referrerEmail}`);
      return null;
    }
  }

  // Add promotional credit
  const credit = await chargebee.promotional_credit.add({
    customer_id: customer.id,
    amount: creditAmount,
    description: `Referral reward (ID: ${referralId})`,
    credit_type: 'general'
  }).request();

  return credit.promotional_credit;
}

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

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

  try {
    const credit = await applyReferralCredit(
      referrer.email,
      1000, // $10.00 in cents
      participant.id
    );

    if (credit) {
      console.log(`Applied $${credit.amount / 100} credit to ${referrer.email}`);
    }
    res.json({ success: true });
  } catch (error) {
    console.error('Chargebee credit error:', error);
    res.status(500).json({ error: error.message });
  }
});

Tips

Use Chargebee's Credit Notes for Immediate Invoice Adjustments

If you want credits to apply to the current billing period (not just the next invoice), use Chargebee's Credit Notes API instead of Promotional Credits. Credit notes adjust the current or outstanding invoice immediately, while promotional credits apply to future invoices.

Set Up Credit Expiration with Scheduled Jobs

Chargebee promotional credits don't expire automatically. If your program requires credit expiration, create a scheduled job that checks for credits older than your expiration period and removes them using the promotional_credit.deduct API. Notify customers before expiring their credits.

Sync Credit Balances Back to GrowSurf

Keep GrowSurf participant metadata updated with their current Chargebee credit balance. This lets you display credit information in GrowSurf's referral widget and emails, giving participants real-time visibility into their earned rewards.

FAQ

Do Chargebee promotional credits automatically apply to the next invoice?

Yes. Once added, Chargebee promotional credits are automatically applied to the customer's next invoice, reducing the amount charged. If the credit exceeds the invoice amount, the remaining balance carries forward to subsequent invoices. No additional code is needed for credit application.

Can I give credits to both the referrer and the referred subscriber (double-sided)?

Yes. In your webhook handler, apply a credit to the referrer's account (reward for referring) and also apply a credit to the referred subscriber's account (welcome discount). Use GrowSurf's conversion event to trigger credits for both parties simultaneously.

How do I handle credits when a customer downgrades or cancels?

Promotional credits remain on the Chargebee customer account even after cancellation. If they re-subscribe, the credits will apply to their new subscription. You can choose to deduct unused credits upon cancellation by calling the promotional_credit.deduct API in response to Chargebee's subscription_cancelled webhook.

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 Apply Referral Credits to Chargebee Subscriptions with GrowSurf

Integration Steps

Step 1: Set Up Chargebee API Access

Step 2: Design Your Credit-Based Reward Structure

Step 3: Build the Credit Application Handler

Step 4: Apply Credits Using Chargebee's API

Step 5: Handle Credit Stacking and Limits

Step 6: Track and Report on Referral Credits

Code Snippets

Tips

Use Chargebee's Credit Notes for Immediate Invoice Adjustments

Set Up Credit Expiration with Scheduled Jobs

Sync Credit Balances Back to GrowSurf

FAQ

Do Chargebee promotional credits automatically apply to the next invoice?

Can I give credits to both the referrer and the referred subscriber (double-sided)?

How do I handle credits when a customer downgrades or cancels?

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