Attribution with Chargebee
This guide walks you through the steps required to attribute referrals if your payment gateway is Chargebee and includes:
- Tracking conversions on your landing page
- Track signups with Chargebee
- Sending signup and transaction events to Cello
1. Track conversions on your landing page
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.
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 functionconst ucc = await window.CelloAttribution('getUcc');// otherwisewindow.CelloAttribution('getUcc').then((result) => { const ucc = result;})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:
Use this option if you create Chargebee customer at the point of signup
Add metadata to Chargebee customer
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.
xxxxxxxxxxvar 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:
Log in to Cello Portal and go to Webhooks to get your endpoint URL and authentication details.
Log in to your Chargebee dashboard.
From the sidebar, select Settings > Configure Chargebee and click on Webhooks.
Click on "+ Add Webhook" and fill out the Endpoint URL provided based on the environment.
Select the events you want to send under "Events to Send." Select the events
- Customer Created, Customer Changed, Customer Deleted
- Payment Succeeded, Payment Refunded, Payment Failed
To secure the webhook, select Protect webhook URL with basic authentication and add the
usernameandsecretprovided in the Cello Portal.Be sure to select Exclude card Information from webhook call
Finally click Create to enable the webhook
Endpoint created 🎉