Skip to main content
This guide is optimized for the typical freemium scenario with Chargebee.Use this guide if you:
  • Create Chargebee customer on signup
  • Use Chargebee webhook to send Cello referral conversion events

​
Step 1: Integrate the Referral Component

First, integrate Cello Referral Component into your web app to provide referrers with full referral experience. Referral Component is integrated using one of our SDKs. For your web app, use Cello JS - our client-side SDK. You can install it by:
  1. Adding a script tag to the <head> of your application
  2. Generating a JWT token for user authentication
  3. Booting the component with the provided token and user details
Follow this installation guide:

Referral Component Quickstart

You can also integrate Referral Component into your mobile applications:

iOS SDK

Android SDK

React Native SDK

​
Step 2: Capture referral codes on landing page

Next, you will need to add Cello attribution script to your referral landing page:
  1. Setup a landing page for your referral links to redirect to
  2. Install attribution script. Choose one of the following installation options best suited for your setup:

    Embedded Script Tag

    Google Tag Manager

  3. Verify the installation
    To verify, follow these steps:
    1. Add ?productId=test and ?ucc=test to your website URL 
       https://yourwebsite.com/?productId=test&ucc=test
    2. Make sure that these values are saved in the cookies as cello-product-id and cello-referral
    3. Navigate to your signup page and try to access the ucc using the getUcc() method from the browser console 
      window.CelloAttribution('getUcc')
      This method should return a promise with value test 
      Promise {<fulfilled>: 'test'}
    If this check passes, the script is installed correctly.
For capturing referral code in your mobile signup flow, follow this guide:

Mobile signup flow

​
Step 3: Add Cello metadata or custom fields on Chargebee customer creation

To track a signup, you can pass the following metadata to Chargebee on customer creation.
You can also choose to use Chargebee custom fields (CF_) to add referral data to the event. Learn more about custom fields in the Chargebee documentation
  • cello_ucc - ucc, a referral code identifying the referrer. You can retrieve this code using attribution script getUcc () method, you have installed as a prerequisite to this guide.
  • new_user_id - a unique user ID in your system, identifying the new user who just signed up. This should be the same ID (productUserId) you will use to boot the Referral component, when this user logs into your app
  • new_user_organization_id (optional) - add this, if your referrers can refer an organization rather then a single user and you want to reward based on that.
Modify customer data you send upon customer creation. Here is an example for a NodeJS App that does that with meta_data: 
var chargebee = require("chargebee");

chargebee.configure({site : "getmoonly-v3-test", api_key : "test_jqXGuQLkBHUSR2PM0qgUV21W1VqSFJIU"});
chargebee.customer.create({
   first_name : "Bob", 
   last_name : "Bobsky", 
   //...
   // other customer fields
   //...
   meta_data: {
		cello_ucc: "hdz7afhs7",
		new_user_id: "xcsdad", // product user id of the new user
        new_user_organization_id: "123456"
			}
//   ..
// })
Now that the customer is created in Chargebee with Cello metadata, a Customer Created event will be sent with Chargebee Webhook, which we will count as a signup event in Cello.

​
Step 4: Connect Chargebee Webhook to send signup and purchase events

To send Cello signup and purchase events, you will need to connect Chargebee Webhook to Cello. Follow this guide to connect the webhook:

Chargebee Webhook

Send events using Chargebee Webhook
Congratulations! You are done and now able to try out the full Cello referral experience 🎉
⌘I