Attribution with Chargebee

This guide walks you through the steps required to attribute referrals if your payment gateway is Chargebee and includes:

1. Track conversions on your landing page

Add Attribution library

to your Home page by including the following script in the <head> tag to track attributions and show New user banner.

<script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>

2. Track signups with Chargebee

When a signup finally happens, you need to make sure that a ucc code, identifying the referrer, is saved to the new user record and passed to Chargebee upon customer creation.

Access Ucc code during signup

Ucc is present in the URL of your Home page when a new user is redirected to it from the invite link and in the cookies, added by the Attribution library.

https://getmoonly.com/request-demo?ucc=UPobYBDuu0N&productId=getmoonly.com

To access the ucc during signup, you can use the Attribution library JS method getUcc().

Here is how to do it:

  • Add the following javascript code before any of the calls to the library to avoid race conditions.

window.CelloAttribution=window.CelloAttribution||async function(t,...o){if("getReferral"===t)throw new Error("getReferral is not supported in this context. Use getUcc instead.");let e,n;const i=new Promise((t,o)=>(e=t,n=o));return(window.CelloAttributionCmd=window.CelloAttributionCmd||[]).push({command:t,args:o,resolve:e,reject:n}),i};
// if in async function const ucc = await window.CelloAttribution('getUcc'); // otherwise window.CelloAttribution('getUcc').then((result) => { const ucc = result; })
Can your user sign up in your mobile app?

To make sure your referrers get rewarded when a new user signs up in the mobile app, follow this guide on Mobile attribution to track mobile app signups.

Now the next step depends on your flow!

4. Send signup and transaction events to Cello

Choose one of the 2 options depending on your scenario:

  • I create Chargebee customer at signup - Use only Chargebee Webhook integration if you create Stripe customer at the point of signup

  • I don't create Chargebee customer at signup - Use a combination of Cello API and Chargebee Webhook integration if you don't create Stripe customer at signup and only at purchase

Pick your scenario:

I create Chargebee customer at signup

Use this option if you create Chargebee customer at the point of signup

Add metadata to Chargebee customer

Support for custom fields (CF)

Chargebee webhook supports custom fields (CF). You can choose to use metadata or custom fields to add referral data to the event. Learn more about custom fields in the Chargebee documentation

Next, at the point when you create a customer in Chargebee, make sure that you add the following metadata to the Chargebee customer:

  • cello_ucc - ucc, a referral code identifying the referrer

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

Below is an example for a NodeJS app, illustrating how to include during customer creation.

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" } // .. // })

Add Chargebee Webhook

You will add a Webhook to your Chargebee configuration to connect Chargebee and Cello. This can be done in both sandbox and production environments separately.

💡 Switch environments in the Portal using a switch to configure Sandbox and Production separately.



To set up:

  1. Log in to Cello Portal and go to Webhooks to get your endpoint URL and authentication details.

  2. Log in to your Chargebee dashboard.

  3. From the sidebar, select Settings > Configure Chargebee and click on Webhooks.

  4. Click on "+ Add Webhook" and fill out the Endpoint URL provided based on the environment.

  5. Select the events you want to send under "Events to Send." Select the events

    1. Customer Created, Customer Changed, Customer Deleted

    2. Payment Succeeded, Payment Refunded, Payment Failed

  6. To secure the webhook, select Protect webhook URL with basic authentication and add the username and secret provided in the Cello Portal.

  7. Be sure to select Exclude card Information from webhook call

  8. Finally click Create to enable the webhook


Endpoint created 🎉

I don't create Chargebee customer at signup

If you don't create Stripe customer at signup and only at purchase, then you will need to use Cello API to send signup and Chargbee Webhook to send transaction events

Use Cello API to send signup events

To send signup events, use Cello API /events endpoint.

Use the Domain base URL that corresponds with the environment.

Endpoint URL

Environment

https://api.sandbox.cello.so/

Dev and Stage

https://api.cello.so/

Prod

💡 Switch environments in the Portal using a switch to get the credentials


Authenticate

To use the Cello API, you need to authenticate the request using an accessToken which is passed in the Authorization request header.

To obtain them you will need accessKeyId & secretAccessKey which you can get from your product dashboard on Access Keys page.


Obtain accessToken & refreshToken

curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "accessKeyId": "<accessKeyId>", "secretAccessKey": "<secretAccessKey>" }' { "accessToken": "<accessToken>", "expiresIn": 18000, "refreshToken": "<refreshToken>" } Status Code 201

Refresh accessToken

curl -X POST https://api.cello.so/token \ -H "Content-Type: application/json" \ -d '{ "refreshToken": "<refreshToken>" }' { "accessToken": "<accessToken>", "expiresIn": 18000 } Status Code 201

Send signup events

new-signup - the new user signs up for your product

POST https://api.cello.so/events { "eventName": "ReferralUpdated", "payload": { "ucc": "cello-ucc", "productUserId": "new-user-product-user-id", // or 'new-user-organization-id' "price": 0, "currency": "" }, "context": { "user": { "id": "new-user-product-user-id", "email": "new_user@gmail.com", "name": "New user name", "organizationId": "New user organization id" }, "event": { "trigger": "new-signup", "timestamp": "2022-10-05 14:14:34" } } }

Add metadata to Chargebee customer

Support for custom fields (CF)

Chargebee webhook supports custom fields (CF). You can choose to use metadata or custom fields to add referral data to the event. Learn more about custom fields in the Chargebee documentation

Next, at the point when you create a customer in Chargebee, make sure that you add the following metadata to the Chargebee customer:

  • cello_ucc - ucc, a referral code identifying the referrer

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

Below is an example for a NodeJS app, illustrating how to include during customer creation.

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" } // .. // })

Connect Chargebee Webhook

To set up:

  1. Log in to Cello Portal and go to Webhooks to get your endpoint URL and authentication details.

  2. Log in to your Chargebee dashboard.

  3. From the sidebar, select Settings > Configure Chargebee and click on Webhooks.

  4. Click on "+ Add Webhook" and fill out the Endpoint URL provided based on the environment.

  5. Select the events you want to send under "Events to Send." Select the events

    1. Customer Created, Customer Changed, Customer Deleted

    2. Payment Succeeded, Payment Refunded, Payment Failed

  6. To secure the webhook, select Protect webhook URL with basic authentication and add the username and secret provided in the Cello Portal.

  7. Be sure to select Exclude card Information from webhook call

  8. Finally click Create to enable the webhook


Next to read:
Manual attribution
null
On This Page
Attribution with Chargebee1. Track conversions on your landing page2. Track signups with Chargebee4. Send signup and transaction events to CelloAdd metadata to Chargebee customerAdd Chargebee WebhookUse Cello API to send signup eventsAuthenticateSend signup eventsConnect Chargebee WebhookAccess Ucc code during signupObtain accessToken & refreshTokenRefresh accessTokenAdd metadata to Chargebee customer