# Get token
Source: https://docs.cello.so/api-reference/authentication/get-token
POST /token
Obtain accessToken & refreshToken using your accessKeyId and secretAccessKey, or obtain a new accessToken using a refreshToken.
# Send new event
Source: https://docs.cello.so/api-reference/generic-events/send-event
POST /events
Report referral-related events such as signups, purchases, and refunds.
# Introduction
Source: https://docs.cello.so/api-reference/introduction
Overview of Cello API for referral codes, authentication, and quickstart.
## Cello API
The Cello API provides endpoints to:
* Validate referral codes (`ucc`)
* Retrieve active referral links
* Send referral events for signups and purchases
***
## Base URLs
Use the URL that matches your environment:
| Environment | Base URL |
| ----------- | ------------------------------- |
| Sandbox | `https://api.sandbox.cello.so/` |
| Production | `https://api.cello.so/` |
***
## Authentication
Authenticate API requests using an `accessToken` in the Authorization header.
Obtain your `accessKeyId` and `secretAccessKey` from the [Access Keys](https://portal.cello.so/integrations/accesskeys) page in your dashboard.
# Fetch active link
Source: https://docs.cello.so/api-reference/referral-codes/fetch-active-link
GET /referral-codes/active-link/{productUserId}
Retrieve an active UCC and invite link for a given user to support contextual sharing.
# Fetch referral code info
Source: https://docs.cello.so/api-reference/referral-codes/fetch-referral-code-info
GET /referral-codes/{code}
Validate a referral code (UCC) and discover associated user/campaign.
# Mobile Signup Flow
Source: https://docs.cello.so/attribution/for-mobile
Learn how to set up mobile app referral attribution
This guide explains how to add referral tracking capabilities to your existing attribution links without creating new ones. In this guide, we'll use Branch.io as an example. The implementation is similar if you use other attribution libraries like [AppsFlyer](https://www.appsflyer.com/), [Singular](https://www.singular.net/) or [Adjust](https://www.adjust.com/).
Mobile attribution builds on top of [web attribution](/attribution/for-web) since users typically click referral links on web before downloading your app. The web setup captures the initial referral code that will later be attributed to the mobile app installation and signup.
## Overview
The referral flow works as follows:
* Existing user shares their unique referral link
* New user clicks the link and is directed to your landing page
* User then clicks on AppStore or Google Play app download
* New user installs and opens the app
* App receives referral data and attributes the installation
* Backend records the referral during signup
## Basic Concept
Instead of creating new links for each referrer, you'll append referral data to your existing Branch.io (or other attribution library) app install link:
```html
Original: https://yourbrand.app.link/abc123
With Referral: https://yourbrand.app.link/abc123?referral_ucc=A1B2C
```
## Data Persists Through Installation
When a user clicks the referral link, Branch.io stores the referral data (including the referral\_ucc) in their servers and associates it with the user's device fingerprint. This allows the data to persist through:
* App Store redirect
* App download
* First app launch
## Data Flow Sequence
#### Link Click
```html
https://yourbrand.app.link/abc123?referral_ucc=A1B2C
↓
Branch.io captures and stores:
- referral_ucc: A1B2C
- Device fingerprint
- Click timestamp
```
#### App Installation
```html
User installs app from store
↓
Branch SDK initializes on first launch
↓
Branch matches device to stored click data
↓
Delivers referral data to app
```
## Accessing Referral Data in Your App
#### iOS Implementation
```swift
import Branch
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in
// Check if the user came from a Branch link
if let clickedBranchLink = params?["+clicked_branch_link"] as? Bool,
clickedBranchLink {
// Extract referral code
if let referralCode = params?["referral_ucc"] as? String {
print("Referral Code: \(referralCode)")
// Store for use during signup
UserDefaults.standard.set(referralCode,
forKey: "pending_referral_code")
}
}
}
return true
}
}
```
#### Android Implementation
```kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
Branch.getAutoInstance(this).initSession({ branchUniversalObject, linkProperties, error ->
if (error == null) {
// Check if user came from Branch link
if (linkProperties?.has("+clicked_branch_link") == true) {
// Get referral code
val referralCode = linkProperties.get("referral_ucc")
referralCode?.let {
Log.d("Branch", "Referral Code: $it")
// Store for signup
getSharedPreferences("app_prefs", Context.MODE_PRIVATE)
.edit()
.putString("pending_referral_code", it)
.apply()
}
}
}
}, this.intent.data, this)
}
}
```
#### React Native Implementation
```javascript
import branch from 'react-native-branch';
function DeepLinkHandler() {
useEffect(() => {
// Handle deep link when app is already running
const subscription = branch.subscribe({
onNewIntent: ({ error, params, uri }) => {
if (error) {
console.error('Branch link error:', error);
return;
}
if (params['+clicked_branch_link']) {
handleDeepLink(params);
}
}
});
return () => subscription();
}, []);
const handleDeepLink = async (params) => {
const referralCode = params.referral_ucc;
if (referralCode) {
await AsyncStorage.setItem('pending_referral_code', referralCode);
// Handle navigation or other logic based on deep link
}
};
return null;
}
```
## Using the Referral Data During Signup
When the user completes signup, retrieve the stored referral code and include it in your signup API call:
#### iOS Implementation
```swift
// iOS Example
class SignupViewController: UIViewController {
func completeSignup(email: String, password: String) {
// Get stored referral code
let referralCode = UserDefaults.standard.string(forKey: "pending_referral_code")
// Include in signup API call
let signupData = [
"email": email,
"password": password,
"referral_code": referralCode
]
api.signup(signupData) { result in
if result.success {
// Clear stored referral data after successful signup
UserDefaults.standard.removeObject(forKey: "pending_referral_code")
}
}
}
}
```
#### Android Implementation
```kotlin
// Android Example
class SignupActivity : AppCompatActivity() {
private fun completeSignup(email: String, password: String) {
val prefs = getSharedPreferences("app_prefs", Context.MODE_PRIVATE)
val referralCode = prefs.getString("pending_referral_code", null)
val signupData = HashMap().apply {
put("email", email)
put("password", password)
referralCode?.let { put("referral_code", it) }
}
api.signup(signupData) { success ->
if (success) {
// Clear stored referral data
prefs.edit().remove("pending_referral_code").apply()
}
}
}
}
```
#### React Native Implementation
```javascript
function SignupScreen({ navigation }) {
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');
const handleSignup = async () => {
try {
const referralCode = await AsyncStorage.getItem('pending_referral_code');
const response = await api.signup({
email,
password,
referral_code: referralCode
});
if (response.success) {
await AsyncStorage.removeItem('pending_referral_code');
navigation.navigate('Home');
}
} catch (error) {
console.error('Signup error:', error);
}
};
return (
// Your signup form JSX
);
}
```
# Web Signup Flow
Source: https://docs.cello.so/attribution/for-web
Learn how to capture referral codes on your website
When users click referral links, they land on your website first. Capture the referral code (`ucc`) on this landing page to properly attribute future conversions.
Follow these steps to set up referral code capture:
## Step 1: Set up your landing page
Create a landing page for referral traffic. Choose one approach:
* Dedicated referral landing page
* Home page with Cello New User Banner
See the [landing page optimization guide](/guides/user-experience/optimizing-landing-pages) for best practices.
## Step 2: Install attribution script
The attribution script detects the `ucc` query parameter and stores it as a first-party cookie for later attribution of conversion events.
Install the Cello attribution script - [Attribution JS](/sdk/client-side/attribution-js-introduction) - using one of these methods:
The attribution script also enables you to:
* Fetch referrer names for [landing page personalization](/guides/user-experience/personalizing-referrals)
* Get campaign parameters to [display discounts](/guides/user-experience/new-user-discounts)
* Attach `ucc` to signup forms
See the [Attribution JS reference](/sdk/client-side/attribution-js-introduction) for complete details.
## Step 3: Verify installation
Verify that the `ucc` is available on your signup page:
1. Test your website with these query parameters:
```html
https://yourwebsite.com/?productId=test&ucc=test
```
2. Verify these values are saved as cookies: `cello-product-id` and `cello-referral`
3. On your signup page, test `ucc` access from the browser console:
```javascript
window.CelloAttribution('getUcc')
```
Expected response:
```javascript
Promise {: 'test'}
```
If this test passes, the script is installed correctly.
**Using referral codes at signup**
Use `getUcc()` during user signup to retrieve the referral code, then pass it in the [signup event](/attribution/tracking-signups) to Cello.
For complex flows, save the `ucc` with your user record so it's available when sending [signup events](/attribution/tracking-signups).
# HubSpot Forms
Source: https://docs.cello.so/attribution/hubspot
Integrate the Cello attribution library with HubSpot forms to track referral conversions
## Overview
This guide shows you how to capture referral codes (`ucc`) from visitors and automatically populate them into HubSpot forms when users submit lead generation or contact forms. This enables you to track which referrals lead to qualified leads and conversions.
## Considerations when creating the `ucc` property in HubSpot
When creating a custom property in HubSpot, it is important that the internal name of the property is `ucc`. This sets up the property in either company or deal. The one to choose depends on your specific sales process and the corresponding HubSpot setup.
These instructions describe creating the `ucc` property in the object type **Company**, group **Company information**. Often, it can make sense to create the `ucc` property in the **Deal** object type. A custom property can be created following the instructions of HubSpot [here](https://knowledge.hubspot.com/properties/create-and-edit-properties).
## Step 1: Create a form with a hidden `ucc` field in HubSpot
To properly capture referral data, you need to add a `ucc` field to your HubSpot form:
1. Create a customized form in HubSpot by following the instructions [here](https://knowledge.hubspot.com/forms/create-forms).
2. In your form, create a hidden field called `ucc`. This field automatically picks up the `ucc` from the link and feeds it into the create `ucc` property in HubSpot. The result should look like this:
## Step 2: Include the Cello Attribution Library
Add the Cello attribution script to your website's `` section or before the closing `` tag:
```html
```
## Step 3: Add the Attribution Command Queue
Since HubSpot forms are loaded dynamically, include this script to handle race conditions between your code and the Cello library loading:
```html
```
**Important:** This script must be added before any calls to `window.CelloAttribution()` to prevent race conditions.
## Step 3: Integrate with HubSpot Form Creation
When creating your HubSpot form, use the `onFormReady` callback to populate the referral code. Replace the placeholder values with your actual HubSpot configuration:
```javascript
hbspt.forms.create({
region: "AAA", // Replace with your HubSpot region (e.g., "na1")
portalId: "BBB", // Replace with your HubSpot Portal ID
formId: "CCC", // Replace with your HubSpot Form ID
onFormReady(form, ctx) {
window.CelloAttribution('getUcc').then((celloUcc) => {
console.log('Incoming Referral:', celloUcc);
// Find all ucc fields and populate them
document.querySelectorAll('input[name="ucc"]').forEach(
el => {
el.value = celloUcc;
}
);
}).catch((error) => {
console.log('No referral code found or error occurred:', error);
});
}
});
```
## Test Your Implementation
### 1. Test Referral Code Capture
1. Visit your page with a referral parameter:
```
https://yoursite.com/landing-page?ucc=test123&productId=yourproduct
```
2. Open browser developer tools and check:
```javascript
// Test if ucc is available
window.CelloAttribution('getUcc')
```
Expected response: `Promise {: 'test123'}`
### 2. Test Form Integration
1. Open the page with the created form
2. Add `?ucc=demo12345687` to the link and reload the page. After the initialization of the config, this will be added automatically to the link by Cello
3. Enter some test data into the form. The result should look similar to the following
4. Submit your HubSpot form
5. HubSpot should now have created a new contact and a new company. In the new company, you should find the `ucc` property filled with the entered value `demo12345687`
6. The test was successful. You can now move ahead to the section on providing the required data to Cello.
## Troubleshooting
### Common Issues and Solutions
**1. "getReferral is not supported" error**
* Make sure you're using `getUcc()` instead of `getReferral()`
* This is the correct method for the latest attribution library
**2. Form fields not getting populated**
* Verify your form has a field with `name="ucc"`
* Check that the field selector in `querySelectorAll()` matches your form
* Ensure the `onFormReady` callback is executing
**3. Referral code is undefined**
* Test with a URL containing the `ucc` parameter: `?ucc=test123`
* Check browser cookies for `cello-referral`
* Verify the attribution script loaded properly
**4. Script loading order issues**
* Always include the command queue script before any attribution calls
* Use the `async` attribute on the attribution library script
## HubSpot Scheduling Pages Integration
You can also use the Cello attribution library with HubSpot scheduling pages to capture referral codes when prospects book meetings or demos. This is particularly useful for sales-led referral programs where referrals often lead to booked consultations or product demos.
### How it works
HubSpot scheduling pages include built-in forms that collect contact information before allowing visitors to book meetings. You can integrate Cello attribution with these forms using the same approach as regular HubSpot forms.
### Setup Steps
The integration process for scheduling pages is identical to regular forms:
1. Include the Cello Attribution Library (Steps 2-3 above remain the same)
2. Set up the `ucc` property in your HubSpot contacts/companies
3. Add a hidden `ucc` field to your scheduling page form
4. Configure the scheduling page to populate the referral code
### Adding `ucc` Field to Scheduling Pages
1. Create or edit a scheduling page ([HubSpot's scheduling page guide](https://knowledge.hubspot.com/meetings/create-scheduling-pages))
2. In the "Form" section, add the created `ucc` parameter to the form. You can't hide this field on a scheduling page. This field automatically picks up the `ucc` parameter from the link and feeds it into the created `ucc` property in HubSpot. The result should look like this:
### JavaScript Integration for Scheduling Pages
Since scheduling pages are embedded HubSpot components, you'll add the same integration code to the page where your scheduling page is embedded:
```html
```
### Testing Your Scheduling Page Integration
1. Visit your scheduling page with a referral parameter:
```
https://yoursite.com/book-demo?ucc=demo12345687
```
2. Start the booking process and fill out the form
3. Complete the booking
4. Check the created contact in HubSpot - the `ucc` field should contain `demo12345687`
### Key Differences from Regular Forms
* **Timing**: Scheduling pages load asynchronously, so we use MutationObserver to detect when the form is ready
* **Form structure**: Scheduling page forms are embedded HubSpot components with specific styling
* **Optional field**: Make the `ucc` field optional since not all meeting bookings will come from referrals
* **Meeting context**: The referral code will be associated with the contact and any resulting deals from the meeting
**For sales-led businesses**: Integrating referral tracking with scheduling pages is crucial for tracking which referrals lead to qualified sales conversations and ultimately closed deals.
# Introduction
Source: https://docs.cello.so/attribution/introduction
Learn how to implement referral attribution to track signups and purchases back to their original referrers
Referral conversion enables you to track and attribute user signups and purchases back to their original referrers and reward them for conversions.
Cello helps you capture referral codes `ucc` from landing pages and maintains attribution throughout the entire user journey, from initial visit to final purchase.
# How it works
The referral conversion process follows a four-step attribution flow:
1. **Referral Link Sharing** - Referrers share links containing unique codes (`ucc` parameters)
2. **Landing Page Capture** - Your website captures and stores referral codes `ucc` as first-party cookies
3. **Signup Tracking** - New user registrations are linked to their referrer
4. **Purchase Tracking** - Revenue events are attributed back to the original referrers
Accurate referral conversion tracking depends on properly passing the referral code `ucc` through each step of the referral journey.
**Attribution based on organization level**
If the buying persona is the organization and you want to attribute purchases on the organization level always provide the **ID of the organization** in the parameter `payload.newUserId`
# Getting started with referral conversion tracking
Learn how to track conversions with Cello in the following resources:
Capture referral code during web signup flow
Capture referral code during mobile signup
A full guide on tracking signup events
A full guide on tracking purchase events
or choose a step-by-step quickstart guide for your integration scenario:
# Track Purchases
Source: https://docs.cello.so/attribution/tracking-purchase
Learn how to track purchase events with Cello
To complete the conversion tracking and reward referrers, you will need to send Cello purchase events. A purchase event is sent when a user pays for a subscription or a product.
# Prerequisites
Before you can send Cello purchase events, make sure you are already:
* [Capturing referral code on your landing page](https://docs.cello.so/attribution/for-web)
* [Tracking signups](https://docs.cello.so/attribution/tracking-signups)
**Attribution based on organization level**
If the buying persona is the organization and you want to attribute purchases at the organization level, always provide the **ID of the organization** in the parameter `payload.newUserId`
# Track purchase events with Webhooks
Depending on which payment gateway you’re using, we offer webhooks for the following:
}
href="/integrations/webhooks/stripe-webhook"
>
Send events using Stripe Webhook
}
href="/integrations/webhooks/chargebee-webhook"
>
Send events using Chargebee Webhook
# Track purchase events with Cello API
If you’re not using any of the gateways listed above, you can also send purchase events using Cello API `POST /events` API endpoint. Here are the 2 events you will need to send:
## `invoice-paid`
This event is sent every time a transaction based on the provided subscription is successful or a new user buys a one-time plan, a license or something similar.
```bash
POST https://api.cello.so/events
{
"eventName": "ReferralUpdated",
"payload": {
"ucc": "cello-ucc",
"newUserId": "new-user-product-user-id", // or 'new-user-organization-id'
"price": 100,
"currency": "EUR"
},
"context": {
"newUser": {
"id": "new-user-product-user-id",
"email": "new-user@gmail.com",
"organizationId": "new-user-organization-id"
},
"event": {
"trigger": "invoice-paid",
"timestamp": "2022-10-05 14:14:34"
},
"subscription": {
"invoiceId": "34hsjdh34jfksd",
"interval": "one-time",
"productKey": "Pro License"
}
}
}
```
Here are the properties you can include when sending a `invoice-paid` event:
| Property | Required | Description |
| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ucc` | yes | A referral code (`ucc`) identifying the referrer. You can retrieve this code using [attribution script](/sdk/client-side/attribution-js-introduction) `getUcc ()` method, you have installed as a prerequisite to this guide |
| `newUserId` | yes | A unique ID in your system, identifying the **new user** who just signed up. Can also be **organization ID**, if your referrers can refer organizations and you want to **reward them for organization account expansion** |
| `price` | yes | Amount on the invoice |
| `currency` | yes | Currency of the amount |
| `newUser.id` | yes | A unique ID of the new user (not the organization, if you are rewarding on organization level). This should be the same ID (`productUserId`) you will use to boot the [Referral component](/referral-component/introduction), when this user logs into your app |
| `newUser.email` | yes | New user email |
| `newUser.organizationId` | no | Organization ID. Add this field if your referrers can **refer an organization** and you want to reward them for **organization account expansion** |
| `event.trigger` | yes | `invoice-paid` |
| `event.timestamp` | yes | Event timestamp in **ISO8601 format** |
| `subscription.invoiceId` | yes | ID of the invoice that was paid or refunded |
| `subscription.interval` | yes | Interval of the payment. Available options: `one-time`, `monthly`, `quarterly`, `yearly`, `biennial`, `triennial`, `lifetime`, `bi-weekly`, `semi-annual` |
| `subscription.productKey` | yes | Name of the product or plan purchased |
Full API referrence for `POST /events` API endpoint can be found [here](/api-reference/generic-events/send-event).
## `charge-refunded`
This event is sent if the payment of the new user was refunded.
```bash
POST https://api.cello.so/events
{
"eventName": "ReferralUpdated",
"payload": {
"ucc": "cello-ucc",
"newUserId": "new-user-product-user-id", // or 'new-user-organization-id'
"price": 1000,
"currency": "EUR"
},
"context": {
"newUser": {
"id": "new-user-product-user-id",
"email": "new-user@gmail.com",
"organizationId": "new-user-organization-id"
},
"event": {
"trigger": "charge-refunded",
"timestamp": "2022-10-05 14:14:34"
},
"subscription": {
"invoiceId": "34hsjdh34jfksd"
}
}
}
```
Here are the properties you can include when sending a `charge-refunded` event:
| Property | Required | Description |
| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ucc` | yes | A referral code (`ucc`) identifying the referrer. You can retrieve this code using [attribution script](/sdk/client-side/attribution-js-introduction) `getUcc ()` method, you have installed as a prerequisite to this guide |
| `newUserId` | yes | A unique ID in your system, identifying the **new user** who just signed up. Can also be **organization ID**, if your referrers can refer organizations and you want to **reward them for organization account expansion** |
| `price` | yes | Amount refunded |
| `currency` | yes | Currency of the amount |
| `newUser.id` | yes | A unique ID of the new user (not the organization, if you are rewarding on organization level). This should be the same ID (`productUserId`) you will use to boot the [Referral component](/referral-component/introduction), when this user logs into your app |
| `newUser.email` | yes | New user email |
| `newUser.organizationId` | no | Organization ID. Add this field if your referrers can **refer an organization** and you want to reward them for **organization account expansion** |
| `event.trigger` | yes | `charge-refunded` |
| `event.timestamp` | yes | Event timestamp in **ISO8601 format** |
| `subscription.invoiceId` | yes | ID of the invoice that was paid or refunded |
Full API referrence for `POST /events` API endpoint can be found [here](/api-reference/generic-events/send-event).
# Track Signups
Source: https://docs.cello.so/attribution/tracking-signups
Learn how to track signup events with Cello
When a referee signs up or otherwise shows interest in your product - like booking or attending a demo - you need to send this event to Cello. This allows Cello to attribute this conversion to the referrer, so they can be rewarded if a purchase happens later.
You can also choose to reward users for actions like signups or demos by configuring this in your [Campaign settings](/guides/campaigns/setting-up-campaigns).
# Prerequisites
Before you can send Cello signup events, you need to make sure that you are able to **capture the referral code** `ucc`**during signup or demo booking**:
* [When users sign up in your web app](/attribution/for-web)
* [When users sign up in your mobile app](/attribution/for-mobile)
* When users book a demo using [Hubspot](/attribution/hubspot) or [Typeform](/attribution/typeform) forms or scheduling
**Attribution based on organization level**
If the buying persona is the organization and you want to attribute purchases at the organization level, always provide the **ID of the organization** in the parameter `payload.newUserId`
# Tracking signup events
For a SaaS application signup flow, you will track a signup event or equivalent.
Depending on how you create a new user and which payment gateway you are using, you can choose from the following options to send Cello signup events.
## Option 1: Using Stripe - I create Stripe Customer at Signup
Use this option if your payment gateway is Stripe and you **create a Stripe customer at signup**
To track a signup, you can pass the following `metadata` to Stripe [Customer Object](https://docs.stripe.com/api/customers/object?api-version=2024-09-30.acacia#customer_object-metadata) on customer creation.
* `cello_ucc` - ucc, a referral code identifying the referrer. You can retrieve this code using [attribution script](https://docs.cello.so/sdk/client-side/attribution-lib) `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](https://docs.cello.so/sdk/client-side/cello-js), 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 fields you send upon customer creation. Here is an example for a NodeJS App that does that:
```javascript
const stripe = require('stripe')('sk_test_51KiCYYCSMQAUBF...');
const customer = await stripe.customers.create({
description: 'New Stripe Customer',
metadata: {
cello_ucc: "hdz7afhs7",
new_user_id: "xcsdad", // product user id of the new user
new_user_organization_id: "123456" // organization id of the new user
}
});
```
Now that the customer is created in Stripe with Cello metadata, a `customer.created` event will be sent with [Stripe Webhook](/integrations/webhooks/stripe-webhook), which we will count as a signup event in Cello.
## Option 2: Using Chargebee - I create Chargebee customer at signup
Use this option if your payment gateway is Chargebee and you **create a Chargebee customer at 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**](https://www.chargebee.com/docs/billing/2.0/site-configuration/custom_fields)
* `cello_ucc` - ucc, a referral code identifying the referrer. You can retrieve this code using [attribution script](/sdk/client-side/attribution-js-introduction) `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](/referral-component/introduction), when this user logs into your app
* `new_user_organization_id` (optional) - add organization ID, if your referrers can **refer an organization** and you want to reward them for **organization account expansion**.
Modify customer fields you send upon customer creation. Here is an example for a NodeJS App that does that:
```javascript
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" // organization id of the new user
}
// ..
// })
```
Now that the customer is created in Chargebee with Cello metadata, a `Customer Created` event will be sent with [Chargebee Webhook](/integrations/webhooks/chargebee-webhook), which we will count as a signup event in Cello.
## Option 3: Using Cello API POST /events API endpoint
Use this option for all other use cases. For example:
* You use Stripe or Chargebee, but customer is created in the payment gateway **at purchase**.
* Your payment gateway is Paddle, Recurly or other, including in-house built payment gateways
Send a `new-signup` event to the Cello API with the following values in the payload:
* `ucc` - ucc, a referral code identifying the referrer. You can retrieve this code using [attribution script](/sdk/client-side/attribution-js-introduction) `getUcc ()` method, you have installed as a prerequisite to this guide.
* `newUserId` - a unique ID in your system, identifying the **new user** who just signed up. Can also be **organization ID**, if your referrers can refer organizations and you want to **reward them for organization account expansion**.
* `user.id` - unique ID of the new user (not the organization, if you are rewarding on organization level). This should be the same ID (`productUserId`) you will use to boot the [Referral component](/referral-component/introduction), when this user logs into your app
* `user.email` - new user email
* `user.name` - new user name
* `user.organizationId`(optional) - add organization ID, if your referrers can **refer an organization** and you want to reward them for **organization account expansion**.
Here is an example of the `POST /events` call to send a `new-signup` event:
```bash
POST https://api.cello.so/events
{
"eventName": "ReferralUpdated",
"payload": {
"ucc": "cello-ucc",
"newUserId": "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"
}
}
}
```
# Tracking "demo attended" event
Use this option if your product follows a sales-led model where successful conversions are driven by users attending a demo call.
Send a `demo-attended` event to the Cello API with the following values in the payload:
* `ucc` - ucc, a referral code identifying the referrer. You can retrieve this code using [attribution script](/sdk/client-side/attribution-js-introduction) `getUcc ()` method, you have installed as a prerequisite to this guide.
* `newUserId` - a unique ID in your system, identifying the **new user** who just signed up. Can also be **organization ID**, if your referrers can refer organizations and you want to **reward them for organization account expansion**.
* `user.id` - unique ID of the new user (not the organization, if you are rewarding on organization level). This should be the same ID (`productUserId`) you will use to boot the [Referral component](/referral-component/introduction), when this user logs into your app
* `user.email` - new user email
* `user.name` - new user name
* `user.organizationId`(optional) - add organization ID, if your referrers can **refer an organization** and you want to reward them for **organization account expansion**.
Here is an example of the `POST /events` call to send a `new-signup` event:
```bash
POST https://api.cello.so/events
{
"eventName": "ReferralUpdated",
"payload": {
"ucc": "cello-ucc",
"newUserId": "product-user-id" // or 'new-user-organization-id'
},
"context": {
"newUser": {
"id": "new-user-product-user-id",
"email": "new-user@gmail.com",
"name": "new-user-name",
"organizationId": "new-user-organization-id"
},
"event": {
"trigger": "demo-call-attended",
"timestamp": "2022-10-05 14:14:34"
}
}
}
```
# Typeform Forms
Source: https://docs.cello.so/attribution/typeform
Ingest Cello's referral code (ucc) into HubSpot using Typeform forms
This page guides you through the required steps to ingest **Cello's referral code (`ucc`) into HubSpot using Typeform forms**.
## Create a form with a hidden ucc field in Typeform
Create a new form in Typeform
On the initial question in your form, go to **Hidden Fields** via **Logic → Hidden Fields** on the panel on the right
Add a new field named `ucc` and click Save
## Setup of Sync from Typeform to HubSpot
Navigate to the **Connect** Section in the header of Typeform and connect HubSpot
After the authorization is done, you can select the HubSpot object to which you want to sync the `ucc`. In the below example the `ucc` is synced to a deal in HubSpot.
You can also sync the `ucc` to multiple objects at the same time: contact, company and deals.
If you sync the `ucc` to a deal, you have to specify in which pipeline at which stage the deals should be created
After finalizing the setup of the integration, save the settings and run a short test run
## Test the created Typeform and HubSpot integration
Open the created Typeform
Add either `?ucc=12341234` or `&ucc=12341234` to the link depending on if there is already a "?" present in the link
Submit the Typeform
Open HubSpot and check that the contact, company or deal was created and the `ucc` was synced correctly
## Further hints
You can also embed a Calendly in Typeform to allow customers to schedule e.g. a demo from the Typeform. Documentation can be found [here](https://www.typeform.com/connect/calendly/).
# Chargebee Webhook Quickstart
Source: https://docs.cello.so/attribution/use-cases/chargebee
Learn how to integrate Cello if you are using Chargebee JS to create Chargebee customer and Chargebee Webhook to send Cello conversion events.
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 `` 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:
You can also integrate Referral Component into your mobile applications:
# Step 2: Capture referral codes on landing page
Next, you will need to add [Cello attribution script](https://docs.cello.so/sdk/client-side/attribution-lib) to your referral landing page:
1. Setup a [landing page](https://docs.cello.so/docs/optimize-landing) for your referral links to redirect to
2. Install attribution script. Choose one of the following installation options best suited for your setup:
3. Verify the installation
To verify, follow these steps:
1. Add `?productId=test` and `?ucc=test` to your website URL
```html
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
```javascript
window.CelloAttribution('getUcc')
```
This method should return a promise with value `test`
```javascript
Promise {: 'test'}
```
**If this check passes, the script is installed correctly.**
For capturing referral code in your mobile signup flow, follow this guide:
# 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**](https://www.chargebee.com/docs/billing/2.0/site-configuration/custom_fields)
* `cello_ucc` - ucc, a referral code identifying the referrer. You can retrieve this code using [attribution script](https://docs.cello.so/sdk/client-side/attribution-lib) `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](https://docs.cello.so/sdk/client-side/cello-js), 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`:
```javascript
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](https://docs.cello.so/integrations/webhooks/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:
}
href="/integrations/webhooks/chargebee-webhook"
>
Send events using Chargebee Webhook
**Congratulations!** You are done and now able to try out the full Cello referral experience 🎉
# Stripe Webhook Quickstart
Source: https://docs.cello.so/attribution/use-cases/stripe
Learn how to integrate Cello if you are using Stripe JS to create Stripe customer and Stripe Webhook to send Cello conversion events.
This guide is **optimized for the typical freemium scenario with Stripe**.
Use this guide if you:
* Create Stripe customer on signup
* Use Stripe 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 `` 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:
You can also integrate Referral Component into your mobile applications:
# Step 2: Capture referral codes on landing page
Next, you will need to add [Cello attribution script](https://docs.cello.so/sdk/client-side/attribution-lib) to your referral landing page:
1. Setup a [landing page](https://docs.cello.so/docs/optimize-landing) for your referral links to redirect to
2. Install attribution script. Choose one of the following installation options best suited for your setup:
3. Verify the installation
To verify, follow these steps:
1. Add `?productId=test` and `?ucc=test` to your website URL
```html
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
```javascript
window.CelloAttribution('getUcc')
```
This method should return a promise with value `test`
```javascript
Promise {: 'test'}
```
**If this check passes, the script is installed correctly.**
For capturing referral code in your mobile signup flow, follow this guide:
# Step 3: Add Cello metadata on Stripe customer creation
To track a signup, you can pass the following `metadata` to Stripe [Customer Object](https://docs.stripe.com/api/customers/object?api-version=2024-09-30.acacia#customer_object-metadata) on customer creation.
* `cello_ucc` - ucc, a referral code identifying the referrer. You can retrieve this code using [attribution script](https://docs.cello.so/sdk/client-side/attribution-lib) `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](https://docs.cello.so/sdk/client-side/cello-js), 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 fields you send upon customer creation. Here is an example for a NodeJS App that does that:
```javascript
const stripe = require('stripe')('sk_test_51KiCYYCSMQAUBF...');
const customer = await stripe.customers.create({
description: 'New Stripe Customer',
metadata: {
cello_ucc: "hdz7afhs7",
new_user_id: "xcsdad", // product user id of the new user
new_user_organization_id: "123456" // organization id of the new user
}
});
```
Now that the customer is created in Stripe with Cello metadata, a `customer.created` event will be sent with [Stripe Webhook](https://docs.cello.so/integrations/webhooks/stripe-webhook), which we will count as a signup event in Cello. You will connect Stripe Webhook in the next step.
# Step 4: Connect Stripe Webhook to send signup and purchase events
To send Cello signup and purchase events, you will need to connect Stripe Webhook to Cello.
Follow this guide to connect the webhook:
}
href="https://docs.cello.so/integrations/webhooks/stripe-webhook"
>
Send events using Stripe Webhook
**Congratulations!** You are done and now able to try out the full Cello referral experience 🎉
# HubSpot Reports
Source: https://docs.cello.so/guides/attribution/hubspot-reports
This guide will walk you through exporting attribution and event reports from HubSpot
This guide will walk you through exporting attribution and event reports from HubSpot. You'll create a view in HubSpot and export it as a .csv file. However, keep in mind that steps may vary based on your specific HubSpot setup and its objects and properties.
For more detailed instructions, please refer to the [HubSpot documentation](https://knowledge.hubspot.com/) and specifically [Create and export a view](https://knowledge.hubspot.com/crm-setup/create-customize-and-manage-your-saved-views).
## Creating and Exporting a View
1. Navigate to your deals pipeline in HubSpot and create a new view.
2. In the view you just created, click **Apply Filter** to show only deals where Cello's referral code (`ucc`) is known.
3. Select the required columns for the **Attribution & Event report**. Make sure that the exported records can be linked with the records in the **Purchases report** via a common field, either the `Referred Account ID` or Cello's referral code (`ucc`). The Attribution & Event report should, at the very least, contain the following fields:
* `Referred Account ID` (which equates to the `Internal Account ID`)
* `Cello's referral code (`ucc`)`
* `Custom Event`
* `Create Date`
* `Last Modification Date`
4. Save the view.
5. Finally, click **Export** to export the view to a .csv file.
With these steps, you should be able to successfully create and export your custom HubSpot reports for use with Cello.
# Manual Attribution
Source: https://docs.cello.so/guides/attribution/manual-attribution
At Cello, we understand that there may be instances where automated referral attribution doesn't work as expected
At Cello, we understand that there may be instances where automated referral attribution doesn't work as expected. In such cases, our platform provides the flexibility to manually attribute referrals to ensure that your users receive the proper rewards for their efforts. This guide will walk you through the steps of manually attributing referrals within the Cello platform.
## When to Manually Attribute Referrals
1. **Technical Glitches**: If you encounter technical issues or glitches that prevent automated attribution, manual attribution allows you to override these challenges.
2. **User Disputes**: In cases where users claim they referred someone but the system did not capture it correctly, manual attribution provides a resolution path.
3. **Custom Scenarios**: For unique situations or custom referral setups, manual attribution offers a tailored solution.
## How to Manually Attribute Referrals
1. Customer gets `cello_ucc` of referrer from the Cello Portal and retrieves `cello_ucc` of referrer and `new_user_id` (former product\_user\_id) new user from their own system. If data cannot be found, please reach out to Cello.
2. Customer adds `cello_ucc` of referrer and `new_user_id` (former product\_user\_id) ID of new user to the existing Stripe customer of new user in Stripe.
3. Cello receives a `customer.updated` event from Stripe for the customer.
4. If there were already paid invoices, please resend the past `invoice.paid` events of the new user to Cello. This can be done by:
1. Go to the transaction
2. Select the `invoice.paid` event in the feed at the bottom
3. Click **View event details**
4. Check webhook attempts and resend the event
1. Customer gets `cello_ucc` of referrer from the Cello Portal and retrieves `cello_ucc` of referrer and `new_user_id` (former product\_user\_id) ID of new user from their own system. If data cannot be found, please reach out to Cello.
2. In Chargebee, you add `cello_ucc` of referrer and `new_user_id` (former product\_user\_id) of new user to the metadata of the new user's Chargebee customer.
3. We automatically receive a `customer_changed` event via the webhook.
4. If there were already payments from the new user, you need to resend the past `payment_succeeded` events via the webhook. You can trigger this inside Chargebee manually.
1. Customer gets `cello_ucc` of referrer from the Cello Portal and retrieves `new_user_id` ID of new user from their own system. If data cannot be found, please reach out to Cello.
2. Customer resends the signup event manually via the Cello API. Fields are filled as in the automated Cello API events. The detailed documentation can be found in the [Example Requests](/api-reference/generic-events/send-event).
3. To add the parameters to the metadata in your payment gateway and resend past transactions, follow step 2-4 from the tab applicable for your payment gateway.
In case Cello API events can not be resend via API, manual reports can be provided to Cello. The reports need to contain equivalent information as the specific event. Exemplary reports can be found in [Sample Data and Reports](/guides/integration/report-automation#sample-data-and-reports)
1. Customer gets `cello_ucc` of referrer from the Cello Portal and retrieves `new_user_id` ID of new user from their own system. If data cannot be found, please reach out to Cello.
2. Customer resends the signup event manually via the Cello API. Fields are filled as in the automated Cello API events. The detailed documentation can be found in the [Example Requests](/api-reference/generic-events/send-event).
3. Customer resends past transaction events manually via the Cello API. Fields are filled as in the automated Cello API events. The detailed documentation can be found in the [Example Requests](/api-reference/generic-events/send-event).
In case Cello API events can not be resend via API, manual reports can be provided to Cello. The reports need to contain equivalent information as the specific event. Exemplary reports can be found in [Sample Data and Reports](/guides/integration/report-automation#sample-data-and-reports)
## Contact Support
If you encounter challenges or have questions during the manual attribution process, our support team is here to assist you. Reach out to us via [support@cello.so](mailto:support@cello.so) with detailed information about the referral in question, and we'll promptly assist you in resolving the matter.
# Attribution Overview
Source: https://docs.cello.so/guides/attribution/overview
Understanding your options for tracking referral attribution and measuring program performance
Attribution is the foundation of any successful referral program – it's how you connect new customers back to the users who referred them. Cello provides multiple attribution tracking options to fit different technical setups and business needs, from fully automated solutions to manual reporting workflows.
## How Referral Attribution Works
Every referral follows a four-step attribution flow:
1. **Referral Link Sharing** - Referrers share links containing unique codes (`ucc` parameters)
2. **Landing Page Capture** - Your website captures and stores referral codes as first-party cookies
3. **Signup Tracking** - New user registrations are linked to their referrer
4. **Purchase Tracking** - Revenue events are attributed back to the original referrers
## Attribution Tracking Options
Cello offers three main approaches to attribution tracking, each suited for different technical capabilities and business requirements:
### 1. Automated Attribution (Recommended)
**Best for:** Teams with development resources who want real-time, accurate tracking
**Technical Implementation Required:** Yes - Developer integration needed
Automated attribution provides real-time tracking of referral conversions through technical integrations:
* **[Web Integration](/attribution/for-web)** - Capture referral codes on landing pages using JavaScript
* **[Mobile Integration](/attribution/for-mobile)** - Track app installs through deep linking platforms like Branch.io
* **[API Integration](/attribution/tracking-signups)** - Send conversion events programmatically
* **[Webhook Integration](/integrations/introduction)** - Automatic tracking via Stripe/Chargebee webhooks
### 2. Auto-Attribution (Backup Safety Net)
**Best for:** Additional coverage to catch missed attributions
**Technical Implementation Required:** No - Works automatically
Cello's auto-attribution system acts as a safety net, detecting and recovering missed referral attributions:
* Automatically identifies potential referrals when users first open the referral widget
* Uses stored referral cookies to detect attribution gaps
* Marks recovered referrals with "AA" designation in reports
* Delays reward processing by 7 days for verification
[Learn more about Auto-Attribution →](/guides/attribution/auto-attribution)
### 3. Manual Attribution & Reporting
**Best for:** Teams without development resources or specific business requirements
**Technical Implementation Required:** No - Report-based workflow
Manual attribution relies on data exports and reports rather than real-time tracking:
#### Manual Report Generation Guides
* **[Stripe Reports](/guides/attribution/stripe-reports)** - Export customer and payment data from Stripe
* **[HubSpot Reports](/guides/attribution/hubspot-reports)** - Create filtered views and export referral data
* **[Salesforce Reports](/guides/attribution/salesforce-reports)** - Generate custom reports with referral attribution
#### Manual Attribution Process
When automated tracking fails, use [Manual Attribution](/guides/attribution/manual-attribution) to:
* Resolve user disputes about missing referrals
* Handle technical glitches in automated systems
* Address custom referral scenarios
* Backfill historical referral data
## Choosing Your Attribution Strategy
Most successful referral programs use a combination of attribution methods:
### Recommended Setup
1. **Primary:** Implement automated attribution for real-time tracking
2. **Backup:** Enable auto-attribution to catch missed referrals
3. **Fallback:** Use manual attribution for edge cases and disputes
## Getting Started
1. **Assess your technical resources** and choose your primary attribution method
2. **Review your current data flow** to identify integration points
3. **Start with one method** and add additional coverage over time
4. **Test attribution accuracy** before launching to all users
Attribution accuracy directly impacts referrer satisfaction and program success. Most customers start with manual reporting for immediate launch, then add automated attribution for scale and accuracy.
# Salesforce Reports
Source: https://docs.cello.so/guides/attribution/salesforce-reports
This guide provides the necessary steps to create and export attribution and event reports from Salesforce as a .csv file, suitable for importation into Cello
This guide provides the necessary steps to create and export attribution and event reports from Salesforce as a .csv file, suitable for importation into Cello.
Refer to Salesforce's official documentation for a more in-depth guide on [Building a Report](https://help.salesforce.com/articleView?id=reports_builder.htm\&type=5) and [Exporting a report](https://help.salesforce.com/s/articleView?id=sf.reports_export.htm\&type=5).
## Step-by-step guide
Follow these steps to generate a report that is compatible with Cello:
1. Navigate to **Reports** in Salesforce and select **New Report**.
2. Select **Opportunities** from the available report types and click **Continue**.
3. Configure your report by applying the necessary filters and selecting the desired columns from the panel on the left-hand side.
4. Save the report for potential future exports by selecting the **Save** option.
5. Click **Export** to save the report data to a .csv file, suitable for import into Cello.
Following these steps will yield a .csv report structured for import into Cello that can be leveraged for attribution and event reporting.
# Stripe Reports
Source: https://docs.cello.so/guides/attribution/stripe-reports
With Stripe, you can manually export and import them into Cello. This feature is especially handy when you need to conduct some tests before enabling full automation
With Stripe, you can manually export and import them into Cello. This feature is especially handy when you need to conduct some tests before enabling full automation.
## Generating a Stripe Customer Export
After you've enriched the Stripe Customer with the right metadata, you're ready to export it as a .csv file. To do so:
1. Navigate to **Customers** > **Overview**, and then click **Export**.
2. Specify the details for the export:
* **Date range**: If you're submitting reports weekly or even more frequently, you can always opt for **Last 7 days**. Cello is designed to avoid importing duplicates.
* **Columns**: You only need to include **ID** and **Created (UTC)**. If `cello_ucc` has been added to the Customer metadata, it will always be added as a column in the exported file.
The exported .csv file for a Stripe Customer Export might look like this:
## Generating a Stripe Payment Export
Stripe allows you to export payments as a .csv file. To do so:
1. Go to **Payments** > **All Payments**, choose **Successful**, and then click **Export**.
2. Specify the details for the export:
1. **Date range**: Just as with the customer export, you can opt for **Last 7 days** if you're submitting reports frequently. Cello will prevent duplicate imports.
1. **Columns**: The data we suggest including in the report are: **ID**, **Description**, **Created (UTC)**, **Amount**, **Currency**, **Converted Amount**, **Fee**, **Tax**, **Converted Currency**, **Customer ID**.
# Contextual Sharing
Source: https://docs.cello.so/guides/best-practices/contextual-sharing
Guide for increasing referral sharing at key moments
Increase sharing by creating referral program awareness, keeping it top of mind for users and making referrals part of your main user flow. To achieve this, we recommend utilizing **moments of delight** and regular communication.
How to encourage referrers to share at key moments in the user journey:
* [Add a CTA to refer your product](#add-a-cta-to-refer-your-product)
* [Send an instant message to introduce the referral program](#send-an-instant-message-to-introduce-the-referral-program)
* [Add referral link to regular emails](#add-referral-link-to-regular-emails)
**Contextual sharing can increase sharing rates by 3.4x**
Adding sharing prompts to just a few moments of delight can increase sharing rates more than x3.
## Add a CTA to refer your product
A product lifecycle naturally has **moments of delight** when a user would be more likely to share their satisfaction with the product within their network. Add a CTA to open the [referral component](/sdk/client-side/cello-js-usage) at such moments and make referring part of this flow.
### How to implement?
For Developers
You can add a custom button anywhere in your UI at the moment of delight and have it open the Referral Component.
1. Identify where to add the button together with your Growth manager and UX designer
2. Use [window.Cello("open")](/sdk/client-side/cello-js-usage#open-destination) method to open the Referral Component when the button is clicked.
```javascript
window.Cello("open");
```
## Send an instant message to introduce the referral program
When your user reaches a **moment of delight** in their journey, that's the time to prompt them to share your product with an introductory in-product message i.e. [announcement](/guides/user-experience/referral-notifications-and-emails#announcement). This introduces the referral program to the user at the time they feel compelled to share their experience and effectively boost the conversion rate from users to referrers.
### How to implement?
For Developers
You can trigger [an announcement](/guides/user-experience/referral-notifications-and-emails#announcement) using [Cello.js](/sdk/client-side/cello-js-usage) client-side JS method at any point of the user journey. Here is how to do it:
1. Add [announcement to your custom launcher](/referral-component/custom-launcher#add-announcement-selector), so they are displayed when triggered.
2. Use [window.Cello("showAnnouncement")](/sdk/client-side/cello-js-usage#showannouncement-announcement) method to open the Referral Component when the button is clicked.
Below example will trigger a default [welcome announcement](/guides/user-experience/referral-notifications-and-emails#announcement):
```javascript
window.Cello("showAnnouncement", { "type": "welcome-announcement-1" } );
```
You can also use a server-side API to trigger the announcement. Check out this guide [on behaviour-based triggers](/guides/best-practices/behavior-based-triggers).
## Add referral link to regular emails
Use regular communication with your users as an opportunity to remind them about the referral program and keep it top of mind. For example, add their personal invite link to your weekly updates or transactional emails.
### How to implement?
For Developers
Depending on your email sending service, you can add additional content to your email, in this case, a personal invite link. To get the link for each referrer, you can use our Cello API [/active-link endpoint](/api-reference/user-referrals/get-active-referral-link) and enrich the emails you already send to your users with information about referral program and their personal invite link.
# Improve User Activation
Source: https://docs.cello.so/guides/best-practices/improve-user-activation
Recommendations to optimize the signup conversion of referred users
This page provides recommendations to optimize the signup conversion of referred users. Cello offers a variety of options that range from stunning new user experiences with personalized website content to easy setup solutions.
## Increase discoverability of your referral program
**Get started now:**
🔗 [Show Cello floating button](/sdk/client-side/cello-js#show) by default. Contact your CS team for adjustments to the floating button.
🔗 [Custom launcher](/referral-component/custom-launcher) to add menu integrations (paid feature).
## Integrate referral ask at moments of delight
**Get started now:**
🔗 **Simple option**: Add [button or UI for opening referral widget](/sdk/client-side/cello-js#open-destination) to your existing user flows.
🔗 **Advanced option**: Set up [behavior-based triggers](/guides/best-practices/behavior-based-triggers) to send a custom message to users upon completion of a defined trigger moment.
## Enable essential notifications with Cello email campaigns
**Get started now:**
Contact your Cello CS team to activate email campaigns in Slack or at [support@cello.so](mailto:support@cello.so). Email addresses need to be provided on boot of Cello to activate certain types of emails.
### Customize Cello in-app messages
**Get started now:**
Contact your Cello CS team to activate the activation campaigns and customize messages [here](https://getcello.typeform.com/to/Np4C9iiO).
# Optimize signup conversion
Source: https://docs.cello.so/guides/best-practices/optimizing-signup-conversion
Recommendations to optimize the signup conversion of referred users
This page provides recommendations to optimize the signup conversion of referred users. Cello offers a variety of options that range from stunning new user experiences with personalized website content to super simple setup solutions.
## Increase conversion by showing discount info on website
**Get started now:**
🔗 Docs: [Personalizing referrals](/guides/user-experience/personalizing-referrals)
🔗 [Wise referral program with personalization](https://wise.com/invite/dic/tanjam2?utm_source=desktop-invite-tab-copylink\&utm_medium=invite\&utm_campaign=\&utm_content=\&referralCode=tanjam2)
🔗 [MeetGeek website with personalized new user banner](https://meetgeek.ai/meetgeek-referral?productId=app.meetgeek.ai\&ucc=vTlj7ne4Fkf\&n=VG9iaWFz)
## Increase conversion with stand-alone landing page
**Get started now:**
Once your referral landing page is ready to go, reach out to your Cello CS team in Slack or at [support@cello.so](mailto:support@cello.so) to enable forwarding new users directly to the page.
🔗 [Typeform landing page](https://www.typeform.com/refer-a-friend/invite/?utm_medium=referrerlink\&utm_source=typeform\&utm_campaign=refer_a_friend_cello\&productId=admin.typeform.com\&ucc=ARn30TGHAsq)
🔗 [Superhuman landing page with personalization](https://superhuman.com/refer?utm_source=product\&utm_medium=signature\&utm_campaign=bob%40bobinsky.me)
🔗 [Heyflow standalone landing page](https://get.heyflow.app/referral-lp?productId=go.heyflow.app\&utm_source=cello\&utm_medium=referral\&utm_campaign=Cello-RS20-C1000-D50\&ucc=2dRGoRjgP7A#start)
🔗 [Cello standalone landing page with direct signup](https://cello.so/invitation/)
# Reward structure FAQs
Source: https://docs.cello.so/guides/campaigns/faqs
Frequently asked questions about campaign setup, reward structures, and referral program management to help you optimize your program performance.
## What is a convincing reward for the referrer?
Cello provides a recommendation on how to set the reward structure during the onboarding. You can find it on your individual “Set the reward structure” page on the Onboarding Notion.
## Does Cello allow to set different reward parameters for different user segments?
Currently only one campaign can be configured. One campaign comprises both the configuration of the referral experience flow and the reward parameters specified in that flow. Cello plans to support multiple campaigns in the near future.
## Is it possible to change the reward parameters retroactively for referrals that are already completed?
Cello considers a referral as completed with the referred account becoming a paying customer of the referred product. Once a referral is completed the parameters for this referral cannot be changed anymore. Changing rewards retroactively would potentially lead to a disappointing user experience for the referrer.
## Is it possible to change the reward parameters in the future?
It is possible to change the reward parameters for the referral program for future referrals. To bring the adjustment live, both the reward parameters and the referral flow have to be updated. Once the update is live, all future completed referrals will be rewarded according to the updated reward parameters. This is also the case even if the referrer shared the referral link still seeing the previous reward structure.
## Which currencies does Cello support for rewarding users?
Currently, rewards for referrers are available in all currencies that Paypal supports. You can find more details in the Paypal documentation.
## From which reward options can a referrer choose?
Cello currently offers payouts via Paypal. The list of supported countries for payouts is ”Austria, Belgium, Canada, Czechia, Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Netherlands, Norway, Poland, Portugal, Romania, Spain, Sweden, Switzerland, United Kingdom, United States” Additional reward options like gift cards, bank transfers, donations are on our backlog. Venmo is available for the US upon request.
# Setting Up Campaigns
Source: https://docs.cello.so/guides/campaigns/setting-up-campaigns
Cello makes it easy to automatically notify and reward your users for making successful referrals
Cello makes it easy to automatically notify and reward your users for making successful referrals. This is done by creating **campaigns** with specific **payout rules.**
Your rules are then automated based on confirmation of **events** and **purchases.** These can be based on transactions for referred contacts, but can also be based on free trials, demos, or events you define.
## Example: Recurring Rewards Encourage Continuous Sharing
In this typical example, a referrer is rewarded **50%** for each referral up to a **\$100 maximum reward cap** with a **\$5 signup bonus**. The referee initially purchases a **\$10** subscription for herself, and then **upgrades her team** in the following month.
The reward is paid to the referrer over a 6 month period until the referrer reaches a **maximum cap of \$100** for this referral. In the meantime, these regular rewards encourage further sharing.
It's important to note that the **new user also receives an exclusive 50% discount** from the referrer when purchasing for the first 6 months. Our research shows that **symmetric rewards** (i.e., the referrer and the referred have incentives of similar values) work best because referrers invest their social capital when recommending a product; having similar incentives makes the referral look fair to both parties involved.
## Campaign Settings
All campaigns must have one or more rules to reward referrers for the referrals they made. **Campaign** settings can be configured in the [Cello portal in the Setup section](https://portal.cello.so/setup/campaigns).
Rewards are typically based on a **percentage** of the transaction amount generated when new customers make a payment up to a **maximum** amount per referral. Additional rewards can also be set on other key events such as **signups** and **purchases** to help encourage more engagement and sharing.
| **Section** | **Rule** | **Description** |
| --------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Referrer Reward | Percentage of revenue | Percentage of attributed new revenue that will be paid as a reward |
| Referrer Reward | Maximum reward (per referrer) | The maximum reward that can be earned per referral |
| Referrer Reward | Bonus rewards | Additional rewards that can be set for signups or purchases to encourage more sharing. Bonus rewards are also recommended for products with longer free to paid conversion times. |
| New User Reward | Percent Discount and Months | The new user discount to encourage additional sharing. |
Cello uses the new user reward settings to display to the new user on your signup screens. You will need to take additional steps to implement the discount at the point of purchase. See the docs [here](referee-rewards-in-stripe) for more information.
### A note on optimizing your campaigns
In this example, while the referrer would not receive a payout beyond their 6th month, it is likely that more referrals are made within this 6-month period that are likely to convert to paid plans within the 6-month period. This is based on the actual conversion rate of this specific product.
Overall, this campaign was designed to create a rewarding experience with continuous, regular incentives that encourage referrers to continue sharing with new contacts. We recommend that you design and optimize your campaigns in a similar way to build trust and encourage continued sharing behaviors with your referrers.
# Introduction
Source: https://docs.cello.so/guides/introduction
Your complete playbook for building and optimizing successful referral programs with Cello
Welcome to the Cello Growth Guides – your comprehensive resource for maximizing the impact of your referral program. These guides are designed specifically for growth managers, marketing leaders, and customer success teams who want to turn their users into their most valuable acquisition channel.
## What You'll Find Here
Our guides are organized into strategic areas that address the full lifecycle of referral program management, from initial setup to advanced optimization techniques.
### Campaign Management
**Set up reward structures that drive results**
* [Campaign Setup](/guides/campaigns/setting-up-campaigns) – Configure reward percentages, caps, and payout rules that motivate both referrers and new users
* Master symmetric reward strategies that balance **referrer incentives** with **new user discounts**
### User Experience Optimization
**Create seamless referral experiences that users love**
* [Referral Component Overview](/guides/user-experience/overview) – Understand all the features available in your referral widget
* [Component Configuration](/guides/user-experience/configuring-referral-component) – Customize appearance, messaging, and behavior
* [Landing Page Optimization](/guides/user-experience/optimizing-landing-pages) – Design high-converting referral landing pages
* [In-app and Email Notifications](/guides/user-experience/referral-notifications-and-emails) – Keep users engaged with timely updates
* [Personalized Experiences](/guides/user-experience/personalizing-referrals) – Add referrer names and custom messages
* [New User Discounts](/guides/user-experience/new-user-discounts) – Configure discount strategies for referred users
### Growth Best Practices
**Proven strategies to increase sharing and conversions**
* [Contextual Sharing](/guides/best-practices/contextual-sharing) – Prompt referrals at high-intent moments
* [Behavior-Based Triggers](/guides/best-practices/behavior-based-triggers) – Automate referral prompts based on user actions
* [User Activation Improvement](/guides/best-practices/improve-user-activation) – Convert more referrals into active users
* [Conversion Optimization](/guides/best-practices/optimizing-signup-conversion) – Maximize signup rates from referral traffic
### Partner Program Management
**Scale beyond user referrals with strategic partnerships**
* [Partner Program Overview](/guides/partners/partner-overview) – Set up affiliate and influencer programs
* [Partner Portal](/guides/partners/partner-portal) – Provide partners with dedicated dashboards and resources
* [Partner Management](/guides/partners/manage-partners) – Invite, onboard, and manage your partner network
### Attribution & Reporting
**Track performance and prove ROI**
* [Auto-Attribution](/guides/attribution/auto-attribution) – Automatically track referral conversions
* [CRM Integration Reports](/guides/attribution/hubspot-reports) – Connect referral data to HubSpot, Salesforce
* [Payment Platform Reports](/guides/attribution/stripe-reports) – Track revenue attribution through Stripe
### Data & Integrations
**Connect Cello to your growth stack**
* [Data Exports](/guides/data-sync/cello-data-exports) – Extract referral data for analysis
* [API Data Sync](/guides/data-sync/api-data-sync) – Programmatically sync referral data
* [Event Testing](/guides/integration/event-testing) – Validate your referral tracking setup
## Getting Started
If you're new to Cello or referral programs:
1. **Start with [Campaign Setup](/guides/campaigns/setting-up-campaigns)** to configure your reward structure
2. **Review [User Experience Overview](/guides/user-experience/overview)** to understand the referral component features
3. **Implement [Contextual Sharing](/guides/best-practices/contextual-sharing)** strategies to increase sharing rates
4. **Set up [Attribution](/guides/attribution/auto-attribution)** to track and reward successful referrals
## Need Help?
Each guide includes actionable steps and real examples from successful Cello customers. For additional support:
* Contact your Customer Success team via Slack
* Email [support@cello.so](mailto:support@cello.so) for technical questions
* Schedule a strategy session to review your program performance
These guides focus on growth strategy and program optimization. For technical implementation details, visit our [Developer Documentation](/referral-component/quickstart) and [API Reference](/api-reference/introduction).
# Manage Partners
Source: https://docs.cello.so/guides/partners/manage-partners
Cello allows you to manage your partners and affiliates to provide them with a full portal experience
Cello allows you to manage your partners and affiliates, providing them with a full portal experience for accessing their affiliate links, tracking referral progress, and receiving rewards for successful referrals. Inviting partners takes only a few clicks.
## Inviting New Partners to Your Program
1. Navigate to the **Partner Users** page in the Cello Portal and click **Add New Partner** in the upper right. If you do not see this page, contact Cello support to have additional permissions applied to your account.
2. Enter the **email** and **campaign** you want to assign to the partner user. **Product User ID** is optional and should be added if you want to update an existing user to partner status.
Adding a Product User ID` ensures that the referrer's referral code (`ucc\`) will be retained if they are either: (1) moving from a user-led campaign to an affiliate campaign, or (2) moving from an old affiliate campaign to a new one.
If you do not specify the Product User ID, Cello automatically creates a new identifier, and the user will then have two separate referral links: one inside your product and one in the Cello portal.
3. Click **Send Invite**.
4. The partner user will receive a branded email invitation with instructions to register.
5. From this email, they can click a link to register quickly, either using **sign up with Google** or by providing an email and password. (Note: If a user signs up using email, they can later use Google to sign in with the same email address.)
# Overview
Source: https://docs.cello.so/guides/partners/partner-overview
Cello allows you to set up and manage all aspects of your own partner program, unifying user referrals and partners in one platform
Cello allows you to set up and manage all aspects of your own partner program, unifying user referrals and partners in one platform. All partner features are offered as part of the core Cello platform without additional technical effort needed.
Cello provides support on setting up your partner program or if you have an existing program that you would like to transfer to Cello. Feel free to contact our support team via Slack to guide you through the setup.
You can find a [walkthrough of the Partner Portal](https://www.loom.com/share/f8f5c502832b485da6ffb1186bd00d89?sid=2f71041c-ab22-4088-9c71-e19757c229d8) end-user experience here
## Steps for setup:
#### 1. Integrate Cello
If you are already using Cello for user referrals, there is no additional technical effort required to enable partners. If you are not yet using Cello, your teams will need to setup a [landing page for referrals](/guides/user-experience/optimizing-landing-pages) and [referral conversion tracking](/attribution/introduction) to automate rewarding.
#### 2. Set Reward Structure
To incentivize affiliates, influencers, and other partners to share your product, you can offer partners exclusive reward structures. Lifetime rewards and one-off compensation components increase the engagement of your partners and make the program more attractive. You can also see what other customers are doing in [this slide deck](https://app.pitch.com/app/presentation/e0b19633-db69-4984-840e-59184b90c2cf/1f57b9cf-0721-401e-89e8-f14f4f84980c/8ee44ff9-aac6-49cb-84e8-d31e1b118d89)
#### 3. Invite Partners
The Cello [Partner Portal](/guides/partners/partner-portal) provides partners with a full experience that includes details of your program, their personal sharing link, updates on the status of their referrals and rewards. You can invite new partners to your program from the [Manage Partners](/guides/partners/manage-partners) page in the Cello portal.
## Optional steps:
For an optimal partner experience, we recommend several best practices to improve performance. You can find more information [here](https://pitch.com/v/h7cf3r/99812f2e-e331-4c58-b84b-009723fc3220).
**1. Create a Media Kit (Optional)**
We recommend providing [media kits](https://pitch.com/v/h7cf3r/46528f51-d7b5-4e45-a94c-e4521d3b55b1) for partners on your ambassador page. Prewritten messages and branded assets make sharing frictionless for your partners and allows you to ensure brand consistency across all collaborations.
**2. Create an Ambassador Landing Page (Optional)**
Implementing a dedicated [ambassador landing page](https://pitch.com/v/h7cf3r/467b3ed2-b50f-4dd9-a280-e358ce2e8ea3) for your partners provides clear guidance on how they can get access to your program, what your program offers, and guidelines for collaboration. Moreover, an ambassador landing page can allow you to effortlessly collect applications from potential partners interested in joining your program.
## Transfer an existing program (optional):
It's easy to transfer an existing partner program using another product or in-house tools to Cello. Once transferred your existing partners can get rewarded on Cello and use the new links to make referrals. Cello can share details and assist upon request.
# Partner Portal
Source: https://docs.cello.so/guides/partners/partner-portal
The partner portal provides full portal experience for accessing their affiliate link, tracking progress on referrals, and getting rewarded for successful referrals
The partner portal provides full portal experience for accessing their affiliate link, tracking progress on referrals, and getting rewarded for successful referrals. Inviting partners only take a few clicks.
Accessing Program Details
Partners can access program details by clicking on **Your Sharing Link** on the left navigation. All details are provided from the Cello referrals component, in the same way your users access Cello from within your application.
## Getting Rewarded
Clicking on **Your Reward Details** opens the Cello component with details of all rewards. Partners who have not provided payment details can do so from this page.
## Partner Analytics
Cello provides partners with detailed analytics for tracking program performance on their referrals. An overview is provided on the **Home** page, with more details provided on the full funnel from the **New User Signups** and **New User Purchases** page .
# Partner Resources
Source: https://docs.cello.so/guides/partners/partner-resources
This guide is designed to help Partner Managers effectively use the Partner Resources feature to add, manage, and share guides and resources with partners
This guide is designed to help Partner Managers effectively use the Partner Resources feature to add, manage, and share guides and resources with partners.
The Partner Resources section is a dedicated space for creating and managing guides and content that can be shared with your partners. It allows you to:
1. Add new guides with detailed descriptions and cover images.
2. Organize resources for easy partner access.
3. Provide links to videos, articles, or pages to help partners promote your products or services.
### Adding a New Guide
If no resources are added yet, you'll see a placeholder message encouraging you to create your first guide.
1. **Click the "Add New Guide" Button**:
* Located at the top right of the Partner Resources dashboard.
2. **Fill Out the Form**:
* **Title**: Enter a clear and concise title for the guide.
* **Description**: Provide a brief description of the guide's purpose.
* **Cover Image**: Upload an image to visually represent the guide. Use the "Select files" area to drag and drop or browse files from your machine.
* **Link**: Add a URL to direct partners to the guide's content, such as a video, article, or webpage.
3. **Save the Guide**:
* Click the **Add** button to save the guide.
💡 **Once added, guide is instantly visible for your partners.**
### Managing Existing Guides
Once guides are added, they appear as individual cards in the Partner Resources dashboard. Each card includes:
1. **Title and Description**: A quick summary of the guide.
2. **Actions**:
* **Edit**: Use the pencil icon to update the guide's details.
* **Delete**: Use the trash icon to remove the guide.
3. **Call-to-Action Buttons**:
* Depending on the link type, buttons like "Watch Video," "Read Article," or "Go to Page" will appear, directing users to the linked resource.
## Best Practices for Creating Guides
1. **Use Descriptive Titles and Images**:
* Ensure titles are specific and relevant to the guide's content.
* Upload visually appealing and professional cover images to attract attention.
2. **Organize by Purpose**:
* Group guides by themes, such as "Overview," "Sharing Tips," or "Content Creation Examples," for easier navigation.
3. **Test Links**:
* Verify that all links lead to the correct resource and are accessible to partners.
## Example Use Cases
### Case 1: Sharing Partner Links
Create a guide titled **"Overview"** with a description like: "Share your partner link with contacts and followers." Include a video tutorial link to help partners understand how to use their referral links.
### Case 2: Promoting Your Product
Add a guide titled **"Share"** with instructions on promoting your product. Link to an article that offers best practices for sharing content on social media.
### Case 3: Content Creation Support
Provide a guide titled **"Content"** with social media post templates and examples. Link to a page where partners can download assets or view tips.
## Frequently Asked Questions (FAQs)
### Q: Can I reorder the guides?
A: Currently, guides are displayed in the order they were added. You may delete and recreate guides to adjust the sequence if necessary.
### Q: What file formats are supported for cover images?
A: Common image formats like JPG, PNG, and GIF are supported.
### Q: How do I ensure partners can access the links?
A: Use publicly accessible links or grant appropriate permissions to ensure partners can view the resources.
***
# Configuring Referral Component
Source: https://docs.cello.so/guides/user-experience/configuring-referral-component
The Referral Component is an all-in-one referral experience, easily added to your web application
The Referral Component is an all-in-one referral experience, easily added to your web application. It takes care of things like referrer first-time experience, enabling users to share links, updating them on progress, and handling rewards.
## Adding the component to your product
First, add the Referral Component into your application with the help of your developer. Simply follow the instructions on the [Referral Component integration guide](/referral-component/quickstart).
## Customize referrer experience
After adding component to your application, you now can customize referrer experience in Cello Portal.
### Choose Cello button design and position
You can use either the default Cello button (FAB) or integrate Cello into a menu via the [custom launcher](/referral-component/custom-launcher), or both as the launcher. If you do not want to use the Cello button, simply uncheck "Show Cello button".
If you are using the Cello button, you can choose on of **3 styles**, configure its position and also specify how would you like to display the [announcements](/guides/user-experience/Referral-Notifications-And-Emails#announcement).
### Choose component type
Component can be displayed as a **pop-up** or a **modal**. When you choose pop-up view, you can also configure pop-up position on the screen.
### Choose your brand colors for Component
You can choose primary color for your component, colors of the Cello button and color of [notification badge](/guides/user-experience/Referral-Notifications-And-Emails#alert-and-badge).
### Choose social sharing options
Cello provides many sharing options to choose from. Simple link copy, social sharing including Twitter, LinkedIn, and email, and transfer to mobile by using a QR-code where a user can forward the invite using all the options provided directly from their mobile device.
### Choose payment method options
Cello allows users to receive rewards via PayPal or Venmo payments. Additional payment options are planned based on user feedback.
# New User Discounts
Source: https://docs.cello.so/guides/user-experience/new-user-discounts
Offering discounts or rewards to referees is a powerful strategy for improving signup conversion
Offering discounts or rewards to referees is a powerful strategy for improving signup conversion for several reasons:
1. **Sense of Urgency:** Time-limited discounts create a sense of urgency, encouraging referees to act swiftly to take advantage of the offer. This urgency can lead to quicker decision-making and increased conversion rates.
2. **Enhancing Referral Motivation:** When referrers know that their referrals lead to tangible benefits like discounts for their contacts, they're more likely to actively promote your product. This not only increases the number of referrals but also the likelihood of signups.
3. **Overcoming Price Resistance:** Discounts can effectively lower financial barriers for potential users who are hesitant about the cost. By making the price more attractive, it can sway those who are undecided about trying your product or service.
4. **Building Initial Trust:** Offering a discount can foster goodwill and build initial trust with new users. A special deal can create a positive first impression of your brand, setting the stage for a lasting relationship.
5. **Competitive Advantage:** If your competitors do not offer similar incentives, your discount can give you a competitive edge. This unique selling point can make your product more appealing compared to others in the market.
This page describes how a **discount to the new referred account can be automated using Stripe or Chargebee** (e. g. 50% discount for the first 6 months).
## Configure discount information
Altho handling discounts needs to be done within your product and supporting systems like Stripe or Chargebee, you can specify discount information in Cello to be shown in the Referral Component and terms.
Go to [Campaign settings in Cello Portal](https://portal.cello.so/setup/campaigns) and add discount information, by specifying discount percentage and duration in months:
How do I grant discounts in Chargebee?
Chargebee uses **coupons** to apply discounts on subscriptions. To grant a discount for a new referred account, the following steps are required:
* Create a coupon either via the [Chargebee Dashboard](https://www.chargebee.com/docs/2.0/coupons.html#creating-coupons) or the [Chargebee API](https://apidocs.chargebee.com/docs/api/coupons?prod_cat_ver=2)
* Attach the coupon code to the [subscription](https://apidocs.stagingcb.com/docs/api/subscriptions?prod_cat_ver=2)
## How do I grant discounts in Stripe?
Stripe uses **coupons** and **promotion codes** to apply discounts on payments. To grant a discount for new referred accounts, these coupons and promotion codes have to be set up in Stripe.
This can be done in multiple ways. For both solutions, you **must first set up a coupon and then attach the discount rules** (e.g. 10% off for 3 months).
* Manually using the [Stripe Dashboard](https://dashboard.stripe.com/coupons)
* Programmatically using the [Stripe API](https://stripe.com/docs/payments/checkout/discounts#promotion-codes).
## Using coupons for discounts
Coupons can be used to attach a discount directly to a **stripe customer** or a **subscription.** This can be achieved manually via the [Stripe Web Console](https://dashboard.stripe.com/coupons) or the [Stripe API](https://stripe.com/docs/billing/subscriptions/coupons?dashboard-or-api=api).
Attach manually via **Stripe Web Console**:
Attach the coupon during customer creation as discount field via **Stripe API:**
### Attach the coupon to the customer or subscription
To give the discount to a new user, you need to attach the coupon to a customer or subscription. There are two ways to attach the coupon, manually or via API.
If you attach the coupon to a customer, the discount is applied to every transaction or subscription. You can limit the coupon in settings with certain conditions.
### Manual attachment of the coupon to the customer in advance
This is only possible if the stripe customer is already created and no transaction has been created yet.
1. Go to your Stripe Console
2. Open the customer, go to **Actions,** and select **Apply coupon**
3. Select the coupon you want to attach
**💸 If the customer subscribes now to a plan or performs a transaction, the discount will be automatically applied during the checkout.**
### Attach the coupon during checkout with Stripe API
The prerequisite for this solution is to have implemented the [Stripe.js](https://stripe.com/docs/js) in your front end so you can modify the customer creation or subscription.
Attach the discount already while creating the customer and adding the `cello_ucc` code.
Example for a NodeJS App — attach coupon while creating the customer **(recommended)**:
```javascript
const stripe = require('stripe')('sk_test_51KiCYYCSMQAUBF...');
const customer = await stripe.customers.create({
description: 'New Stripe Customer',
coupon: 'lHTYr6Y9',
metadata: {
'cello_ucc': 'hdz7afhs7',
'product_user_id': 'xcsdad'
}
});
```
Example for a NodeJS App — attach coupon code during the checkout and re-use an existing customer:
```javascript
const session = await stripe.checkout.sessions.create({
mode: "subscription",
line_items: [
{
price: priceId,
quantity: 1
},
],
customer: 'cus_dbhsahd7fhsd',
discounts: [{
coupon: 'lHTYr6Y9',
}],
});
```
The Stripe UI will automatically pick up the discount and visualize it during the checkout
## Using promotion codes for discounts
A **Promotion Code** represents a customer-redeemable code for a coupon. They can be used for the **Stripe Payment Link** **or custom-built forms**. Here are their key characteristics:
* When using a **Promotion Code,** the setup of an underlying coupon is also required.
* **Promotion Codes** can be used to create multiple codes for a single coupon.
* Because **Promotion Codes** are used by customers to redeem a coupon, they are exposed to customers.
### Pre-fill the promotion code in Stripe Payment Link
With the URL parameter `prefilled_promo_code` a promo code can be automatically passed to the UI. The form automatically picks up the parameter from the URL and pre-fills the promotion code field. More details can be found [here](https://stripe.com/docs/payments/payment-links#url-parameters).
**Example:**
10% off for 3 months via promo code `CELLO`
[https://buy.stripe.com/cello?prefilled\_promo\_code=CELLO](https://buy.stripe.com/cello?prefilled_promo_code=CELLO)
# Optimizing Referral Landing Page
Source: https://docs.cello.so/guides/user-experience/optimizing-landing-pages
This guide focuses on optimizing landing pages for referrals, a critical step in the user journey
This guide focuses on optimizing landing pages for referrals, a critical step in the user journey. A referee's first interaction with your product occurs when they follow an invite link, making the page they land on a key determinant in the success of your referral program.
### In this guide
This guide walks you through the key building blocks of a referral-optimized landing page to ensure referees smoothly transition from interested to signing up.
There are a few approaches you can take when designing your referee signup flow:
* [Using a dedicated landing page](#dedicated-landing-page) Recommended
* [Using your home page as the landing page with inline personalization](#home-page-as-the-landing-page-with-inline-personalization)
* [Using your home page as the landing page with our new user banner for personalization](#home-page-as-the-landing-page-with-new-user-banner) No code
## Dedicated landing page
A dedicated page that the referee lands on when clicking on the invite link has shown to have up to **x2 higher conversion rate** if done right. Below, you can find examples of the landing pages we like along with the key building blocks to make a dedicated landing page perform.
### Key building blocks
#### Headline: Personalized Exclusivity
Craft a headline that feels exclusive and personal. [Use personalization](#add-personalization) for additional social proof like adding the referrer's name, and highlight [any special discount or reward](#add-a-new-user-discount-or-reward). This approach creates a sense of trust and urgency.
#### Key Value Proposition: Clarity in One Sentence
Distill your product's core benefit into a single, compelling sentence. This should quickly inform the visitor whether your product meets their needs, making their decision process easier and faster.
#### Content: Concise and Informative
Streamline your content compared to your main homepage. Provide just enough detail to help visitors understand your product and how it can work for them, without overwhelming them or necessitating navigation away from the page.
#### CTA Focus: Direct and Offer-Centric
Make your Call-to-Action (CTA) clear and direct, with an emphasis on the action you want the referee to take. If there's a special offer or discount, ensure your CTA highlights this to maximize conversion.
#### Social Proof: Credibility through Endorsements
Include social proofs such as G2/Capterra badges, Trustpilot ratings, customer logos, and quotes. These elements build trust and credibility, showing potential users that others have had positive experiences with your product.
#### FAQs: Contextual Information
Integrate a section for Frequently Asked Questions (FAQs) to address common queries. This helps provide referees with all the necessary information on the same page, reducing the likelihood of them leaving the page without signing up. If they return later, they can still be tracked towards the referral, but the best time to capture a new user is the first time they click the referral link.
### Add a new user discount or reward
Offering discounts to referees effectively boosts signup conversion by fostering urgency, encouraging active promotion, reducing cost concerns, and giving a competitive advantage when similar incentives aren't available from competitors. [Learn more about adding discounts 👉](/guides/user-experience/adding-discounts)
If your program offers discounts or rewards to referees, make sure to highlight it in the Headline and CTA.
💡 Our research shows that **symmetric rewards** (i.e. the referrer and the referred have incentives of similar values) are more effective. This happens because referrers invest their social capital when recommending a product; having similar incentives makes the referral look fair to both parties involved.
**Examples of dedicated landing pages**
🔗 [Heyflow stand-alone landing page](https://get.heyflow.app/referral-lp?productId=go.heyflow.app\&utm_source=cello\&utm_medium=referral\&utm_campaign=Cello-RS20-C1000-D50\&ucc=2dRGoRjgP7A#start)
🔗 [Cello stand-alone landing page with direct signup](https://cello.so/invitation/)
### Add personalization
*"The most credible advertising comes straight from the people we know and trust. More than eight-in-ten global respondents (88%) say they completely or somewhat trust the recommendations of friends and family." Nielsen Global Trust in Advertising Report, 2021*
Personalization and social proof, like using the referrer's name on the landing page, can contribute to converting referees into users. The personalization establishes trust and credibility, makes the offer more relevant and engaging, leverages an existing relationship, fosters a sense of community and belonging, reduces perceived risk, and has an emotional appeal. These elements together make the referral more compelling, encouraging referees to sign up. [Learn more about personalization 👉](/guides/user-experience/personalizing-referrals)
💡 **Leveraging existing assets -** Do you already have an optimized landing page for ads? You don't need to start from scratch. Reuse the layout and some of the content to build a dedicated referral landing page.
**Examples of personalized landing pages**
🔗 [Reword stand-alone landing page with personalization](https://reword.com/referral?productId=reword.com\&ucc=IX2FHjt1Y0Z\&celloN=Q29udGVudCBDeWJvcmc)
🔗 [Wise Referral Program with personalization](https://wise.com/invite/dic/tanjam2?utm_source=desktop-invite-tab-copylink\&utm_medium=invite\&utm_campaign=\&utm_content=\&referralCode=tanjam2)
🔗 [Superhuman landing page with personalization](https://superhuman.com/refer?utm_source=product\&utm_medium=signature\&utm_campaign=bob%40bobinsky.me)
## Home page as the landing page with inline personalization
Use your existing home page as landing page and [add a discount](/guides/user-experience/new-user-discounts) and [personalization](/guides/user-experience/personalizing-referrals) into your home page Headline and CTA.
## Home page as the landing page with New User Banner
The [New User Banner](/guides/user-experience/personalizing-referrals) is easily added to your landing page by integrating the [Cello attribution library](/sdk/client-side/attribution-lib). Visitors who follow the Cello invite link will have a banner that includes the discounts, tailored CTA, and personalization on your home page.
**Examples of landing pages with new user banner**
🔗 [MeetGeek Website with personalized new user banner](https://meetgeek.ai/meetgeek-referral?productId=app.meetgeek.ai\&ucc=vTlj7ne4Fkf\&n=VG9iaWFz)
## Get started now
Once your referral landing page is ready to go, go to you product dashboard [New User Experience setup page](https://portal.cello.so/setup/new-user-experience) and switch to **Custom landing page**.
In **Custom landing page URL** field, add the URL to your new landing page and **Save**.
# Overview
Source: https://docs.cello.so/guides/user-experience/overview
The Referral Component is an all-in-one referral experience, easily added to your web application with just a few lines of code
The Referral Component is an all-in-one referral experience, easily added to your web application with just a few lines of code. It takes care of things like referrer first-time experience, enabling users to share links, updating them on progress, and handling rewards. This functionality helps to keep your users happy and engaged with your referral program.
Let's review some of the key capabilities 👉
## Adding the component to your product
Adding the Referral Component to your product is straightforward. You can get it up and running in your test environment in just a few minutes. Simply follow the instructions or the [Referral Component Quickstart](/referral-component/quickstart).
Cello provides a few different options to add the component to your product. You can use either the default Cello button (FAB) or integrate Cello into a menu via the [Custom Launcher](/referral-component/custom-launcher). Either option can open with the component appearing as a pop-up or modal view.
## First-time experience
The Cello Referral Component provides an onboarding experience for first-time users of the program. It's a way to get users excited about the opportunity and explain how the program works in 3 easy steps. All the texts of the onboarding experience can be customized to better explain your unique value proposition.
## Your offer, front and center
The referral program text and offer are fully customizable and can be translated into multiple languages.
## Easy sharing
Cello provides many sharing options to choose from. Simple link copy, social sharing including Twitter, Facebook, LinkedIn, and email, and transfer to mobile by using a QR-code where a user can forward the invite using all the options provided directly from their mobile device.
## Engaging users with announcements
The Cello Referral Component provides a robust announcement feature to activate first-time referrers, keep the referral program top of mind, encourage repeat behaviour, and keep your users up to date with important updates.
Announcements can be customized based on the Referral Component integration option you have chosen. [Anchor announcements to a specific menu item](/referral-component/custom-launcher#add-announcement-selector) or choose to have them appear as toasts or banners.
## Keeping users update with emails
Referral programs thrive on timely engagement. Knowing instantly when there's activity tied to a referrals means your users can celebrate successes and continue to share more effectively. Whether it's their first successful share, a brand-new signup or unlocking a new reward, email notifications ensure they never miss a beat in the referral journey.
## Getting Rewarded
When users receive their first reward, they will be prompted to provide payment details and can select how they would like to receive their reward. They may also be asked to provide additional information if required to receive a payment in their specific country.
## Reward Countries and Payout Methods
Cello supports a growing list of countries\* where users can receive reward payments. Cello plans to continue expanding support for additional countries based on user feedback.
Cello can be automatically hidden for users in unsupported countries by providing country information when [integrating the Referral Component](/sdk/client-side/cello-js#celloboot). This is recommended to provide the best experience for your users.
Cello allows users to receive rewards via PayPal or Venmo payments. Additional payment options are planned based on user feedback.
All users are subject to the Cello [Terms of Service](https://cello-growth.notion.site/Terms-of-Service-40b8093e87e04429b862a601a1d23fc1/) and [Privacy Policy](https://cello-growth.notion.site/Privacy-Policy-for-Platform-76a94bd64cb44e1f92a6cec3ec5643ca) and can access details through the links that are provided. Referrers are able to get rewarded as a business and receive invoices for tax purposes.
Users are required to provide additional taxpayer information based on the specific country of residence and local reward thresholds or choose to be paid as a business by providing their VAT number.
Cello allows users to download credit notes directly from the Cello Referral Component. If they have at least one reward, they will see a link "Tax Information" link from the rewards tab under "Update Payment Details". Users who no longer have access to the Cello component can contact [support@cello.so](mailto:support@cello.so) to receive their credit notes through a standard support process.
*Supported Reward Countries: Australia, Austria, Bahrain, Belgium, Bermuda, Botswana, Brazil, Bulgaria, Canada, Cayman Islands, Chile, Croatia, Czechia, Denmark, Dominican Republic, Estonia, Faroe Islands, Finland, France, French Guiana, Georgia, Germany, Gibraltar, Greece, Greenland, Guatemala, Hong Kong SAR, Hungary, Iceland, India, Ireland, Israel, Italy, Japan, Latvia, Lesotho, Liechtenstein, Lithuania, Luxembourg, Malta, Mauritius, Mozambique, Netherlands, Nicaragua, Norway, Oman, Philippines, Poland, Portugal, Qatar, Romania, San Marino, Saudi Arabia, Senegal, Slovakia, Slovenia, South Africa, Spain, Sweden, Switzerland, Thailand, Ukraine, United Kingdom, United States, Uruguay, Zambia, Zimbabwe.*
## Texts and language
You can customize the default text that appears on the Referral Component and provide different language options for your users. The Cello component detects a user's language automatically or you can set it [using Referral Component JS methods](/sdk/client-side/cello-js).
We provide English, German, Spanish, French, Dutch, Italian, Portuguese, Japanese, Danish and Slovak by default and Cello will help you add additional languages on request.
# Personalizing Referrals
Source: https://docs.cello.so/guides/user-experience/personalizing-referrals
Add personalized messages to your landing pages to increase conversion rates
In this guide we will go through:
* The benefits of personalization
* How to add personalization to your landing pages:
* [Inline](#add-personalization-to-the-headline-or-other-page-element) Recommended
* [Using the new user banner](#add-personalization-with-new-user-banner) No code
## Why personalization?
Personalization and social proof, such as including the referrer's name in the landing page headline, are crucial for converting referees into signed-up users due to several key reasons:
1. **Enhanced Trust and Credibility:** Seeing a familiar name like "Bob has gifted you a free month to try Moonly" immediately establishes a sense of trust. The referee recognizes the referrer, which lends credibility to the offer.
2. **Increased Relevance and Engagement:** Personalization makes the offer feel more tailored and relevant to the referee. A message that appears to be handpicked for them can create a stronger emotional connection and engagement with the content, increasing the likelihood of a positive response.
3. **Leveraging Existing Relationships:** Utilizing the referrer's name capitalizes on the existing relationship between the referrer and the referee. This relational dynamic can be a powerful motivator, as referees often value and trust the opinions and choices of their friends or contacts.
4. **Creating a Sense of Community and Belonging:** Personalized messages can give referees the feeling of being part of an exclusive group or community, especially when the message implies a gift or a special offer from someone they know. This sense of belonging can be a strong incentive to join and participate.
5. **Reducing Perceived Risk:** For new users, trying a new service involves some level of perceived risk or uncertainty. A personalized referral reduces this perceived risk, as it comes with an implicit endorsement from someone the referee trusts.
6. **Emotional Appeal:** Personalized messages can evoke an emotional response. Knowing that a friend or acquaintance has thoughtfully extended an offer can create feelings of appreciation and reciprocity, further encouraging the referee to sign up.
To show the referrer name to the new user, you need to make sure that their user details are passed in the [referral component](/referral-component/quickstart).
## Add personalization to the Headline or other page element
Recommended
To add the referrer's name to an element on the page that the new user lands on when following an invite link, you need to follow these steps:
### Turn personalization on for your product
Go to [New User Experience setup in Cello Portal -> Personalization tab](https://portal.cello.so/setup/new-user-experience) and add personalization.
When personalization is turned on, an extra parameter will be added to the URL of your landing page, e.g. `celloN=VGFuamE`
```html
https://getmoonly.com/?productId=getmoonly.com&ucc=pNRB1aYqArN&celloN=VGFuamE
```
### Use parameter to get the name of the referrer
Value of parameter `celloN` is an base64 encoded name of the referrer. In this example, `VGFuamE` is decoded to `Tanya` . You can try it yourself [here](https://www.base64decode.org/). By accessing this parameter from the URL and decoding in, you can add it to any element on any landing pages which are relevant.
## Add personalization with the New user banner
No code
The banner with a personalized message is easily added in a few steps:
* Add [Cello attribution library](/sdk/client-side/attribution-lib) to your landing page.
* Go to [New User Experience setup in Cello Portal -> Personalization tab](https://portal.cello.so/setup/new-user-experience) and turn the banner on.
Visitors who follow the Cello invite link will have a banner displayed with a custom message containing an offer and the name of their referrer.
# Referral Notifications and Emails
Source: https://docs.cello.so/guides/user-experience/referral-notifications-and-emails
Cello provides notifications that are seamlessly integrated with your product experience to inform, activate and continuously engage users with the referral program
Cello provides notifications that are seamlessly integrated with your product experience to inform, activate and continuously engage users with the referral program. This page provides details on the notifications types and how to customize based on your needs.
## Notifications types and triggers
Notifications the we support fall into 2 categories: **in-product** announcement and alert and **external** like email. These notifications and their associated triggers are designed to work in conjunction your existing product engagement touch points in a seamless way.
### Alert and Badge
**Alert** is a notification that appears under Rewards tab. It is accompanied with a **badge**.
A **badge** is a small colored dot displayed on the launcher opening the widget (Cello button or [Custom Launcher](/referral-component/custom-launcher)) to draw attention to the activity with the referral program without being too distracting from your core product experience.
| Type | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| "New referrer activation" alert | Displayed after referrer has used the product more then 1 day after signs up to bring subtle attention to the referral program. |
| "Successful share" alert | Displayed every time referrer has a new link view. |
| "New reward" alert | Displayed every time the referrer receives a new signup or reward. |
### Announcement
Announcements are callout style message that appears anchored to the launcher, either Cello button or [Custom Launcher](/referral-component/custom-launcher). Announcements can be dismissed by clicking on them or their "X" dismiss button.
| Type | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| "New referrer activation" announcement | Sent 7 days after a ["New referrer activation" alert](#alert-and-badge) is sent and the user has not acted on it. |
| "New reward" announcement | Sent if the user has not entered their payment details after 7 days of receiving the first reward. |
### Email
Emails are a way to keep your users aware and engage with the referral program without them needing to log into the application. By default, Cello will send emails about the key events in the referral lifecycle.
Don't forget to add user email to the [boot command of the Referral component](/sdk/client-side/cello-js#3-initialize-the-library) to start sending emails to your users.
| Type | Description |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Welcome" email +10% activation | By default is sent on the 6th day after new referrer first signs up to introduce the referral program and its details. |
| "Successful share" email | Sent once when the referrer gets a first successful share, i.e. someone has viewed their link, to keep the momentum and encourage more sharing. |
| "New reward" email | Sent every time the referrer receives a new reward. When referrer gets a first monetary reward this email contains information on how to claim the rewards. |
| "Unclaimed rewards" email | Sent if the user has not entered their payment details after 7 days of receiving the first reward. |
## Default notification journey
Below is an illustration of the default new referrer's journey with key milestones and how Cello uses different types of notifications to keep them informed and engaged.
## Activation campaign
In addition to the default notification journey, you can run **an activation campaign** with Cello to activate users for your referral program with recurring announcements.
**How it works:**
1. Activation campaign starts 30 days after ["New referrer activation" announcement](#announcement) is sent and the user has not acted on it.
2. The recurring announcements will be only send if the user full-fills a certain activity pattern in the product like:
* Referrer has used the app at least once after reading the last announcement.
* Last activation announcement was read.
* Referrer didn't share in the last 30 days.
## Notification settings
You can preview and configure which notifications you want Cello to send in your [Cello Portal](https://portal.cello.so/setup/notifications).
Cello distinguishes between **Essential** and **Engagement** notifications. Essential notifications are **always on** as they are required for the program to run successfully. You can choose to turn off Engagement notifications, however, they do give a significant performance improvement.
# Setup Overview
Source: https://docs.cello.so/integration-overview
Get started with Cello in 4 easy steps
## Setup Steps
If you did not find your integration guide, complete these steps to integrate Cello, regardless of your tech stack or payment gateway.
Effort: \~3-4 hours
Add referral functionality to your web application with Cello's embeddable Referral Component.
You can also integrate the Cello Referral Component into your mobile apps. Choose the appropriate SDK for your platform:
Effort: \~1-2 hours
Set up a [Referral Landing Page](/user-experience/optimizing-landing-pages) and capture referral codes (`ucc`) when users click referral links. For Web signup flow, follow this guide:
Or choose the appropriate guide for your flow:
Effort: \~1 day
When users sign up or express interest in your product, attribute these events to their referrer for potential future rewards.
Choose your preferred method to send signup events to Cello:
Complete guide for tracking signup events
API reference for sending events
Effort: \~1 day
Complete the conversion tracking by sending purchase events to Cello when users make payments.
Choose your integration method based on your payment gateway:
}
href="/integrations/webhooks/stripe-webhook"
>
Stripe webhook integration for purchase events
}
href="/integrations/webhooks/chargebee-webhook"
>
Chargebee webhook integration for purchase events
Complete guide for tracking purchase events
API reference for sending events
## Integration Guides
Effort: \~1-2 days
Ready-to-use webhook integrations for Stripe and Chargebee provide the **fastest path** to track referral conversions automatically.
These guides are **optimized for the typical freemium scenario with Stripe or Chargebee**.
Use one of these guides if you:
* Create a Stripe or Chargebee customer on signup
* Use the Stripe or Chargebee webhook to send Cello referral conversion events
# Introduction
Source: https://docs.cello.so/integrations/introduction
Connect Cello to your payment gateway, CRM, and other systems
Cello provides flexible integration options to connect with any payment provider, CRM, or custom system. Choose the approach that best fits your architecture.
## Integration Methods
### Pre-built Webhooks
Ready-to-use webhook integrations for popular payment providers. These provide the fastest path to track referral conversions automatically.
}
href="/integrations/webhooks/stripe-webhook"
>
Automatically track Stripe payments
}
href="/integrations/webhooks/chargebee-webhook"
>
Track Chargebee subscriptions
### Cello REST API
Did not find an integration for your system? Send conversion events from any system using our REST API.
Perfect for connecting payment gateways (e.g. Paddle, Recurly, etc.), CRMs (e.g. Hubspot, Salesforce, etc.), or in-house built CRMs or billing systems.
Follow 4 easy steps to get your referral program up and running with Cello using any CRM or payment gateway
Send conversion events, validate referral codes, and manage referral links programmatically
## Next steps
Choose your integration based on your setup:
Follow one of our quickstart guides for **pre-built webhook integrations** for the fastest setup.
Use the **Cello API** to send signup events and **Stripe or Chargebee webhook** to send purchase events from your payment provider.
Send signup events
}
href="/integrations/webhooks/stripe-webhook"
>
Automatically track Stripe payments
}
href="/integrations/webhooks/chargebee-webhook"
>
Track Chargebee subscriptions
**Cello API** gives you full control over when and how to track conversions. Send events from your backend whenever a signup or purchase occurs.
Follow 4 easy steps to get your referral program up and running with Cello using any CRM or payment gateway
Send conversion events, validate referral codes, and manage referral links programmatically
All integration methods support both sandbox and production environments, allowing you to test thoroughly before going live.
# Salesforce Apex Triggers + Cello API
Source: https://docs.cello.so/integrations/salesforce-apex-triggers
This documentation guides you through the process of setting up Apex triggers in Salesforce to handle specific conditions related to Opportunities
This documentation guides you through the process of setting up Apex triggers in Salesforce to handle specific conditions related to Opportunities. The exemplary trigger will be designed to execute when an Opportunity meets two criteria:
1. The opportunity moved to the stage `Proposal/Price Quote`
2. It has a value in the custom field `cello_ucc`
Adjust according to your individual Salesforce setup and referral requirements
Customize the code as needed based on your individual Salesforce setup. Cello requires at least a "demo done" event as well as a the revenue transactions of won opportunities.
### Apex Trigger Configuration
### 1. Create an Apex Trigger
Find detailed documentation on [Apex triggers in the Salesforce docs](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_triggers.htm).
Navigate to Setup in Salesforce and follow these steps,:
* In the Quick Find box, type "Triggers" and select "Apex Triggers."
* Click "New Trigger" to create a new trigger.
```apex
trigger OpportunityTrigger on Opportunity (after update) {
OpportunityHandler.handleOpportunityUpdate(Trigger.new);
}
```
### 2. Create an Apex Class
Now, create an Apex class to handle the logic and API call. Implement the call to the [auto\$](/docs/cello-api) in the placeholder method `makeApiCall` in the below code.
This configuration ensures that the Cello API is triggered when an Opportunity meets the specified criteria. Customize the code as needed based on your individual Salesforce setup, API requirements and endpoint.
```apex
public class OpportunityHandler {
public static void handleOpportunityUpdate(List updatedOpportunities) {
for (Opportunity opp : updatedOpportunities) {
// Check criteria: Opportunity in Proposal/Price Quote stage and cello_ucc value
if (opp.StageName == 'Proposal/Price Quote' && opp.Cello_UCC__c != null) {
// Make the API call
makeApiCall(opp.Id, opp.Cello_UCC__c);
}
}
}
private static void makeApiCall(Id opportunityId, String celloUccValue) {
// Your code to make the API call using HTTP methods, e.g., HttpRequest and HttpResponse
// Example:
// HttpRequest req = new HttpRequest();
// req.setEndpoint('your API endpoint');
// req.setMethod('POST');
// req.setHeader('Content-Type', 'application/json');
// req.setBody('{"opportunityId": "' + opportunityId + '", "celloUccValue": "' + celloUccValue + '"}');
// HttpResponse res = new Http().send(req);
}
}
```
### 3. Test and Deploy
* Test your trigger and class in the sandbox environment to ensure proper functionality.
* Reach out to the Cello team to confirm that provided event data is correct.
* Deploy the trigger and class to your production environment once testing is successful.
Important Notes
* **Bulk Processing**: Ensure that your Apex trigger can handle bulk updates, as Salesforce triggers operate in bulk.
* **Error Handling**: Implement appropriate error handling in your Apex class to manage API call failures.
# Chargebee Webhook
Source: https://docs.cello.so/integrations/webhooks/chargebee-webhook
Send signup and purchase events to Cello using Chargebee Webhook
Cello makes it easy to **connect securely to your Chargebee payment provider** to automate transaction events, attribution, and payouts. Transactions are monitored and used to pay out referrers based on your campaign reward rules.
# Overview
A notification event is securely sent to Cello through the webhook endpoint every time a customer makes a purchase or a customer record is created or updated. Cello checks these events to perform the following actions:
* Determine if a reward for the referrer needs to be created and paid out
* Inform the referrer about new signups and rewards
* Cancel recurring rewards if a subscription is cancelled
If the automation of Cello detects unclear cases the automation will be paused and Cello will reach out to you to clarify the case.
# Endpoint URLs
You will find the webhook endpoint URL for both **Sandbox** and **Production** environments in the [Cello Portal Webhooks page](https://portal.cello.so/integrations/webhooks).
# Securing the webhook
To secure the webhook in Step 5, you will find credentials for both **Sandbox** and **Production** environments in [Cello Portal Webhooks page](https://portal.cello.so/integrations/webhooks).
# Connecting Chargebee
## Prerequisites
Before configuring webhooks, ensure your Chargebee customers include the required Cello attribution fields. These information enables proper attribution and reward tracking.
**When to add additional fields:**
* If you create Chargebee customers at signup → You would have already added metadata or custom fields to the customer during the [Setup Step "Track Signups"](/attribution/tracking-signups)
* If you create Chargebee customers at purchase → Make sure to add metadata or custom fields when creating the customer
### Required Chargebee Customer attribution fields
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**](https://www.chargebee.com/docs/billing/2.0/site-configuration/custom_fields)
Pass the following fields during checkout in the [Customer Object](https://apidocs.chargebee.com/docs/api/customers) to `metadata` attribute or as a `CF_` custom field.
| Field | Description | Chargebee Object |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `cello_ucc` | Referral code identifying the referrer | [Customer Object](https://apidocs.chargebee.com/docs/api/customers) to `metadata` attribute or as a `CF_` custom field |
| `new_user_id` | Your system's unique user ID. Same as `productUserId` used in [Referral Component](/referral-component/introduction) when booting the SDK | [Customer Object](https://apidocs.chargebee.com/docs/api/customers) to `metadata` attribute or as a `CF_` custom field |
| `new_user_organization_id` | Organization ID (optional). Required only for organization-level referrals and rewards | [Customer Object](https://apidocs.chargebee.com/docs/api/customers) to `metadata` attribute or as a `CF_` custom field |
| `coupon` | New user discount code | [Customer Object](https://apidocs.chargebee.com/docs/api/customers) to `metadata` attribute or as a `CF_` custom field |
## Steps
You will add a webhook to your Chargebee configuration to connect Chargebee and Cello. This can be done in both test and production environments separately.
From the sidebar, select Settings > Configure Chargebee and click on "Webhooks". Next Click on "+ Add Webhook".
Choose the Endpoint URL corresponding to the environment you are setting up: **Sandbox** or **Production**.
Select the events you want to send under "Events to Send":
1. `Customer Created`, `Customer Changed`, `Customer Deleted`
2. `Payment Succeeded`, `Payment Refunded`, `Payment Failed`
Select "Protect webhook URL with basic authentication" and add the `product_id` and `secret` provided in the Cello Portal.
Be sure to select **Exclude card Information from webhook call**
Webhook created!
# Stripe Webhook
Source: https://docs.cello.so/integrations/webhooks/stripe-webhook
Send signup and purchase events to Cello using Stripe Webhook
Cello makes it easy to **connect securely to your Stripe payment provider** to automate transaction events, attribution, and payouts. Transactions are monitored and used to pay out referrers based on your campaign reward rules.
# Overview
A notification event is securely sent to Cello through the webhook endpoint every time a customer makes a purchase or a customer record is created or updated. Cello checks these events to perform the following actions:
* Determine if a reward for the referrer needs to be created and paid out
* Inform the referrer about new signups and rewards
* Cancel recurring rewards if a subscription is cancelled
If the automation of Cello detects unclear cases the automation will be paused and Cello will reach out to you to clarify the case.
# Endpoint URLs
You will find the webhook endpoint URL in the [Cello Portal Webhooks page](https://portal.cello.so/integrations/webhooks).
# Connecting Stripe
## Prerequisites
Before configuring webhooks, ensure your Stripe customers include the required Cello metadata. This metadata enables proper attribution and reward tracking.
**When to add metadata:**
* If you create Stripe customers at signup → You would have already added metadata to the customer during the [Setup Step "Track Signups"](/attribution/tracking-signups)
* If you create Stripe customers at purchase → Make sure to add metadata when creating the customer
### Required Stripe Customer Metadata
Pass the following fields during Stripe Checkout in the [Customer Object](https://docs.stripe.com/api/customers/object?api-version=2024-09-30.acacia#customer_object-metadata) and [Checkout Session object](https://docs.stripe.com/api/checkout/sessions/object?api-version=2025-07-30.basil)
| Field | Description | Stripe Object |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cello_ucc` | Referral code identifying the referrer | Stripe [Customer Object](https://docs.stripe.com/api/customers/object?api-version=2024-09-30.acacia#customer_object-metadata), attribute:`metadata` |
| `new_user_id` | Your system's unique user ID. Same as `productUserId` used in [Referral Component](/referral-component/introduction) when booting the SDK | Stripe [Customer Object](https://docs.stripe.com/api/customers/object?api-version=2024-09-30.acacia#customer_object-metadata), attribute:`metadata` |
| `new_user_organization_id` | Organization ID (optional). Required only for organization-level referrals and rewards | Stripe [Customer Object](https://docs.stripe.com/api/customers/object?api-version=2024-09-30.acacia#customer_object-metadata), attribute:`metadata` |
| `coupon` | New user discount code | Stripe [Checkout Session object](https://docs.stripe.com/api/checkout/sessions/object?api-version=2025-07-30.basil), attribute: `discount` |
## Steps
You will add a webhook to your Stripe configuration to connect Stripe and Cello. This can be done in both test and production environments separately.
Select Developers from the upper right menu.
You can find Webhooks at the left menu. Next click Add an endpoint.
Choose the Endpoint URL corresponding to the environment you are setting up: **Sandbox** or **Production**.
To select events, do the following steps:
1. Select "Events on your account"
2. Select your latest API version
3. Choose events to send:
1. `charge.refunded`, `charge.succeeded`, `charge.updated`
2. `customer.created`, `customer.deleted`, `customer.updated`
3. `customer.subscription.created`, `customer.subscription.deleted`, `customer.subscription.updated`
4. `invoice.paid`
Webhook created!
To secure the connection, you need to add the “Signing secret” to [Stripe Webhook Configuration in Cello Portal](https://portal.cello.so/integrations/webhooks).
Stripe Webhook Signing secret starts with `whsec_`
1. Click “Reveal” and copy the Signing secret
2. Add the Signing secret to Stripe webhook settings in the [Cello portal](https://portal.cello.so/integrations/webhooks).
# Introduction
Source: https://docs.cello.so/introduction
Learn how to turn your users into your most valuable growth channel
[Cello](https://cello.so/) is a referral platform for building user and partner referral programs.
Cello enables you to:
* Embed referral components directly in your application
* Track and attribute user signups and purchases
* Process payouts in 10+ countries and currencies
# Key Features
Cello provides the following capabilities:
* [Integrated Referral Component for Web and Mobile apps](/referral-component/quickstart)
* [In-product and Email notifications](/guides/user-experience/referral-notifications-and-emails)
* [Analytics Dashboard](https://portal.cello.so/dashboard/referrer)
* [Partner Program](/guides/partners/partner-overview)
* [Integrations and Webhooks](/integrations/introduction)
* [Cello API](/api-reference/introduction)
# Getting Started
Add the Cello Referral Component to your web app in just 15 minutes with our Quickstart:
Follow 4 easy steps to get your referral program up and running with Cello
Referral component for your web and mobile applications
Track signups and purchases back to the right referrer
Webhooks for payment gateways to send conversion events to Cello
# Key Concepts
Source: https://docs.cello.so/key-concepts
Essential terms and concepts for understanding Cello's referral platform and attribution system
## Quick Reference
| Term | Description |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| [**Referrer**](#referrer) | Existing user who shares their unique referral link |
| [**New User**](#new-user-referred-user-referee) | Person who receives and uses a referral link |
| [**Referral Code (UCC)**](#referral-code-or-ucc-unique-campaign-code) | Unique 11-character identifier for tracking referrals |
| [**Partner**](#partner) | Professional referrer with exclusive rewards and dedicated portal |
| [**Landing Page Attribution**](#landing-page-attribution-referral-attribution) | Process of capturing and storing referral codes |
| [**Referral Conversion Tracking**](#referral-conversion-tracking) | Tracking when referred users complete target actions |
| [**Attribution Script**](#attribution-script-attribution-js) | JavaScript library for detecting referral parameters |
| [**Referral Component**](#referral-component-cello-js) | Embeddable UI component for referrers |
| [**Payment Gateway**](#payment-gateway-or-payment-provider) | Third-party payment processors integrated with Cello |
***
## Referrer
The existing user (or customer) who initiates the referral by sharing their unique referral link. The referrer is the source of the referral traffic and is typically eligible to receive rewards when the referred user (new user) completes the desired action (e.g., signup, purchase).
***
## New User (Referred User / Referee)
The person who receives the referral invitation or link from the referrer and engages with it. They are considered a "new user" if they have not previously registered or purchased. Often called the **referee** in referral programs.
***
## Partner
A professional referrer who promotes your product as part of a formal partnership. Unlike regular user referrers, partners typically receive:
* **Special reward structures** - Different campaigns from user referrals; can include higher rates, reward caps, or even lifetime rewards
* **Dedicated Partner Portal** - Professional dashboard for tracking referrals, conversions, and earnings
* **Marketing resources** - Media kits, branded assets, and pre-written promotional content
Partners can include affiliates, influencers, agencies, consultants, or other businesses that systematically refer customers. Cello unifies both user referrals and partner programs in a single platform, requiring no additional technical integration beyond the standard referral setup. Learn more about [managing partners](/guides/partners/partner-overview).
***
## Referral Code or UCC (Unique Campaign Code)
A unique identifier tied to the referrer. It is a unique set of 11 alphanumeric characters, composed of numbers, uppercase and lowercase letters. It always appears at the end of the referral link. When a new user uses the referral link with a referral code, it allows the system to attribute their actions back to the referrer. **Referral Code** is a more general term for the code shared by the referrer. **UCC (Unique Campaign Code)** refers to the same code but is a specific Cello term which will be used throughout this documentation and in API references.
* ucc: `pNRB1aYqArN`
* referral link: `moonly.cello.so/pNRB1aYqArN`
***
## Landing Page Attribution / Referral Attribution
The process of **capturing and storing the referral code** (`ucc`) when a referred user lands on a [website](/attribution/for-web) or [mobile app](/attribution/for-mobile) via the referral link. This step ensures the system knows **which referrer** brought the user, so later actions (signups, purchases) can be attributed correctly. This step also involves storing the code in a cookie or user record until the user completes a tracked action.
***
## Referral Conversion Tracking
The stage where a new user completes the targeted action defined by the referral program. This can include:
* [Signups / Tracking Signups](/attribution/tracking-signups): When a new user successfully creates an account. The system links this signup to the referrer.
* [Purchases / Tracking Purchases](/attribution/tracking-purchase): When a new user makes a purchase, often the ultimate revenue-driving conversion.
***
## Attribution Script / Attribution JS
[Attribution JS is a JavaScript library](/sdk/client-side/attribution-lib) embedded on landing pages that automatically detects referral parameters (`ucc`, `productId`, `referrerName`), stores them in cookies for indirect signups, and provides JS methods to easily retrieve these parameters for further conversion events.
***
## Referral Component / Cello JS
The embeddable component provided by the Cello referral platform to handle referral-related functionality for the referrer in your [web or mobile application](/referral-component/introduction).
***
## Payment gateway or payment provider
Third-party services that handle payment processing and billing for your application. These platforms (such as Stripe, Chargebee, Paddle, Recurly, etc.) integrate with Cello to enable automatic tracking of referral-driven purchases and revenue attribution. When a referred user makes a purchase through your payment provider, Cello can automatically detect and attribute that conversion back to the original referrer, enabling seamless reward distribution and revenue tracking.
# Manage cookie consent
Source: https://docs.cello.so/landing-pages/manage-cookies
To ensure compliance with privacy regulations, customers handle cookies and respond to user consent preferences with care and transparency. It is your responsibility to prompt website visitors to specify their preferred tracking level.
Cookie consent is a complex legal subject, varying across different jurisdictions. While the Attribution Library offers tools for managing cookie consent, it is the responsibility of your organization to consult with legal experts to ensure compliance with specific regional laws and regulatory requirements.
# Understanding referral cookies
The [Attribution JS](/sdk/client-side/attribution-js-introduction) employs a specific first-party cookie to enable returning user to claim their referral discount. This cookie functions as a strictly necessary or essential cookie by default, but **should be configured based on your privacy guidelines**.
It's important to note that these cookies **do not directly monitor the identity of returning users.** Instead, it records the referral code, also known as the \[Unique campaign code (`ucc`), originating from the invitation link provided by a referrer and additional parameters to support returning users.
Cookies are not required to directly attribute referrals in Cello. They are used to assist in attributing a referral when a new user leaves and returns to the signup.
## List of first-party referral cookies that are set
| Cookie | Purpose | Persistent or Session | Lifespan | Default type |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------- | ----------------------------------------------------------------- |
| cello-referral | Cello uses `cello-referral` cookie to identify the referrer and campaign. These let us link the referrer and new users who sign up, and help us apply rewards and discounts based on the campaign terms. | Persistent | 3 months | Strictly necessary or essential cookies |
| cello-productId | Cello uses `cello-productId` cookie to identify the product (account) using Cello on this page. | Persistent | 3 months | Strictly necessary or essential cookies |
| cello-cookie-consent | Cello uses `cello-cookie-consent` cookie to store consent to managing cookies | Persistent | 3 months | Strictly necessary or essential cookie for custom cookie handling |
# Methods for Handling Consent
The [Attribution JS](/sdk/client-side/attribution-js-introduction) provides several methods for handling user consent efficiently:
## 1. Custom Method
Custom method only works if your account has been configured to use custom cookie handling. Contact Cello Support to enable it.
Utilize the [Attribution JS](/sdk/client-side/attribution-js-introduction) JavaScript API to dynamically inform it when a visitor has consented to cookie storage. This method offers full control over the timing of cookie storage, allowing you to align it with your user consent process.
### allowCookies
To allow the storage of the referral code cookie:
```javascript
window.CelloAttribution('allowCookies');
```
### deleteCookies
To halt the storage of the referral code cookie and clear it:
```javascript
window.CelloAttribution('deleteCookies');
```
## 2. Consent System Method
For users of popular cookie management and consent platforms such as OneTrust, CookieBot, and Civic Cookie Control, the [Attribution Library](/cello/v2.0/docs/connect-attribution) offers built-in support for seamless integration. Our Cello support team can assist you in configuring the right tool for your specific needs, eliminating the need for coding.
### Supported Tools
* OneTrust New
* CookieFirst Coming Soon
* CookieBot Coming Soon
* Civic Cookie Control Coming Soon
These methods allow you to handle cookie consent effectively when utilizing the [Attribution JS](/sdk/client-side/attribution-js-introduction) to track returning referees seamlessly.
# Using Cello Docs with AI
Source: https://docs.cello.so/llm-quickstart
Integrate Cello documentation into your AI tools for faster, smarter development
Build with Cello faster using AI assistants that understand our entire documentation. This guide shows you how to give AI tools complete context about Cello's APIs, SDKs, and integration patterns.
## Quick Start: URL Context
The fastest way to get started is to provide this URL directly to your AI tool:
```
https://docs.cello.so/llms-full.txt
```
This file contains \~73,000 tokens of comprehensive Cello documentation optimized for LLM consumption.
Start your chat with:
```
Retrieved and processed the Cello documentation
from this provided URL: https://docs.cello.so/llms-full.txt.
Use it as context in this chat to answer my questions.
```
## Method 2: Direct Content Injection
For AI tools that don't support URL fetching, you can copy the entire documentation:
1. **Download the documentation**: Open [llms-full.txt](https://docs.cello.so/llms-full.txt)
2. **Copy all content**: Select all (Ctrl/Cmd + A) and copy
3. **Paste into your AI tool**: Add as context before your questions
Some AI tools have token limits. The full documentation is \~73,000 tokens, so you may need to use tools like Claude (200k context) or GPT-4 Turbo (128k context).
## Method 3: MCP Server Integration
For advanced integrations, connect directly to our Model Context Protocol (MCP) server:
```
https://docs.cello.so/mcp
```
This provides structured access to Cello documentation for MCP-compatible AI applications.
## Example Prompts
Here are some powerful prompts to get you started:
### Basic Integration
```
Using the Cello docs, show me how to implement the referral component
with user authentication in a React app
```
### Advanced Attribution
```
Create a complete attribution tracking system that captures referral codes
from URLs, stores them in cookies, and sends conversion events to Cello using Cello API
```
### Custom Integration
```
How do I integrate our payment provider Paddle with Cello to send purchase events?
```
## Best Practices
Always mention what you're building (web app, mobile app, backend service) for more targeted assistance.
Ask for full, runnable code examples including error handling and edge cases.
Always confirm the latest API endpoints and authentication methods from the documentation.
Build and test features step-by-step rather than implementing everything at once.
## Troubleshooting
| Issue | Solution |
| -------------------- | ------------------------------------------------------------------------ |
| AI doesn't fetch URL | Use Method 2 (copy-paste) instead |
| Token limit exceeded | Focus on specific sections or use an AI with larger context window |
| Outdated information | Always verify critical details at [docs.cello.so](https://docs.cello.so) |
## Need Help?
AI sometimes makes mistakes. If you get stuck, reach out to your Customer Success Manager or our support team at [support@cello.so](mailto:support@cello.so).
# Custom Launcher
Source: https://docs.cello.so/referral-component/custom-launcher
Learn how to implement your own button to open Referral Component and display notifications.
The Cello custom launcher allows you to open the Referral Component from any element that you want to use. **It can be a button, a menu item, a link and you can use multiple places that open Cello Referral Component**. Additionally, you can choose to open it either in a popup or modal view.
## Add a custom launcher
1. **Choose an element** in your app to launch Referral Component. It can be a button, a menu item, a link. Make sure your element has a unique identifier in your application DOM. It can be a **class ID**, **an attribute selector**, **an element ID**.
2. **Add the ID or class to the HTML element** where you want the Referral Component to open when clicked.
Our function needs a relative parent. So, if you attach it to a button inside the div, the div needs a `position: relative` .
```html
Invite
Invite
Invite
```
3. Add this identifier as Custom Launcher Selector under [Referrer Experience in Cello Portal](https://portal.cello.so/setup/referrer-experience) .
## Add reward in launcher
1.5x activation rate3.5x sharing rate
Increase the sharing activity of your users by highlighting the reward directly in the referral launcher inside your menu item.
You can get the text for the menu launcher from [cello.js](/sdk/client-side/cello-js). Text will be localized to the [referrer's language](/guides/user-experience/overview#texts-and-language) and the reward amount is based on the [referrer's campaign](/guides/campaigns/setting-up-campaigns).
```javascript
const labels = await window.Cello("getLabels")
const myCustomLauncherLabel = labels.customLauncher
```
## Disable Cello button
**Cello button** is a floating action button or bookmark style button provided as a default Referral Component launcher. When integrating a Customer Launcher, you may choose to disable the Cello button or keep it as an additional launcher.
You can choose to disable the default launcher, the Cello button. Go to [Referrer experience](https://portal.cello.so/setup/referrer-experience) settings in Cello Portal and **uncheck** "Show Cello Button".
## Configure notification badge
You can control the behaviour of the [notification badge](/guides/user-experience/referral-notifications-and-emails#alert-and-badge), which is attached to your Custom Launcher Selector by default:
This is the default behaviour of the Custom Launcher.
```html
"Invite"
```
Does not open the Referral Component. Use this option if you want to place notification badge to a different element then the one that opens the Referral Component, e.g. you want to show the badge notification on the menu item that is one level above from the actual Custom Launcher of Referral Components to increase visibility.
```html
"Invite"
```
Use this option if you do not want the Custom Launcher to show a notification badge, i.e. you have an additional CTA button that launches Referral Component.
```html
"Invite"
```
**Testing notification badge position**\
To trigger a notification badge to be shown on your Custom Launcher simply visit the referral link, of the same user you are testing with, e.g. `moonly.cello.so/pNRB1aYqArN` . A link visit will trigger a [view notification](/guides/user-experience/referral-notifications-and-emails#alert-and-badge) and a badge will be displayed.
## Add announcement selector
Announcement are callout style notifications used to [communicate important information](/guides/user-experience/referral-notifications-and-emails#announcement) to the user if we need to grab their attention and direct them to the Referral Component.
If the Cello button is disabled, the announcement needs to be anchored to one of your Custom Launchers.
Depending on the implementation, the Announcement Selector can be the same as for Custom Launcher, i.e. you can use exactly the same class ID, attribute selector or element ID.
Add this identifier as Announcement Selector under [Referrer Experience in Cello Portal](https://portal.cello.so/setup/referrer-experience).
Here you can also configure where you want announcement to be shown relative to the Announcement Selector by specifying **Announcement position** and **Announcement position offset.**
**Testing Announcement position**\
While choosing Announcement Selector and choosing its position, you will want to see how it looks and make necessary adjustments. You can trigger an [announcement](/guides/user-experience/referral-notifications-and-emails#announcement) using [Cello JS](/sdk/client-side/cello-js-usage#showannouncement-announcement) `showAnnouncement(announcement)` method.
Example below will trigger the default welcome announcement:
```javascript
window.Cello("showAnnouncement", { "type": "welcome-announcement-1" } )
```
# Introduction
Source: https://docs.cello.so/referral-component/introduction
Add a referral program to your application with Cello's embeddable referral component
The Cello Referral Component is an all-in-one referral experience that integrates directly into your web and mobile applications with just a few lines of code, enabling users to share referral links, track progress, and receive rewards.
## What is the Referral Component?
The Referral Component provides a complete referral experience within your product through:
* **First-time onboarding** that explains how your referral program works
* **Multiple sharing options** including link copy, social media, email, and QR codes
* **Progress tracking** showing clicks, signups, and earned rewards in real-time
* **Automated reward payouts** via PayPal, Venmo, and other payment methods
* **In-app and Email notifications** to keep users engaged with referral activity
Learn more about the [complete user experience](/guides/user-experience/overview).
## Key Features
* **Easy Integration** - Add as a floating button to launch the Referral Component or integrate into your existing menu with [custom launcher](/referral-component/custom-launcher)
* **Customizable Offer** - [Configure reward amounts, text, and program details](/guides/campaigns/setting-up-campaigns)
* **In-app Notifications** - [Alerts and announcements](/guides/user-experience/referral-notifications-and-emails) to keep users engaged with updates, promotions, and milestones
* **Email Notifications** - [Automated emails for signups, rewards, and milestones](/guides/user-experience/referral-notifications-and-emails)
* **Multi-language Support** - Available in 10+ languages with automatic detection
* **Cross-platform** - Native SDKs [for Web](/sdk/client-side/cello-js), [iOS, Android, and React Native](/sdk/mobile/introduction)
## Installation Options
JavaScript library for React, Vue, Angular, and vanilla JS applications
Native Swift/Objective-C SDK with CocoaPods and SPM support
Native Kotlin/Java SDK with Gradle integration
Cross-platform mobile SDK for React Native apps
## How to Use
### Basic Implementation
1. **Load the SDK** - Add Cello script or SDK to your application
2. **Generate JWT Token** - Create server-side authentication token
3. **Initialize Component** - Boot with your product ID and user details
### Quick Example (Web)
```javascript
// Load and initialize Cello
window.cello.cmd.push(async function (cello) {
await cello.boot({
productId: "YOUR_PRODUCT_ID",
token: "JWT_TOKEN",
productUserDetails: {
email: "user@example.com",
firstName: "John"
}
});
});
```
## Next Steps
Get started with the [Quickstart guide](/referral-component/quickstart) to integrate the Referral Component in under 15 minutes.
# Quickstart
Source: https://docs.cello.so/referral-component/quickstart
Learn how to install Cello Referral Component into your web application
This guide follows basic steps to **integrate Referral Component into your web application** using [Cello JS SDK](/sdk/client-side/cello-js-introduction).
[Cello JS SDK](/sdk/client-side/cello-js-introduction) is a browser-based JavaScript library compatible with all web frameworks that output HTML/JavaScript, including React, Next.js, Vue, and Angular.
For server-side rendering frameworks like Next.js, Cello interactions must occur client-side, not server-side.
## Prerequisites
First, you'll need your `productId` and `PRODUCT_SECRET` from your Cello dashboard's [Access Keys page](https://portal.cello.so/integrations/accesskeys) for the right environment (Sandbox or Production)
## Installation Steps
Follow these steps to integrate the Referral Component:
1. Load the Cello script from our CDN
2. Generate a JWT token server-side for user authentication
3. Initialize the component with the token to connect your user session
## Step 1: Load the script
Add the Cello script to your HTML. The script loads asynchronously to avoid blocking page rendering and can be included anywhere on your website. This approach is recommended for optimal SEO performance.
**Avoiding CORS Issues**: When loading third-party scripts like Cello at runtime, ensure your Content Security Policy (CSP) allows loading from `*.cello.so` domains. If your application has strict CSP headers, add `script-src 'unsafe-inline' https://assets.cello.so https://assets.sandbox.cello.so` to your CSP configuration to prevent CORS-related loading issues.
Add this script to the `head` tag of your HTML:
```javascript
```
```javascript
```
Once loaded, the script:
1. Registers `window.Cello` for communication between your page and Cello
2. Processes any queued commands from `window.cello.cmd` and maintains the command interface
## Step 2: Generate a JWT token
Create a JWT token to securely connect your user's session to Cello. The token authenticates your application and provides user identity for generating unique referral links.
Generate JWT tokens server-side only. Never create tokens in the browser.
See [User Authentication](/sdk/client-side/user-authentication) for complete JWT token generation instructions.
## Step 3: Initialize the library
Initialize Cello with a single function call that includes your **product ID**, **JWT token**, and configuration options.
User details (email, first name) are required for fraud detection and features like email notifications and personalized messaging.
```javascript
window.cello = window.cello || { cmd: [] };
window.cello.cmd.push(async function (cello) {
try {
await cello.boot({
productId: "CELLO_PRODUCT_ID",
token: "REPLACE_ME",
language: "en",
productUserDetails: {
firstName: "Bob",
lastName: "Bobsky",
fullName: "Bob B Bobsky",
email: "bob@gmail.com",
},
});
} catch (error) {
console.error("Failed to boot cello:", error);
// Handle the error appropriately
}
});
```
This implementation works with asynchronous script loading. For complete configuration options, see [SDK Reference](/sdk/client-side/cello-js#cello-boot-options).
After initialization, the library:
1. Adds a Cello button to your page or [connects to your custom element](https://docs.cello.so/referral-component/custom-launcher)
2. Creates a session to handle configured callbacks
**Congratulations!** You have successfully integrated Cello Referral Component!
Next, you can integrate Referral Component into your mobile applications:
***
## Controlling access to Referral component
If you want to enable the Cello referral component only to selected users or control its visibility dynamically, we provide the following options:
During the new referral program rollout with Cello, you may want to pilot with a small cohort of selected users. This can be achieved using our Named user whitelist.
All you need to do is to provide a list of selected users UIDs (productUserIds) to Cello. After they are added to the whitelist, only these users will have access to the Referral component until you are ready to rollout to your entire user base.
To control dynamically when and who sees the Referral component, you can use `show()` and `hide()` methods.
For example, you may decide to only show the Referral component after the user has completed onboarding. In that case, when a user first logs in, boot the component with `hideDefaultLauncher = true` configuration option. Then, when the onboarding is complete, use `cello.show()` to show the Cello button.
## Opening the Referral Component with a Link
You can automatically open the Referral Component with a link to your product by adding a `cello-open=true` param to your URL.
For example, add a link to the referral component to your email communication to help your users access the sharing options directly from the email.
If a user is redirected between URLs on login, make sure to re-attach this param to the final URL the user lands on in order to automatically open the Cello Referral Component.
You may also pass one of `invite`, `rewards` and `edit-payments` values to the param for the Referral Component to open a specific tab automatically e.g.:
```html
https://your-product.com?cello-open=edit-payments
```
## Troubleshooting
### `Error 1200: Invalid Tenant`
The main cause for this error is that the used URL for the referral component, the product ID, and the Product Secret do not fit together. Make sure that you are using all three components of the same environment.
### `Error 1100: Invalid JWT token`
This means that the token is not valid and the main cause is that some of the attributes for constructing the token are not correct. You can decode your token using [https://jwt.io/](https://jwt.io/). After decoding, please check all the attributes against the requirements in User Authentication, specifically make sure that productUserId is a string, iat is valid, algorithm is H512 and the secret is the correct one for the environment you are using (Sandbox or Production)
### `Failed to load resource: the server responded with a status of 401 () [Cello]: "User is not authorized to load the widget"`
Most likely, the created JWT token is not valid. Common causes for this error are:
* The use of an incorrect `PRODUCT_SECRET`.
* The `productUserId` is not passed as a `string` in the payload for the JWT token creation.
* The use of an incorrect `productId`.
* `issuedAt` (`iat`) date cannot be older than 24h or set in the future.
### `Error: User is not authorized to load the widget`
Most likely you are not passing the `productUserId` as a `string` into the payload for the JWT token creation.
### `[Cello]: Cannot read properties of null (reading ‘__H')`
Most likely, you are using `http` in your script’s source: `src="http://assets.cello.so/app/latest/cello.js"` . Please use `https`.
## Frequently asked questions
### How much effort on tech side is the integration of Cello?
The complexity of integrating Cello can vary greatly, depending on your individual setup. Integration generally consists of frontend integration and user authentication. For our typical customer, setting up these components on a development environment requires hours, not days. The integration of attribution and reward automation is also relatively straightforward, though it depends on your existing setup.
### The Cello Floating Action Button is overlaying or covering another component within my product. What can I do?
Sometimes, the Cello Floating Action Button or the Referral Component might overlay another component in your product. Here's what you can do:
* **Adjust the z-index**: Cello can modify the z-index of the Floating Action Button or the Referral Component. This ensures that your other components can cover the Cello elements.
* **Hide the element**: Using the `cello.hide()` function, you can hide the Floating Action Button or the Referral Component when other components are open. Implement this function in your frontend.
You can also use the `cello.hide()` function to hide the Cello Floating Action Button on specific pages.
### Is it possible to hide the Cello Floating Action Button on certain pages?
You can hide the Cello Floating Action Button using the [cello.hide()](/sdk/client-side/cello-js-usage#hide) function when other components open. The implementation has to be done in your frontend.
### What exactly is the `productUserId` that is required in the user authentication?
The `productUserId` is the internal user id that you are using inside your product to uniquely identify users.
### Do you support server-side rendering?
Yes, for server-side rendering frameworks like Next.js, Cello interactions must occur client-side, not server-side.
### Do you support Angular?
As mentioned before, the Cello Referral Component is being loaded independently from your angular app and appends itself to `` tag. That being said, you need to just make sure that the injected HTML code is not being overridden by your angular app. This can be achieved in various ways. The safest choice would be not to use `` as your AppRoot element as it would create a race condition.
```typescript
@Component({
selector: 'app-root',
...
})
```
```html
```
The other option that we have seen customers implement is to load the cello javascript dynamically from your angular app, making sure that it is being loaded after angular is finished rendering its own components.
Here is an example that has been provided by one of our customers:
```typescript
export interface CelloReferralPayload {
productId: string;
token: string;
showOnBoot: boolean;
productUserId: string;
language: string;
iat: string;
}
@Injectable({ providedIn: 'root' })
export class CelloReferralAdapter {
constructor(@Inject(DOCUMENT) private document: Document, @Inject(WINDOW) private window: Window) {}
async init(payload: CelloReferralPayload, isProd: boolean){
await this.loadScript(isProd
? 'https://assets.cello.so/app/latest/cello.js'
: 'https://assets.sandbox.cello.so/app/latest/cello.js');
await this.wait(1000);
(this.window as Window & {Cello: any}).Cello('boot', payload);
}
async wait(timeout: number) {
// due to a race condition a timeout is needed after initializing the script.
return new Promise(resolve => setTimeout(() => resolve(), timeout));
}
async loadScript(src: string): Promise {
return new Promise(resolve => {
const script = this.document.createElement('script');
script.onload = () => resolve();
script.type = 'module';
script.src = src;
this.document.head.appendChild(script);
});
}
}
```
***
### What about other frameworks?
Since Cello is a Javascript library running on browser, then it works naturally with all frameworks that end up resulting in a standard HTML/Javascript application. That includes React, Angular, Vue and all similar JS/TS libraries.
# Introduction
Source: https://docs.cello.so/sdk/client-side/attribution-js-introduction
JavaScript library for capturing and tracking referral codes throughout the conversion funnel
## What is Attribution JS?
Attribution JS is a lightweight JavaScript library that captures referral codes (`ucc`) from landing pages and maintains attribution throughout the user journey. When users click referral links and land on your website, this library ensures their referral source is properly tracked through signup and purchase events.
The library automatically:
* Detects referral code (`ucc`) query parameters from referral links
* Stores referral code (`ucc`) as first-party cookies for persistent tracking
* Attaches referral code (`ucc`) to signup forms
* Provides APIs to retrieve referrer information for personalization
## Installation Options
Choose your preferred installation method:
Add directly to your HTML pages with a script tag
Deploy through GTM without code changes
## Key Capabilities
Attribution JS enables you to:
### Referral Tracking
* **Capture referral codes** - Automatically detect and store `ucc` parameters
* **Retrieve referral data** - Access referral codes programmatically with `getUcc()` from URL or cookie.
* **Form integration** - Auto-inject hidden referral fields into signup forms
### Personalization & Campaigns
* **Get referrer names** - Display personalized messages with referrer information
* **Access campaign config** - Retrieve discount percentages and duration for referred users
* **Dynamic discount display** - Show referral incentives based on campaign parameters
### Cookie Management
* **Privacy compliance** - [Manage cookie consent](/landing-pages/manage-cookies) with built-in methods
* **Allow cookies** - Enable cookie storage after user consent
* **Delete cookies** - Remove stored data when consent is withdrawn
* **Custom handling** - Implement your own consent flow with full API control
## How It Works
1. **User clicks referral link** - Link contains referral code (`ucc`) parameter (e.g., `yoursite.com?ucc=ABC123`)
2. **Script captures code** - Attribution JS detects referral code (`ucc`) and makes it accessible via JS method
3. **Code persists** - Stored as cookie for 3 months to handle return visits
4. **Signup attribution** - Referral code (`ucc`) is attributed to new user on signup
5. **Referral conversion tracking** - Pass the referral code (`ucc`) to Cello when tracking signups and purchases
## Next Steps
Choose between [embedded script](/sdk/client-side/embedded-script-tag) or [GTM installation](/sdk/client-side/google-tag-manager)
Test that referral codes are being captured correctly
Review all [available methods](/sdk/client-side/attribution-js-usage) for advanced functionality
Attribution JS works alongside [Cello JS](/sdk/client-side/cello-js-introduction) for complete referral program functionality. While Attribution JS handles tracking, Cello JS provides the referral component interface.
# Usage
Source: https://docs.cello.so/sdk/client-side/attribution-js-usage
Below is the full list of commands to call the Cello Attribution JS SDK with.
To avoid race condition of our script loading and your application trying to communicate to it, you should add the following javascript code before any of the calls to the library.
```javascript expandable
window.CelloAttribution=window.CelloAttribution||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||[],window.CelloAttributionCmd.push({command:t,args:o,resolve:e,reject:n}),i}
```
## `attachTo(formElement)`
Attaches hidden input to the passed `HTMLFormElement` node, or array of nodes.
```javascript
window.CelloAttribution("attachTo", formElement);
```
### Accepts
Form(s) to attach the hidden input to
### Example
```javascript
window.CelloAttribution("attachTo", document.querySelector("form"));
```
***
## `getCampaignConfig()`
Returns campaign config pertaining to a new user.
```javascript
const campaignConfig = await window.CelloAttribution("getCampaignConfig");
```
### Returns
The campaign config object:
How long new users get a discount
The discount new users get
## `getReferrerName()`
Returns the referrer's name, if provided in the referral link.
```javascript
const name = await window.CelloAttribution("getReferrerName");
```
### Returns
Referrer's name or `undefined`
## `getUcc()`
Retrieves the referral code `ucc` from the URL or the cookie (if cookies are enabled).
```javascript
const ucc = await window.CelloAttribution("getUcc");
```
### Returns
Unique campaign code/referral code
## ~~`attachAll()`~~
> ⚠️ **Deprecated**: forms are now auto-detected and the hidden `ucc` input is injected automatically.
> Use [`attachTo(formElement)`](#attachto-formelement) for targeted cases instead.
```javascript
window.CelloAttribution("attachAll");
```
***
## ~~`getReferral()`~~
> ⚠️ **Deprecated**: use [`getUcc()`](#getucc) instead.
```javascript
const ucc = window.CelloAttribution("getReferral");
```
### Returns
Unique campaign code/referral code
# Introduction
Source: https://docs.cello.so/sdk/client-side/cello-js-introduction
JavaScript SDK for embedding the Cello Referral Component in web applications
## What is Cello JS?
Cello JS is a browser-based JavaScript SDK that enables you to embed a fully-featured referral component directly into your web application. It provides a seamless way for your users to share referral links, track their performance, and receive rewards—all without leaving your product.
The SDK works with any web framework that outputs HTML/JavaScript, including:
* React, Next.js, and Gatsby
* Vue and Nuxt
* Angular
* Vanilla JavaScript applications
* Server-rendered applications (with client-side initialization)
## Getting Started
Follow our quickstart guide to integrate Cello JS in under 15 minutes:
Step-by-step instructions to add the Referral Component to your web app
## Key Capabilities
With Cello JS, you can:
### Core Functionality
* **Initialize the component** - Boot with user authentication and configuration
* **Manage visibility** - Show, hide, or programmatically open the component
* **Handle user sessions** - Update user details and manage authentication tokens
### Customization & Control
* **Change language** - Switch languages dynamically without re-initialization
* **Custom launchers** - Replace the default button with your own UI elements
* **Event callbacks** - React to component events like open, close, and token expiration
### Data & Communication
* **Retrieve referral links** - Get active referral codes and URLs programmatically
* **Access campaign config** - Fetch reward amounts and program details
* **Display announcements** - Show targeted messages and updates to users
### Advanced Features
* **Localization** - Access and customize all UI text labels
* **Country restrictions** - Automatically handle unsupported regions
* **Graceful shutdown** - Clean component removal when needed
## Mobile Applications
Looking to add referral functionality to your mobile app? Check out our native mobile SDKs:
Swift/Objective-C SDK for iOS apps
Kotlin/Java SDK for Android apps
Cross-platform mobile SDK
## Next Steps
[Follow the quickstart](/referral-component/quickstart) to add Cello JS to your application
[Set up JWT authentication](/sdk/client-side/user-authentication) for secure user sessions
[View all available methods](/sdk/client-side/cello-js-usage) in the usage documentation
# Usage
Source: https://docs.cello.so/sdk/client-side/cello-js-usage
Below is the full list of commands to call the Cello JS SDK with.
## `cello.boot(options)`
Initializes Cello Referral Component in your product.
Returns a promise that is resolved once the whole initialization process is finished or rejected if the boot command failed.
```javascript
window.cello = window.cello || { cmd: [] };
window.cello.cmd.push(async (cello) => {
try {
await cello.boot(options);
} catch (error) {
// Handle the error appropriately
}
});
```
The solution above is designed so that you don't have to wait for the library to finish loading before you call the command - follow it and use the `window.cello` object to avoid that particular race condition.
For any other commands, or when you are sure that the command is called after the library has finished loading, you can opt to use the regular command syntax:
```javascript
await window.Cello("boot", options);
```
### Accepts
The initialization options object:
Identifier of the product your users will refer.
You can obtain this in your Cello Portal.
Access token generated for the given user.
More in [User Authentication](/referral-component/user-authentication).
Product user details object. Required for select features
Email of the product user. This data is used in the personalization of the referral
experience, e.g. email notifications. Required for select features
First name of the product user.
This data is used in the personalization of the referral experience, e.g. email notifications and the [personalized message to referees](/docs/add-personalized-message).
Required for select features
Last name of the product user
Full name of the product user.
Use this option if you do not have first name and last name separately.
Product user country, if known. ISO 3166 Alpha-2 standard e.g. `DE`.
If the user is from an [unsupported country](/docs/component-overview#getting-rewarded), the Cello Referral Component will not be booted for this user and an error will be returned.
If no country is passed, Cello will still be booted.
The language, in which the Referral Component will be loaded in ISO 639-1.
Default: `undefined`. If undefined, we use default language set for your product.
Show or hide the Cello button, launching the Referral Component when it's first initialized.
Default: `false`
Callback event for when Referral Component widget is opened.
Callback event for when Referral Component widget is closed.
### Example
```javascript
window.cello = window.cello || { cmd: [] };
window.cello.cmd.push(async (cello) => {
try {
const options = {
productId: "REPLACE_WITH_PRODUCT_ID",
token: "REPLACE_WITH_TOKEN",
language: "en",
productUserDetails: {
firstName: "Bob",
lastName: "Bobsky",
fullName: "Bob B Bobsky",
email: "bob@gmail.com",
},
};
await cello.boot(options);
// Call other Cello commands, if necessary
} catch (error) {
console.error("Failed to boot cello:", error);
}
});
```
***
## `changeLanguage(language)`
Changes the Referral Component language at runtime without re-initializing it.
```javascript
window.Cello("changeLanguage", "de");
```
### Accepts
The language string in ISO 639-1
## `close()`
Closes Referral Component.
```javascript
window.Cello.close();
```
***
## `getActiveUcc()`
Returns active `ucc` and invite `link` for the currently logged-in user.
```javascript
const { ucc, link } = await window.Cello("getActiveUcc");
```
### Returns
The active ucc object:
Active unique campaign code or referral code for the current logged-in user
Personal invite link for the current logged-in user
## `getCampaignConfig()`
Returns campaign config values for the currently logged-in user.
```javascript
const campaignConfig = await window.Cello("getCampaignConfig");
```
### Returns
The campaign config object:
Primary currency code
Percentage of attributed new revenue that will be paid as a reward
Maximum reward that can be earned per referral
Additional reward for signups to encourage more sharing
Additional reward for purchases to encourage more sharing
How long new users get a discount
The discount new users get
## `getLabels()`
Returns select labels used in our Referral Component.
```javascript
const labels = await window.Cello("getLabels");
```
### Returns
The labels object:
A welcome text useful for building custom launchers
## `hide()`
Hides the Cello button or bookmark that launches the Referral Component.
```javascript
window.Cello("hide");
```
***
## `open(destination)`
Opens Referral Component.
```javascript
window.Cello("open", destination);
```
### Accepts
Optional destination string to open Referral Component on a specific tab or page:
* `"rewards"` - open Referral Component on the rewards tab
* `"edit-payments"` - open Referral Component on the payment details page
## `show()`
Shows the Cello button or bookmark that launches the Referral Component.
```javascript
window.Cello("show");
```
***
## `showAnnouncement(announcement)`
Triggers an [announcement](/docs/notifications#announcement).
```javascript
window.Cello("showAnnouncement", announcement);
```
### Accepts
### Example
Example below triggers a default welcome announcement:
```javascript
const announcement = { type: "welcome-announcement-1" };
window.Cello("showAnnouncement", announcement);
```
## `shutdown()`
Shuts down connection to Cello and unmounts the Referral Component.
```javascript
window.Cello("shutdown");
```
***
## `updateProductUserDetails(productUserDetails)`
Updates user details at runtime without re-initializing the Referral Component.
```javascript
window.Cello("updateProductUserDetails", productUserDetails);
```
### Accepts
The product user details object
Email of the product user. This data is used in the personalization of the referral
experience, e.g. email notifications. Required for select features
First name of the product user.
This data is used in the personalization of the referral experience, e.g. email notifications and the [personalized message to referees](/docs/add-personalized-message).
Required for select features
Last name of the product user
Full name of the product user.
Use this option if you do not have first name and last name separately.
### Example
```javascript
const productUserDetails = {
email: "bob@gmail.com",
firstName: "Bob",
lastName: "Bobsky",
fullName: "Bob Bobsky",
};
window.Cello("updateProductUserDetails", productUserDetails);
```
# Embedded Script Tag
Source: https://docs.cello.so/sdk/client-side/embedded-script-tag
Learn how to add Cello attribution script to your website
Attribution script helps you to capture referral code on your landing pages and make it available at signup to attribute referral conversions to the right referrers. In addition, it helps you to personalize messages for referees on the landing page, get discount information and detect potential fraud and abuse of your referral program.
# Adding the script
You can add attribution script to your website like any other third party JavaScript code by inserting the following code snippet into the `` tag of **each page** on your website.
Make sure to use `type="module"` and `async` html params in the script tag
```javascript
```
```javascript
```
# Verifying the installation
Now that you have added the attribution script to your website, make sure that the `ucc` is available on the signup page. To verify, follow these steps:
1. Add `?productId=test` and `?ucc=test` to your website URL
```html
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
```javascript
window.CelloAttribution('getUcc')
```
This method should return a promise with value `test`
```javascript
Promise {: 'test'}
```
If this check passes, the script is installed correctly.
# Google Tag Manager
Source: https://docs.cello.so/sdk/client-side/google-tag-manager
How to add the Cello attribution script to your site using Google Tag Manager
Learn how to install the Cello attribution script on your website using Google Tag Manager (GTM). This method is ideal for teams who want to manage tracking scripts without direct code changes.
## Prerequisites
Before you begin, ensure you have:
* A Google Tag Manager account and container set up on your website
* Admin access to your GTM container
* Your Cello product ID from the Cello Portal
## Step 1: Create a New Tag
1. Log in to your Google Tag Manager account
2. Select the container for your website
3. Click **Tags** in the left sidebar
4. Click the **New** button to create a new tag
5. Click the **Tag Configuration** area
## Step 2: Add the Cello Attribution Script
1. Select **Custom HTML** as the tag type
2. In the HTML field, paste the following code:
```html
```
3. Name your tag (e.g., "Cello Attribution Script")
## Step 3: Configure the Trigger
1. Click the **Triggering** area
2. Choose when you want the Cello attribution script to load:
### Option A: All Pages (Recommended)
* Select **All Pages** trigger
* This ensures referral codes are captured on any landing page
### Option B: Specific Pages Only
If you only want to track attribution on specific pages:
1. Click the **+** to create a new trigger
2. Select **Page View → Some Page Views**
3. Configure conditions (e.g., Page URL contains "landing" or "signup")
## Step 4: Save and Publish
1. Click **Save** to save your tag
2. Give your tag a descriptive name (e.g., "Cello Attribution - All Pages")
3. Click **Submit** to create a new version
4. Add a version description (e.g., "Added Cello referral attribution tracking")
5. Click **Publish** to make the changes live
## Step 5: Test Your Installation
### Method 1: Browser Console Test
1. Open your website in a new browser tab
2. Open the browser's developer console (F12)
3. Type the following command:
```javascript
window.CelloAttribution('getUcc')
```
If the script is installed correctly, you should see a Promise response:
```javascript
Promise {}
```
### Method 2: Test with Referral Parameters
1. Add the `?ucc=test123&productId=test` query parameters to your website URL:
```
https://yourwebsite.com/?ucc=test123&productId=test
```
2. Check that the referral cookies are being set in your browser:
* Open Developer Tools → Application → Cookies
* Look for `cello-referral` and `cello-product-id` cookies
3. Test `ucc` retrieval in the console:
```javascript
window.CelloAttribution('getUcc').then(ucc => console.log('ucc:', ucc))
```
Expected output: `ucc: test123`
### Method 3: GTM Preview Mode
1. In GTM, click **Preview** to enter debug mode
2. Visit your website - you should see the GTM debug panel
3. Verify that your "Cello Attribution Script" tag is firing on the correct pages
**Success indicators:**
* Cello attribution tag fires in GTM preview
* `window.CelloAttribution` function is available in console
* `ucc` cookies are set when visiting with referral parameters
* `getUcc()` method returns referral codes correctly
# User Authentication
Source: https://docs.cello.so/sdk/client-side/user-authentication
The Cello Referral Component contains sensitive data such as the identity of the referee, amounts of payouts and details regarding your user's referral flow e.g. notifications.
We use JWT (JSON Web token) to authenticate the user and authorize access to the data in the Referral Component.
The expected flow is as follows:
1. User logs into your system.
2. Your **backend** provides your frontend code with a **Cello JWT token**.
3. Your frontend code initializes the Referral Component with the **token**.
## Generating the token
Keep your credentials safe. **Never** generate a token or store your secret on the client side!
To generate a valid Cello JWT token, you'll need:
1. Your Cello credentials: **productId** and **product secret**
2. A **productUserId** that uniquely identifies the logged-in user
3. A token signing library for your tech stack of choice. A good variety can be found in the [JWT community](https://jwt.io/libraries)
For more resources on **server-side token** generation see [JWT community](https://jwt.io/introduction).
### Credentials
You will require both **productId** and **product secret** to generate tokens for your users.
You can find these in your [Cello Portal](https://portal.cello.so/integrations/accesskeys):
### User identity
Cello requires a **productUserId** - a unique user identifier to be passed when initializing the Referral Component.
This can be a user id that you already use to identify users in your product.
It can also be any other new unique identifier you generate - the main requirement is that it is unique per user accross your application.
It is important that this ID is **unique per user**, rather than organisation.
### JWT signing library
Regardless of the signing library you choose, make sure you use the `HS512` signing algorithm:
```json
{
"alg": "HS512",
"typ": "JWT"
}
```
### Token generation
Token payload attributes:
Identifier of the product your users will refer
Your logged-in user's unique identifier within your system
A token issuing Unix timestamp. Example: `1661876739`
Note that some libraries do not require you to pass `iat` in the payload and default to the current time if you don't.
### Example
Example of token generation in a NodeJS backend with JavaScript:
```javascript
import { sign } from 'jsonwebtoken';
const tokenPayload = {
productId: 'REPLACE_WITH_PRODUCT_ID',
productUserId: 'REPLACE_WITH_CURRENT_USER_ID',
};
const secret = 'REPLACE_WITH_PRODUCT_SECRET';
const token = sign(tokenPayload, secret, {
algorithm: 'HS512',
});
```
Creating a JWT token should **always** be done in your backend code and **not in the browser**!
Below is an example content of the generated JWT token.
```json
{
"productId": "acme.com",
"productUserId": "123456",
"iat": 1662712365
}
```
## Using the token
Finally, provide the server side-generated token in the `token` property when initializing the Referral Component.
```javascript
window.cello = window.cello || { cmd: [] };
window.cello.cmd.push(async (cello) => {
await cello.boot({
productId: "REPLACE_WITH_PRODUCT_ID",
token: "REPLACE_WITH_TOKEN",
...otherOptions,
});
});
```
# Introduction
Source: https://docs.cello.so/sdk/introduction
Explore our SDKs for adding referrals to your web and mobile apps.
# Web SDKs
Referral component for your web app
Script for tracking referrals on landing pages
# Mobile SDKs
Referral component for your iOS app
Referral component for your Android app
Referral component for iOS and Android
# Cello for Android
Source: https://docs.cello.so/sdk/mobile/android
The Cello SDK for Android enables you to add a referral program into your Android app. With a plug-n-play mobile component, your users can easily share their invite link with their friends and network using mobile sharing options convenient for them, receive rewards and get paid out.
## Installation
You can install Cello for Android using Gradle or manually. A basic installation takes around 15 minutes but will take a little longer if you want to customize the way the Cello Referral Component is launched.
### Compatibility
Cello SDK for Android is compatible with API 21 and up.
### SDK size
The size of Cello for Android once installed varies depending on your app’s configuration. Around 7MB is the average size increase we would expect to see if you're minifying your app correctly.
## Setup
Install Cello to see and give your users the option to spread the word from your Android app. Cello for Android supports API 21 and above.
**Note:** We recommend using the latest available `compileSdkVersion`.
### Install Cello
Add the following dependency to your app’s `build.gradle` file:
#### Groovy (or Kotlin DSL)
```gradle
dependencies {
implementation("so.cello.android:cello-sdk:0.7.1")
}
```
Also, ensure that Maven Central is added to your root `build.gradle`:
```gradle
allprojects {
repositories {
mavenCentral()
}
}
```
### Choose an Environment
In your Cello SDK setup, you have the flexibility to select the environment in which your application will run. This feature is especially useful for different stages of development, such as testing in a development or staging environment before going live in production. The available environments are:
* `prod` (Production) – *default*
* `sandbox` (Sandbox)
#### Configuration Steps
In your Android project, open or create `res/values/config.xml`, then add:
```xml
prod
```
To change the environment, simply replace the value of `cello_env`. For instance, to set the environment to sandbox:
```xml
sandbox
```
Save and rebuild your project to apply.
Using this configuration, the Cello SDK will adapt to the specified environment, allowing for more controlled development and testing processes.
## Initialize Cello
In this step, you will need your **product ID** and a **token** you have generated for the user, similar when [**implementing the web based Referral component**](https://docs.cello.so/docs/user-authentication).
Then, initialize Cello by calling the following in the `onCreate()` method of your application class:
```kotlin
Cello.initialize(this, "YOUR_PRODUCT_ID", token)
```
> **Note:** If you don't currently implement a custom application, you’ll need to create one. A custom application looks like this:
#### Kotlin
```kotlin
class CustomApplication : Application() {
override fun onCreate() {
super.onCreate()
Cello.initialize(this, "YOUR_PRODUCT_ID", token)
}
}
```
#### Java
```java
public class CustomApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
Cello.initialize(this, "YOUR_PRODUCT_ID", token);
}
}
```
> **Note:** Cello SDK must be initialized inside the application `onCreate()` method. Initializing anywhere else will result in the SDK not behaving as expected and could even result in the host app crashing.
## Customize the Cello Referral Component
The Cello SDK allows for various levels of customization to better fit into your app's design and flow. One of the main components you might want to customize is the [**Referral component**](https://docs.cello.so/docs/component-overview)
You have two options to launch the referral component:
### Default Launcher
If you choose to go with the default launcher, you can call the `showFab()` method from the Cello SDK to present a Floating Action Button (FAB) within your app. This FAB is pre-styled but may not perfectly match your app's look and feel.
```kotlin
Cello.client().showFab()
```
### Custom Launcher
If the default launcher does not fit your needs, you can implement your own custom launcher. This could be any UI element like a button, menu item, or even a gesture. To open the Referral component using a custom launcher, you can call `Cello.openWidget()`.
```kotlin
Cello.client().openWidget()
```
Example using Compose:
```kotlin
Button(onClick = { Cello.client().openWidget() }) {
Text("Open Referral")
}
```
## Android API
### `Cello.initialize()`
Initializes the Cello referral component.
| Name | Type | Description | Required |
| --------- | -------- | ----------------------------------------------- | -------- |
| activity | Activity | This is the reference to the MainActivity | Yes |
| productId | String | Identifier of the product your users will refer | Yes |
| token | String | Access token generated for the given user | Yes |
```kotlin
Cello.initialize(this, "YOUR_PRODUCT_ID", token)
```
### `Cello.showFab()`
Shows the Floating action button or bookmark that launches the Referral Component
```kotlin
Cello.client().showFab()
```
### `Cello.hideFab()`
Hides the Floating action button or bookmark that launches the Referral Component
```kotlin
Cello.client().hideFab()
```
### `Cello.openWidget()`
Opens the referral component.
```kotlin
Cello.client().openWidget()
```
### `Cello.hideWidget()`
Hides the referral component.
```kotlin
Cello.client().hideWidget()
```
### `Cello.getActiveUcc()`
A method to get an active `ucc` and invite link for the currently logged in user.
```kotlin
val result = Cello.client().getActiveUcc()
```
### `Cello.changeLanguage()`
A method to change the language of the Referral component at runtime without re-initialising it.
```kotlin
Cello.client().changeLanguage("de")
```
### `Cello.shutdown()`
Shuts down connection to Cello and unmounts the component
```kotlin
Cello.client().shutdown()
```
# Introduction
Source: https://docs.cello.so/sdk/mobile/introduction
Native mobile SDKs for embedding referral functionality in iOS and Android applications
## Available Mobile SDKs
Cello provides native mobile SDKs that embed a complete referral experience directly into your mobile applications, enabling users to share referral links, track rewards, and receive payouts—all without leaving your app.
Native Swift/Objective-C SDK for iOS apps
Native Kotlin/Java SDK for Android apps
Cross-platform SDK for React Native apps
## What Do Mobile SDKs Do?
The mobile SDKs provide the same comprehensive referral functionality as our web component, optimized for mobile experiences:
### Referral Component Features
* **In-app sharing interface** with native mobile sharing options (Messages, email, social media)
* **Real-time tracking** of referral performance and earned rewards
* **Reward management** with payout setup and history
* **Multi-language support** with automatic device language detection
### Native Mobile Integrations
* **Platform-specific UI** that follows iOS and Android design guidelines
* **Native sharing** using platform share sheets and messaging apps
* **Deep linking support** for seamless user journeys
* **Performance optimized** for mobile device constraints
### Customizations
You can customize the mobile Referral Component in the following ways:
* **Launcher** – Use the default button or implement a custom launcher to open the Referral component.
* **Hero Image** – Set a custom image for the sharing screen.
* **Copy** – Customize the text displayed in the component.
* **Brand Color** – Apply your brand’s primary color to match your app’s style.
* **Notification images** - Choose which image is displayed in the new view and new reward notification.
## Complete Mobile Referral Setup
After integrating the mobile SDK, you'll need to set up mobile attribution and referral conversion tracking:
### 1. Set Up Mobile Attribution
Configure deep linking and referral code capture for mobile app installs:
Learn how to capture referral codes through app store installs using Branch.io or similar services
### 2. Track Referral Conversions
Implement signup and purchase event tracking to reward referrers:
Send signup events when users create accounts
Send purchase events for subscription or one-time payments
## Getting Started
Select the appropriate SDK for your mobile platform
Follow the installation guide for your chosen SDK
[Configure mobile attribution](/attribution/for-mobile) to capture referral codes from app installs
Implement referral events for [signups](/attribution/tracking-signups) and [purchases](/attribution/tracking-purchases) to complete the referral flow
Mobile SDKs work independently but can be used alongside [Cello JS](/sdk/client-side/cello-js-introduction) if you have both web and mobile versions of your product.
# Cello for iOS
Source: https://docs.cello.so/sdk/mobile/ios
The Cello SDK for iOS enables you to add a referral program into your iOS app. With a plug-n-play mobile component, your users can easily share their invite link with their friends and network using mobile sharing options convenient for them, receive rewards and get paid out.
## Installation
A basic installation takes around 15 minutes but will take a little longer if you want to customize the way the Cello Referral Component is launched.
**Compatibility**
Cello for iOS is compatible with iOS 15 and up.
### SDK size
The size of Cello for iOS varies depending on your app’s configuration. For most installations, it’s around 3 MB in size.
## Setup
Install Cello to see and give your users the option to spread the word from your iOS app. The Cello for iOS library supports iOS **15+** and requires **Xcode 14** to build.
### Install Cello
#### Option 1: CocoaPods
Using the [latest version of Cocoapods](https://github.com/CocoaPods/CocoaPods/releases/latest), add CelloSDK to your Podfile and run `pod install`
```ruby
target :YourTargetName do
pod 'CelloSDK'
end
```
#### Option 2: Swift Package Manager
Add [**https://github.com/getcello/cello-ios-sp**](https://github.com/getcello/cello-ios-sp) as a Swift Package Repository in Xcode and follow the instructions to add CelloSDK as a Swift Package.
#### Option 3: Install Cello manually
1. Download Cello for iOS and extract the zip. (👉 [**Cello iOS zip download**](https://github.com/getcello/cello-ios-sp/releases))
2. Drag `CelloSDK.xcframework` into your project. Make sure **Copy items if needed** is selected and click Finish.
3. In the target settings for your app, set the `CelloSDK.xcframework` to **Embed & Sign** in the **Frameworks, Libraries, and Embedded Content** section of the **General** tab.
### Choose an Environment
In your Cello SDK setup, you have the flexibility to select the environment in which your application will run. This feature is especially useful for different stages of development, such as testing in a development or staging environment before going live in production. The available environments are:
Available environments:
* `prod` (Production)
* `sandbox` (Sandbox)
*`Default environment: prod`*
#### Configuration Steps
* Open your iOS project in Xcode.
* Navigate to the `Info.plist` file.
* Add a new key-value pair:
```xml
CELLO_ENVprod
```
* To switch to sandbox, change the string value to `sandbox`.
* Save your changes. The next build will use the selected environment.
Using this setup, the Cello SDK on iOS can adapt to the chosen environment, allowing a smoother and more controlled development and testing process.
## Initialize Cello
You’ll need your **product ID** and a user-specific **token** (similar to [the web-based Referral component flow](https://docs.cello.so/docs/user-authentication)):
```swift
import CelloSDK
Cello.initialize(for: "YOUR_PRODUCT_ID", with: token) { result in
switch result {
case .success(let configuration):
print("Initialization successful with config:", configuration)
case .failure(let error):
print("Initialization failed with error:", error)
}
}
```
## Customize the Cello Referral Component
The Cello SDK allows for various levels of customization to better fit into your app's design and flow. One of the main components you might want to customize is the [**Referral component**](https://docs.cello.so/docs/component-overview)
### Choose your launcher
* **Default launcher**: Use `Cello.showFab()` to present a pre-styled Floating Action Button (FAB).
```swift
import CelloSDK
Cello.showFab()
```
* **Custom launcher**: Use any UI element (button, menu item, gesture) and call `Cello.openWidget()` when you want to open it.
```swift
import CelloSDK
class YourViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
let myButton = UIButton(type: .system)
myButton.setTitle("Open Referral", for: .normal)
myButton.addTarget(self, action: #selector(didTapMyButton), for: .touchUpInside)
// Add 'myButton' to your view
}
@objc func didTapMyButton() {
Cello.openWidget()
}
}
```
### Advanced: Custom Callbacks
For even more control, you can implement your own delegate conforming to the `CelloDelegate` protocol. This allows you to get callbacks for significant events in the Referral component.
```swift
class YourViewController: UIViewController, CelloDelegate {
func celloWidgetDidOpen() {
print("Cello widget opened")
}
func celloWidgetDidClose() {
print("Cello widget closed")
}
override func viewDidLoad() {
super.viewDidLoad()
Cello.delegate = self
}
}
```
## iOS API
### Cello.initialize()
Initializes the Cello referral component.
| Name | Type | Description | Required |
| ---------- | -------- | ---------------------------------------------------------------------------- | -------- |
| productId | string | Identifier of the product your users will refer. Found in your Cello Portal. | Yes |
| token | string | Access token generated for the given user. | Yes |
| completion | callback | Receives success or failure with configuration or error. | |
```swift
import CelloSDK
Cello.initialize(for: "dev.cello.so", with: token) { result in
switch result {
case .success(let configuration):
print("Initialization successful with config:", configuration)
case .failure(let error):
print("Initialization failed with error:", error)
}
}
```
### Cello.showFab()
Shows the Floating action button or bookmark that launches the Referral Component
```swift
import CelloSDK
Cello.showFab()
```
### Cello.hideFab()
Hides the Floating action button or bookmark that launches the Referral Component
```swift
import CelloSDK
Cello.hideFab()
```
### Cello.openWidget()
Opens the referral component.
```swift
import CelloSDK
Cello.openWidget()
```
### Cello.hideWidget()
Hides the referral component.
```swift
import CelloSDK
Cello.hideWidget()
```
### Cello.getActiveUcc()
A method to get an active `ucc` and invite link for the currently logged in user.
```swift
import CelloSDK
let result = Cello.getActiveUcc()
```
### Cello.changeLanguage()
A method to change the language of the Referral component at runtime without re-initialising it.
```swift
import CelloSDK
Cello.changeLanguage(to: .de)
```
### Cello.shutdown()
Shuts down connection to Cello and unmounts the component
```swift
import CelloSDK
Cello.shutdown()
```
# Cello for React Native
Source: https://docs.cello.so/sdk/mobile/react-native
The Cello React Native wrapper allows you to use Cello for iOS and Cello for Android in your React Native apps. With a plug-n-play mobile component, your users can easily share their invite link with their friends and network using mobile sharing options convenient for them, receive rewards and get paid out.
## Installation
A basic installation takes around 15 minutes, but will take a little longer if you want to customize the way the Cello Referral Component is launched.
**Compatibility**
* The Cello React Native wrapper supports React Native **0.59** and above.
* Cello for iOS supports **iOS 15+**.
* Cello for Android supports **API 21+**.
### Install Cello
```bash
yarn add @getcello/cello-react-native
# or
npm install @getcello/cello-react-native
```
### Android Setup
#### Automatic Linking (RN v0.60+)
Library is automatically linked after installation.
#### React Native v0.59 (Automatic Linking)
```bash
react-native link @getcello/cello-react-native
```
#### React Native v0.59 (Manual Linking)
**`android/settings.gradle`**
```groovy
include ':cello-react-native'
project(':cello-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/@getcello/cello-react-native/android')
```
**`android/app/build.gradle`**
```groovy
dependencies {
implementation project(':cello-react-native')
}
```
### Android Initialization
Update your `MainApplication.java`:
```java
import com.celloreactnative.CelloReactNativeModule;
@Override
public void onCreate() {
super.onCreate();
SoLoader.init(this, /* native exopackage */ false);
CelloReactNativeModule.initialize(this, "productId", "token");
}
```
Also include internet permission in `android/app/src/main/AndroidManifest.xml`:
```xml
```
### iOS Setup
#### Automatic Linking (RN v0.60+)
Library links automatically after `pod install`.
#### Manual Linking (RN v0.59)
1. Open `.xcworkspace` or `.xcodeproj`.
2. Insert the `CelloSDK.xcframework` into your project (enable "Copy items if needed").
3. In target settings, set it to **Embed & Sign** under *Frameworks, Libraries, and Embedded Content*.
For additional information on iOS manual linking please refer to the [**React Native developer docs**](https://reactnative.dev/docs/linking-libraries-ios).
### iOS Initialization
In `AppDelegate.m`, add:
```objc
#import "AppDelegate.h"
#import
#import
#import
// ...
#import // <-- Add This
```
Next, in the method `didFinishLaunchingWithOptions` you'll need to initialize Cello. Add the snippet below using the `productId` and `token`
```
// ...
self.window.rootViewController = rootViewController;
[CelloReactNative initialize:for@"productId" with:@"token"]; // <-- Add this (Remember to replace strings with your product id and token)
return YES;
}
```
## Choose an Environment
In your Cello SDK setup, you have the flexibility to select the environment in which your application will run. This feature is especially useful for different stages of development, such as testing in a development or staging environment before going live in production. The available environments are:
* `prod` (Production) *(default)*
* `sandbox` (Sandbox)
For iOS follow [**Cello for iOS configurational steps**](https://docs.cello.so/docs/cello-for-ios#choose-an-environment)
For Android follow Cello for [**Android configurational steps**](https://docs.cello.so/docs/cello-for-android#choose-an-environment)
## Using Cello with Expo
If you are using Expo, you can use the built-in plugin. After installing the **@getcello/cello-react-native** package, add the [**config plugin**](https://docs.expo.io/guides/config-plugins/) to the `plugins` array of your `app.json` or `app.config.js`:
```json
{
"expo": {
"plugins": ["@getcello/cello-react-native"]
}
}
```
The plugin provides props to set environment. Every time you change the props or plugins, you'll need to rebuild (and `prebuild`) the native app. If no extra properties are added, defaults will be used.
* `env` (*string*): Set to your desired environment, such as `prod`, `sandbox`. Optional. Defaults to `prod`.
```json
{
"expo": {
"plugins": [
[
"@getcello/cello-react-native",
{
"env": "sandbox"
}
]
]
}
}
```
Next, rebuild your app as described in the [**"Adding custom native code"**](https://docs.expo.io/workflow/customizing/) guide.
## Customize the Cello Referral Component
The Cello React Native allows for various levels of customization to better fit into your app's design and flow. One of the main components you might want to customize is the [**Referral component**](https://docs.cello.so/docs/component-overview)
### Choose Your Launcher
The library provides two ways to launch the Referral component:
**Default launcher**
If you choose to go with the default launcher, you can call the `showFab()` method from the Cello library to present a Floating Action Button (FAB) within your app. This FAB is pre-styled but may not perfectly match your app's look and feel.
```js
import Cello from '@getcello/cello-react-native';
Cello.showFab();
```
**Custom launcher**
If the default launcher does not fit your needs, you can implement your own custom launcher. This could be any UI element like a button, menu item, or even a gesture. To open the Referral component using a custom launcher, you can call `Cello.openWidget()`.
```js
import Cello from '@getcello/cello-react-native';
const MyButton = () => {
return (
);
}
```
## React Native API
### `Cello.initialize(productId, token): Promise`
Initializes the Cello referral component.
| Name | Type | Description | Required |
| --------- | ------ | ----------------------------------------------- | -------- |
| productId | string | Identifier of the product your users will refer | Yes |
| token | string | Access token generated for the given user | Yes |
```javascript
Cello.initialize(productId, token)
```
### `Cello.showFab(): void`
Shows the default Cello button that launches the Referral Component
```ts
Cello.showFab();
```
### `Cello.hideFab(): void`
Hides the default Cello button that launches the Referral Component
```ts
Cello.hideFab();
```
### `Cello.openWidget(): void`
Opens the referral component.
```ts
Cello.openWidget();
```
### `Cello.hideWidget(): void`
Hides the referral component.
```ts
Cello.hideWidget();
```
### `Cello.getActiveUcc(): Promise<{ ucc: string; inviteLink: string; } | null>`
A method to get an active `ucc` and invite link for the currently logged in user.
```ts
const data = await Cello.getActiveUcc();
```
### `Cello.changeLanguage(langCode: string): void`
A method to change the language of the Referral component at runtime without re-initialising it.
```ts
Cello.changeLanguage("de");
```
### `Cello.shutdown(): void`
Shuts down connection to Cello and unmounts the component
```ts
Cello.shutdown();
```
## Step 2: Include the Cello Attribution Library
Add the Cello attribution script to your website's `` section or before the closing `` tag:
```html
```
## Step 3: Add the Attribution Command Queue
Since HubSpot forms are loaded dynamically, include this script to handle race conditions between your code and the Cello library loading:
```html
```
4. Submit your HubSpot form
5. HubSpot should now have created a new contact and a new company. In the new company, you should find the `ucc` property filled with the entered value `demo12345687`
6. The test was successful. You can now move ahead to the section on providing the required data to Cello.
## Troubleshooting
### Common Issues and Solutions
**1. "getReferral is not supported" error**
* Make sure you're using `getUcc()` instead of `getReferral()`
* This is the correct method for the latest attribution library
**2. Form fields not getting populated**
* Verify your form has a field with `name="ucc"`
* Check that the field selector in `querySelectorAll()` matches your form
* Ensure the `onFormReady` callback is executing
**3. Referral code is undefined**
* Test with a URL containing the `ucc` parameter: `?ucc=test123`
* Check browser cookies for `cello-referral`
* Verify the attribution script loaded properly
**4. Script loading order issues**
* Always include the command queue script before any attribution calls
* Use the `async` attribute on the attribution library script
## HubSpot Scheduling Pages Integration
You can also use the Cello attribution library with HubSpot scheduling pages to capture referral codes when prospects book meetings or demos. This is particularly useful for sales-led referral programs where referrals often lead to booked consultations or product demos.
### How it works
HubSpot scheduling pages include built-in forms that collect contact information before allowing visitors to book meetings. You can integrate Cello attribution with these forms using the same approach as regular HubSpot forms.
### Setup Steps
The integration process for scheduling pages is identical to regular forms:
1. Include the Cello Attribution Library (Steps 2-3 above remain the same)
2. Set up the `ucc` property in your HubSpot contacts/companies
3. Add a hidden `ucc` field to your scheduling page form
4. Configure the scheduling page to populate the referral code
### Adding `ucc` Field to Scheduling Pages
1. Create or edit a scheduling page ([HubSpot's scheduling page guide](https://knowledge.hubspot.com/meetings/create-scheduling-pages))
2. In the "Form" section, add the created `ucc` parameter to the form. You can't hide this field on a scheduling page. This field automatically picks up the `ucc` parameter from the link and feeds it into the created `ucc` property in HubSpot. The result should look like this:
### JavaScript Integration for Scheduling Pages
Since scheduling pages are embedded HubSpot components, you'll add the same integration code to the page where your scheduling page is embedded:
```html
```
### Testing Your Scheduling Page Integration
1. Visit your scheduling page with a referral parameter:
```
https://yoursite.com/book-demo?ucc=demo12345687
```
2. Start the booking process and fill out the form
3. Complete the booking
4. Check the created contact in HubSpot - the `ucc` field should contain `demo12345687`
### Key Differences from Regular Forms
* **Timing**: Scheduling pages load asynchronously, so we use MutationObserver to detect when the form is ready
* **Form structure**: Scheduling page forms are embedded HubSpot components with specific styling
* **Optional field**: Make the `ucc` field optional since not all meeting bookings will come from referrals
* **Meeting context**: The referral code will be associated with the contact and any resulting deals from the meeting
1. **Referral Link Sharing** - Referrers share links containing unique codes (`ucc` parameters)
2. **Landing Page Capture** - Your website captures and stores referral codes `ucc` as first-party cookies
3. **Signup Tracking** - New user registrations are linked to their referrer
4. **Purchase Tracking** - Revenue events are attributed back to the original referrers
## Setup of Sync from Typeform to HubSpot
## Test the created Typeform and HubSpot integration
2. In the view you just created, click **Apply Filter** to show only deals where Cello's referral code (`ucc`) is known.
3. Select the required columns for the **Attribution & Event report**. Make sure that the exported records can be linked with the records in the **Purchases report** via a common field, either the `Referred Account ID` or Cello's referral code (`ucc`). The Attribution & Event report should, at the very least, contain the following fields:
* `Referred Account ID` (which equates to the `Internal Account ID`)
* `Cello's referral code (`ucc`)`
* `Custom Event`
* `Create Date`
* `Last Modification Date`
4. Save the view.
5. Finally, click **Export** to export the view to a .csv file.
With these steps, you should be able to successfully create and export your custom HubSpot reports for use with Cello.
# Manual Attribution
Source: https://docs.cello.so/guides/attribution/manual-attribution
At Cello, we understand that there may be instances where automated referral attribution doesn't work as expected
At Cello, we understand that there may be instances where automated referral attribution doesn't work as expected. In such cases, our platform provides the flexibility to manually attribute referrals to ensure that your users receive the proper rewards for their efforts. This guide will walk you through the steps of manually attributing referrals within the Cello platform.
## When to Manually Attribute Referrals
1. **Technical Glitches**: If you encounter technical issues or glitches that prevent automated attribution, manual attribution allows you to override these challenges.
2. **User Disputes**: In cases where users claim they referred someone but the system did not capture it correctly, manual attribution provides a resolution path.
3. **Custom Scenarios**: For unique situations or custom referral setups, manual attribution offers a tailored solution.
## How to Manually Attribute Referrals
2. Select **Opportunities** from the available report types and click **Continue**.
3. Configure your report by applying the necessary filters and selecting the desired columns from the panel on the left-hand side.
4. Save the report for potential future exports by selecting the **Save** option.
5. Click **Export** to save the report data to a .csv file, suitable for import into Cello.
Following these steps will yield a .csv report structured for import into Cello that can be leveraged for attribution and event reporting.
# Stripe Reports
Source: https://docs.cello.so/guides/attribution/stripe-reports
With Stripe, you can manually export and import them into Cello. This feature is especially handy when you need to conduct some tests before enabling full automation
With Stripe, you can manually export and import them into Cello. This feature is especially handy when you need to conduct some tests before enabling full automation.
## Generating a Stripe Customer Export
After you've enriched the Stripe Customer with the right metadata, you're ready to export it as a .csv file. To do so:
1. Navigate to **Customers** > **Overview**, and then click **Export**.
2. Specify the details for the export:
* **Date range**: If you're submitting reports weekly or even more frequently, you can always opt for **Last 7 days**. Cello is designed to avoid importing duplicates.
* **Columns**: You only need to include **ID** and **Created (UTC)**. If `cello_ucc` has been added to the Customer metadata, it will always be added as a column in the exported file.
The exported .csv file for a Stripe Customer Export might look like this:
## Generating a Stripe Payment Export
Stripe allows you to export payments as a .csv file. To do so:
1. Go to **Payments** > **All Payments**, choose **Successful**, and then click **Export**.
2. Specify the details for the export:
1. **Date range**: Just as with the customer export, you can opt for **Last 7 days** if you're submitting reports frequently. Cello will prevent duplicate imports.
1. **Columns**: The data we suggest including in the report are: **ID**, **Description**, **Created (UTC)**, **Amount**, **Currency**, **Converted Amount**, **Fee**, **Tax**, **Converted Currency**, **Customer ID**.
# Contextual Sharing
Source: https://docs.cello.so/guides/best-practices/contextual-sharing
Guide for increasing referral sharing at key moments
Increase sharing by creating referral program awareness, keeping it top of mind for users and making referrals part of your main user flow. To achieve this, we recommend utilizing **moments of delight** and regular communication.
How to encourage referrers to share at key moments in the user journey:
* [Add a CTA to refer your product](#add-a-cta-to-refer-your-product)
* [Send an instant message to introduce the referral program](#send-an-instant-message-to-introduce-the-referral-program)
* [Add referral link to regular emails](#add-referral-link-to-regular-emails)
## Add a CTA to refer your product
A product lifecycle naturally has **moments of delight** when a user would be more likely to share their satisfaction with the product within their network. Add a CTA to open the [referral component](/sdk/client-side/cello-js-usage) at such moments and make referring part of this flow.
### How to implement?
For Developers
You can add a custom button anywhere in your UI at the moment of delight and have it open the Referral Component.
1. Identify where to add the button together with your Growth manager and UX designer
2. Use [window.Cello("open")](/sdk/client-side/cello-js-usage#open-destination) method to open the Referral Component when the button is clicked.
```javascript
window.Cello("open");
```
## Send an instant message to introduce the referral program
When your user reaches a **moment of delight** in their journey, that's the time to prompt them to share your product with an introductory in-product message i.e. [announcement](/guides/user-experience/referral-notifications-and-emails#announcement). This introduces the referral program to the user at the time they feel compelled to share their experience and effectively boost the conversion rate from users to referrers.
### How to implement?
For Developers
You can trigger [an announcement](/guides/user-experience/referral-notifications-and-emails#announcement) using [Cello.js](/sdk/client-side/cello-js-usage) client-side JS method at any point of the user journey. Here is how to do it:
1. Add [announcement to your custom launcher](/referral-component/custom-launcher#add-announcement-selector), so they are displayed when triggered.
2. Use [window.Cello("showAnnouncement")](/sdk/client-side/cello-js-usage#showannouncement-announcement) method to open the Referral Component when the button is clicked.
Below example will trigger a default [welcome announcement](/guides/user-experience/referral-notifications-and-emails#announcement):
```javascript
window.Cello("showAnnouncement", { "type": "welcome-announcement-1" } );
```
### How to implement?
For Developers
Depending on your email sending service, you can add additional content to your email, in this case, a personal invite link. To get the link for each referrer, you can use our Cello API [/active-link endpoint](/api-reference/user-referrals/get-active-referral-link) and enrich the emails you already send to your users with information about referral program and their personal invite link.
# Improve User Activation
Source: https://docs.cello.so/guides/best-practices/improve-user-activation
Recommendations to optimize the signup conversion of referred users
This page provides recommendations to optimize the signup conversion of referred users. Cello offers a variety of options that range from stunning new user experiences with personalized website content to easy setup solutions.
## Increase discoverability of your referral program
**Get started now:**
🔗 [Show Cello floating button](/sdk/client-side/cello-js#show) by default. Contact your CS team for adjustments to the floating button.
🔗 [Custom launcher](/referral-component/custom-launcher) to add menu integrations (paid feature).
## Integrate referral ask at moments of delight
**Get started now:**
🔗 **Simple option**: Add [button or UI for opening referral widget](/sdk/client-side/cello-js#open-destination) to your existing user flows.
🔗 **Advanced option**: Set up [behavior-based triggers](/guides/best-practices/behavior-based-triggers) to send a custom message to users upon completion of a defined trigger moment.
## Enable essential notifications with Cello email campaigns
**Get started now:**
Contact your Cello CS team to activate email campaigns in Slack or at [support@cello.so](mailto:support@cello.so). Email addresses need to be provided on boot of Cello to activate certain types of emails.
### Customize Cello in-app messages
**Get started now:**
Contact your Cello CS team to activate the activation campaigns and customize messages [here](https://getcello.typeform.com/to/Np4C9iiO).
# Optimize signup conversion
Source: https://docs.cello.so/guides/best-practices/optimizing-signup-conversion
Recommendations to optimize the signup conversion of referred users
This page provides recommendations to optimize the signup conversion of referred users. Cello offers a variety of options that range from stunning new user experiences with personalized website content to super simple setup solutions.
## Increase conversion by showing discount info on website
**Get started now:**
🔗 Docs: [Personalizing referrals](/guides/user-experience/personalizing-referrals)
🔗 [Wise referral program with personalization](https://wise.com/invite/dic/tanjam2?utm_source=desktop-invite-tab-copylink\&utm_medium=invite\&utm_campaign=\&utm_content=\&referralCode=tanjam2)
🔗 [MeetGeek website with personalized new user banner](https://meetgeek.ai/meetgeek-referral?productId=app.meetgeek.ai\&ucc=vTlj7ne4Fkf\&n=VG9iaWFz)
## Increase conversion with stand-alone landing page
**Get started now:**
Once your referral landing page is ready to go, reach out to your Cello CS team in Slack or at [support@cello.so](mailto:support@cello.so) to enable forwarding new users directly to the page.
🔗 [Typeform landing page](https://www.typeform.com/refer-a-friend/invite/?utm_medium=referrerlink\&utm_source=typeform\&utm_campaign=refer_a_friend_cello\&productId=admin.typeform.com\&ucc=ARn30TGHAsq)
🔗 [Superhuman landing page with personalization](https://superhuman.com/refer?utm_source=product\&utm_medium=signature\&utm_campaign=bob%40bobinsky.me)
🔗 [Heyflow standalone landing page](https://get.heyflow.app/referral-lp?productId=go.heyflow.app\&utm_source=cello\&utm_medium=referral\&utm_campaign=Cello-RS20-C1000-D50\&ucc=2dRGoRjgP7A#start)
🔗 [Cello standalone landing page with direct signup](https://cello.so/invitation/)
# Reward structure FAQs
Source: https://docs.cello.so/guides/campaigns/faqs
Frequently asked questions about campaign setup, reward structures, and referral program management to help you optimize your program performance.
## What is a convincing reward for the referrer?
Cello provides a recommendation on how to set the reward structure during the onboarding. You can find it on your individual “Set the reward structure” page on the Onboarding Notion.
## Does Cello allow to set different reward parameters for different user segments?
Currently only one campaign can be configured. One campaign comprises both the configuration of the referral experience flow and the reward parameters specified in that flow. Cello plans to support multiple campaigns in the near future.
## Is it possible to change the reward parameters retroactively for referrals that are already completed?
Cello considers a referral as completed with the referred account becoming a paying customer of the referred product. Once a referral is completed the parameters for this referral cannot be changed anymore. Changing rewards retroactively would potentially lead to a disappointing user experience for the referrer.
## Is it possible to change the reward parameters in the future?
It is possible to change the reward parameters for the referral program for future referrals. To bring the adjustment live, both the reward parameters and the referral flow have to be updated. Once the update is live, all future completed referrals will be rewarded according to the updated reward parameters. This is also the case even if the referrer shared the referral link still seeing the previous reward structure.
## Which currencies does Cello support for rewarding users?
Currently, rewards for referrers are available in all currencies that Paypal supports. You can find more details in the Paypal documentation.
## From which reward options can a referrer choose?
Cello currently offers payouts via Paypal. The list of supported countries for payouts is ”Austria, Belgium, Canada, Czechia, Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Netherlands, Norway, Poland, Portugal, Romania, Spain, Sweden, Switzerland, United Kingdom, United States” Additional reward options like gift cards, bank transfers, donations are on our backlog. Venmo is available for the US upon request.
# Setting Up Campaigns
Source: https://docs.cello.so/guides/campaigns/setting-up-campaigns
Cello makes it easy to automatically notify and reward your users for making successful referrals
Cello makes it easy to automatically notify and reward your users for making successful referrals. This is done by creating **campaigns** with specific **payout rules.**
Your rules are then automated based on confirmation of **events** and **purchases.** These can be based on transactions for referred contacts, but can also be based on free trials, demos, or events you define.
## Example: Recurring Rewards Encourage Continuous Sharing
In this typical example, a referrer is rewarded **50%** for each referral up to a **\$100 maximum reward cap** with a **\$5 signup bonus**. The referee initially purchases a **\$10** subscription for herself, and then **upgrades her team** in the following month.
The reward is paid to the referrer over a 6 month period until the referrer reaches a **maximum cap of \$100** for this referral. In the meantime, these regular rewards encourage further sharing.
It's important to note that the **new user also receives an exclusive 50% discount** from the referrer when purchasing for the first 6 months. Our research shows that **symmetric rewards** (i.e., the referrer and the referred have incentives of similar values) work best because referrers invest their social capital when recommending a product; having similar incentives makes the referral look fair to both parties involved.
## Campaign Settings
All campaigns must have one or more rules to reward referrers for the referrals they made. **Campaign** settings can be configured in the [Cello portal in the Setup section](https://portal.cello.so/setup/campaigns).
Rewards are typically based on a **percentage** of the transaction amount generated when new customers make a payment up to a **maximum** amount per referral. Additional rewards can also be set on other key events such as **signups** and **purchases** to help encourage more engagement and sharing.
| **Section** | **Rule** | **Description** |
| --------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Referrer Reward | Percentage of revenue | Percentage of attributed new revenue that will be paid as a reward |
| Referrer Reward | Maximum reward (per referrer) | The maximum reward that can be earned per referral |
| Referrer Reward | Bonus rewards | Additional rewards that can be set for signups or purchases to encourage more sharing. Bonus rewards are also recommended for products with longer free to paid conversion times. |
| New User Reward | Percent Discount and Months | The new user discount to encourage additional sharing. |
2. Enter the **email** and **campaign** you want to assign to the partner user. **Product User ID** is optional and should be added if you want to update an existing user to partner status.
# Overview
Source: https://docs.cello.so/guides/partners/partner-overview
Cello allows you to set up and manage all aspects of your own partner program, unifying user referrals and partners in one platform
Cello allows you to set up and manage all aspects of your own partner program, unifying user referrals and partners in one platform. All partner features are offered as part of the core Cello platform without additional technical effort needed.
Accessing Program Details
Partners can access program details by clicking on **Your Sharing Link** on the left navigation. All details are provided from the Cello referrals component, in the same way your users access Cello from within your application.
## Getting Rewarded
Clicking on **Your Reward Details** opens the Cello component with details of all rewards. Partners who have not provided payment details can do so from this page.
## Partner Analytics
Cello provides partners with detailed analytics for tracking program performance on their referrals. An overview is provided on the **Home** page, with more details provided on the full funnel from the **New User Signups** and **New User Purchases** page .
# Partner Resources
Source: https://docs.cello.so/guides/partners/partner-resources
This guide is designed to help Partner Managers effectively use the Partner Resources feature to add, manage, and share guides and resources with partners
This guide is designed to help Partner Managers effectively use the Partner Resources feature to add, manage, and share guides and resources with partners.
The Partner Resources section is a dedicated space for creating and managing guides and content that can be shared with your partners. It allows you to:
1. Add new guides with detailed descriptions and cover images.
2. Organize resources for easy partner access.
3. Provide links to videos, articles, or pages to help partners promote your products or services.
### Adding a New Guide
If no resources are added yet, you'll see a placeholder message encouraging you to create your first guide.
1. **Click the "Add New Guide" Button**:
* Located at the top right of the Partner Resources dashboard.
2. **Fill Out the Form**:
* **Title**: Enter a clear and concise title for the guide.
* **Description**: Provide a brief description of the guide's purpose.
* **Cover Image**: Upload an image to visually represent the guide. Use the "Select files" area to drag and drop or browse files from your machine.
* **Link**: Add a URL to direct partners to the guide's content, such as a video, article, or webpage.
3. **Save the Guide**:
* Click the **Add** button to save the guide.
💡 **Once added, guide is instantly visible for your partners.**
### Managing Existing Guides
Once guides are added, they appear as individual cards in the Partner Resources dashboard. Each card includes:
1. **Title and Description**: A quick summary of the guide.
2. **Actions**:
* **Edit**: Use the pencil icon to update the guide's details.
* **Delete**: Use the trash icon to remove the guide.
3. **Call-to-Action Buttons**:
* Depending on the link type, buttons like "Watch Video," "Read Article," or "Go to Page" will appear, directing users to the linked resource.
## Best Practices for Creating Guides
1. **Use Descriptive Titles and Images**:
* Ensure titles are specific and relevant to the guide's content.
* Upload visually appealing and professional cover images to attract attention.
2. **Organize by Purpose**:
* Group guides by themes, such as "Overview," "Sharing Tips," or "Content Creation Examples," for easier navigation.
3. **Test Links**:
* Verify that all links lead to the correct resource and are accessible to partners.
## Example Use Cases
### Case 1: Sharing Partner Links
Create a guide titled **"Overview"** with a description like: "Share your partner link with contacts and followers." Include a video tutorial link to help partners understand how to use their referral links.
### Case 2: Promoting Your Product
Add a guide titled **"Share"** with instructions on promoting your product. Link to an article that offers best practices for sharing content on social media.
### Case 3: Content Creation Support
Provide a guide titled **"Content"** with social media post templates and examples. Link to a page where partners can download assets or view tips.
## Frequently Asked Questions (FAQs)
### Q: Can I reorder the guides?
A: Currently, guides are displayed in the order they were added. You may delete and recreate guides to adjust the sequence if necessary.
### Q: What file formats are supported for cover images?
A: Common image formats like JPG, PNG, and GIF are supported.
### Q: How do I ensure partners can access the links?
A: Use publicly accessible links or grant appropriate permissions to ensure partners can view the resources.
***
# Configuring Referral Component
Source: https://docs.cello.so/guides/user-experience/configuring-referral-component
The Referral Component is an all-in-one referral experience, easily added to your web application
The Referral Component is an all-in-one referral experience, easily added to your web application. It takes care of things like referrer first-time experience, enabling users to share links, updating them on progress, and handling rewards.
## Adding the component to your product
First, add the Referral Component into your application with the help of your developer. Simply follow the instructions on the [Referral Component integration guide](/referral-component/quickstart).
## Customize referrer experience
After adding component to your application, you now can customize referrer experience in Cello Portal.
### Choose Cello button design and position
You can use either the default Cello button (FAB) or integrate Cello into a menu via the [custom launcher](/referral-component/custom-launcher), or both as the launcher. If you do not want to use the Cello button, simply uncheck "Show Cello button".
If you are using the Cello button, you can choose on of **3 styles**, configure its position and also specify how would you like to display the [announcements](/guides/user-experience/Referral-Notifications-And-Emails#announcement).
### Choose component type
Component can be displayed as a **pop-up** or a **modal**. When you choose pop-up view, you can also configure pop-up position on the screen.
### Choose your brand colors for Component
You can choose primary color for your component, colors of the Cello button and color of [notification badge](/guides/user-experience/Referral-Notifications-And-Emails#alert-and-badge).
### Choose social sharing options
Cello provides many sharing options to choose from. Simple link copy, social sharing including Twitter, LinkedIn, and email, and transfer to mobile by using a QR-code where a user can forward the invite using all the options provided directly from their mobile device.
### Choose payment method options
Cello allows users to receive rewards via PayPal or Venmo payments. Additional payment options are planned based on user feedback.
# New User Discounts
Source: https://docs.cello.so/guides/user-experience/new-user-discounts
Offering discounts or rewards to referees is a powerful strategy for improving signup conversion
Offering discounts or rewards to referees is a powerful strategy for improving signup conversion for several reasons:
1. **Sense of Urgency:** Time-limited discounts create a sense of urgency, encouraging referees to act swiftly to take advantage of the offer. This urgency can lead to quicker decision-making and increased conversion rates.
2. **Enhancing Referral Motivation:** When referrers know that their referrals lead to tangible benefits like discounts for their contacts, they're more likely to actively promote your product. This not only increases the number of referrals but also the likelihood of signups.
3. **Overcoming Price Resistance:** Discounts can effectively lower financial barriers for potential users who are hesitant about the cost. By making the price more attractive, it can sway those who are undecided about trying your product or service.
4. **Building Initial Trust:** Offering a discount can foster goodwill and build initial trust with new users. A special deal can create a positive first impression of your brand, setting the stage for a lasting relationship.
5. **Competitive Advantage:** If your competitors do not offer similar incentives, your discount can give you a competitive edge. This unique selling point can make your product more appealing compared to others in the market.
This page describes how a **discount to the new referred account can be automated using Stripe or Chargebee** (e. g. 50% discount for the first 6 months).
## Configure discount information
Altho handling discounts needs to be done within your product and supporting systems like Stripe or Chargebee, you can specify discount information in Cello to be shown in the Referral Component and terms.
Go to [Campaign settings in Cello Portal](https://portal.cello.so/setup/campaigns) and add discount information, by specifying discount percentage and duration in months:
How do I grant discounts in Chargebee?
Chargebee uses **coupons** to apply discounts on subscriptions. To grant a discount for a new referred account, the following steps are required:
* Create a coupon either via the [Chargebee Dashboard](https://www.chargebee.com/docs/2.0/coupons.html#creating-coupons) or the [Chargebee API](https://apidocs.chargebee.com/docs/api/coupons?prod_cat_ver=2)
* Attach the coupon code to the [subscription](https://apidocs.stagingcb.com/docs/api/subscriptions?prod_cat_ver=2)
## How do I grant discounts in Stripe?
Stripe uses **coupons** and **promotion codes** to apply discounts on payments. To grant a discount for new referred accounts, these coupons and promotion codes have to be set up in Stripe.
This can be done in multiple ways. For both solutions, you **must first set up a coupon and then attach the discount rules** (e.g. 10% off for 3 months).
* Manually using the [Stripe Dashboard](https://dashboard.stripe.com/coupons)
* Programmatically using the [Stripe API](https://stripe.com/docs/payments/checkout/discounts#promotion-codes).
## Using coupons for discounts
Coupons can be used to attach a discount directly to a **stripe customer** or a **subscription.** This can be achieved manually via the [Stripe Web Console](https://dashboard.stripe.com/coupons) or the [Stripe API](https://stripe.com/docs/billing/subscriptions/coupons?dashboard-or-api=api).
Attach manually via **Stripe Web Console**:
Attach the coupon during customer creation as discount field via **Stripe API:**
### Attach the coupon to the customer or subscription
3. Select the coupon you want to attach
**💸 If the customer subscribes now to a plan or performs a transaction, the discount will be automatically applied during the checkout.**
### Attach the coupon during checkout with Stripe API
The prerequisite for this solution is to have implemented the [Stripe.js](https://stripe.com/docs/js) in your front end so you can modify the customer creation or subscription.
## Using promotion codes for discounts
A **Promotion Code** represents a customer-redeemable code for a coupon. They can be used for the **Stripe Payment Link** **or custom-built forms**. Here are their key characteristics:
* When using a **Promotion Code,** the setup of an underlying coupon is also required.
* **Promotion Codes** can be used to create multiple codes for a single coupon.
* Because **Promotion Codes** are used by customers to redeem a coupon, they are exposed to customers.
### Pre-fill the promotion code in Stripe Payment Link
With the URL parameter `prefilled_promo_code` a promo code can be automatically passed to the UI. The form automatically picks up the parameter from the URL and pre-fills the promotion code field. More details can be found [here](https://stripe.com/docs/payments/payment-links#url-parameters).
**Example:**
10% off for 3 months via promo code `CELLO`
[https://buy.stripe.com/cello?prefilled\_promo\_code=CELLO](https://buy.stripe.com/cello?prefilled_promo_code=CELLO)
# Optimizing Referral Landing Page
Source: https://docs.cello.so/guides/user-experience/optimizing-landing-pages
This guide focuses on optimizing landing pages for referrals, a critical step in the user journey
This guide focuses on optimizing landing pages for referrals, a critical step in the user journey. A referee's first interaction with your product occurs when they follow an invite link, making the page they land on a key determinant in the success of your referral program.
### In this guide
This guide walks you through the key building blocks of a referral-optimized landing page to ensure referees smoothly transition from interested to signing up.
There are a few approaches you can take when designing your referee signup flow:
* [Using a dedicated landing page](#dedicated-landing-page) Recommended
* [Using your home page as the landing page with inline personalization](#home-page-as-the-landing-page-with-inline-personalization)
* [Using your home page as the landing page with our new user banner for personalization](#home-page-as-the-landing-page-with-new-user-banner) No code
## Dedicated landing page
A dedicated page that the referee lands on when clicking on the invite link has shown to have up to **x2 higher conversion rate** if done right. Below, you can find examples of the landing pages we like along with the key building blocks to make a dedicated landing page perform.
### Key building blocks
#### Headline: Personalized Exclusivity
Craft a headline that feels exclusive and personal. [Use personalization](#add-personalization) for additional social proof like adding the referrer's name, and highlight [any special discount or reward](#add-a-new-user-discount-or-reward). This approach creates a sense of trust and urgency.
#### Key Value Proposition: Clarity in One Sentence
Distill your product's core benefit into a single, compelling sentence. This should quickly inform the visitor whether your product meets their needs, making their decision process easier and faster.
#### Content: Concise and Informative
Streamline your content compared to your main homepage. Provide just enough detail to help visitors understand your product and how it can work for them, without overwhelming them or necessitating navigation away from the page.
#### CTA Focus: Direct and Offer-Centric
Make your Call-to-Action (CTA) clear and direct, with an emphasis on the action you want the referee to take. If there's a special offer or discount, ensure your CTA highlights this to maximize conversion.
#### Social Proof: Credibility through Endorsements
Include social proofs such as G2/Capterra badges, Trustpilot ratings, customer logos, and quotes. These elements build trust and credibility, showing potential users that others have had positive experiences with your product.
#### FAQs: Contextual Information
Integrate a section for Frequently Asked Questions (FAQs) to address common queries. This helps provide referees with all the necessary information on the same page, reducing the likelihood of them leaving the page without signing up. If they return later, they can still be tracked towards the referral, but the best time to capture a new user is the first time they click the referral link.
### Add a new user discount or reward
Offering discounts to referees effectively boosts signup conversion by fostering urgency, encouraging active promotion, reducing cost concerns, and giving a competitive advantage when similar incentives aren't available from competitors. [Learn more about adding discounts 👉](/guides/user-experience/adding-discounts)
If your program offers discounts or rewards to referees, make sure to highlight it in the Headline and CTA.
💡 Our research shows that **symmetric rewards** (i.e. the referrer and the referred have incentives of similar values) are more effective. This happens because referrers invest their social capital when recommending a product; having similar incentives makes the referral look fair to both parties involved.
**Examples of dedicated landing pages**
🔗 [Heyflow stand-alone landing page](https://get.heyflow.app/referral-lp?productId=go.heyflow.app\&utm_source=cello\&utm_medium=referral\&utm_campaign=Cello-RS20-C1000-D50\&ucc=2dRGoRjgP7A#start)
🔗 [Cello stand-alone landing page with direct signup](https://cello.so/invitation/)
### Add personalization
*"The most credible advertising comes straight from the people we know and trust. More than eight-in-ten global respondents (88%) say they completely or somewhat trust the recommendations of friends and family." Nielsen Global Trust in Advertising Report, 2021*
Personalization and social proof, like using the referrer's name on the landing page, can contribute to converting referees into users. The personalization establishes trust and credibility, makes the offer more relevant and engaging, leverages an existing relationship, fosters a sense of community and belonging, reduces perceived risk, and has an emotional appeal. These elements together make the referral more compelling, encouraging referees to sign up. [Learn more about personalization 👉](/guides/user-experience/personalizing-referrals)
💡 **Leveraging existing assets -** Do you already have an optimized landing page for ads? You don't need to start from scratch. Reuse the layout and some of the content to build a dedicated referral landing page.
**Examples of personalized landing pages**
🔗 [Reword stand-alone landing page with personalization](https://reword.com/referral?productId=reword.com\&ucc=IX2FHjt1Y0Z\&celloN=Q29udGVudCBDeWJvcmc)
🔗 [Wise Referral Program with personalization](https://wise.com/invite/dic/tanjam2?utm_source=desktop-invite-tab-copylink\&utm_medium=invite\&utm_campaign=\&utm_content=\&referralCode=tanjam2)
🔗 [Superhuman landing page with personalization](https://superhuman.com/refer?utm_source=product\&utm_medium=signature\&utm_campaign=bob%40bobinsky.me)
## Home page as the landing page with inline personalization
Use your existing home page as landing page and [add a discount](/guides/user-experience/new-user-discounts) and [personalization](/guides/user-experience/personalizing-referrals) into your home page Headline and CTA.
## Home page as the landing page with New User Banner
The [New User Banner](/guides/user-experience/personalizing-referrals) is easily added to your landing page by integrating the [Cello attribution library](/sdk/client-side/attribution-lib). Visitors who follow the Cello invite link will have a banner that includes the discounts, tailored CTA, and personalization on your home page.
**Examples of landing pages with new user banner**
🔗 [MeetGeek Website with personalized new user banner](https://meetgeek.ai/meetgeek-referral?productId=app.meetgeek.ai\&ucc=vTlj7ne4Fkf\&n=VG9iaWFz)
## Get started now
Once your referral landing page is ready to go, go to you product dashboard [New User Experience setup page](https://portal.cello.so/setup/new-user-experience) and switch to **Custom landing page**.
In **Custom landing page URL** field, add the URL to your new landing page and **Save**.
# Overview
Source: https://docs.cello.so/guides/user-experience/overview
The Referral Component is an all-in-one referral experience, easily added to your web application with just a few lines of code
The Referral Component is an all-in-one referral experience, easily added to your web application with just a few lines of code. It takes care of things like referrer first-time experience, enabling users to share links, updating them on progress, and handling rewards. This functionality helps to keep your users happy and engaged with your referral program.
Let's review some of the key capabilities 👉
## Adding the component to your product
Adding the Referral Component to your product is straightforward. You can get it up and running in your test environment in just a few minutes. Simply follow the instructions or the [Referral Component Quickstart](/referral-component/quickstart).
Cello provides a few different options to add the component to your product. You can use either the default Cello button (FAB) or integrate Cello into a menu via the [Custom Launcher](/referral-component/custom-launcher). Either option can open with the component appearing as a pop-up or modal view.
## First-time experience
The Cello Referral Component provides an onboarding experience for first-time users of the program. It's a way to get users excited about the opportunity and explain how the program works in 3 easy steps. All the texts of the onboarding experience can be customized to better explain your unique value proposition.
## Your offer, front and center
The referral program text and offer are fully customizable and can be translated into multiple languages.
## Easy sharing
Cello provides many sharing options to choose from. Simple link copy, social sharing including Twitter, Facebook, LinkedIn, and email, and transfer to mobile by using a QR-code where a user can forward the invite using all the options provided directly from their mobile device.
## Engaging users with announcements
The Cello Referral Component provides a robust announcement feature to activate first-time referrers, keep the referral program top of mind, encourage repeat behaviour, and keep your users up to date with important updates.
Announcements can be customized based on the Referral Component integration option you have chosen. [Anchor announcements to a specific menu item](/referral-component/custom-launcher#add-announcement-selector) or choose to have them appear as toasts or banners.
## Keeping users update with emails
Referral programs thrive on timely engagement. Knowing instantly when there's activity tied to a referrals means your users can celebrate successes and continue to share more effectively. Whether it's their first successful share, a brand-new signup or unlocking a new reward, email notifications ensure they never miss a beat in the referral journey.
## Getting Rewarded
When users receive their first reward, they will be prompted to provide payment details and can select how they would like to receive their reward. They may also be asked to provide additional information if required to receive a payment in their specific country.
## Reward Countries and Payout Methods
Cello supports a growing list of countries\* where users can receive reward payments. Cello plans to continue expanding support for additional countries based on user feedback.
Cello can be automatically hidden for users in unsupported countries by providing country information when [integrating the Referral Component](/sdk/client-side/cello-js#celloboot). This is recommended to provide the best experience for your users.
Cello allows users to receive rewards via PayPal or Venmo payments. Additional payment options are planned based on user feedback.
All users are subject to the Cello [Terms of Service](https://cello-growth.notion.site/Terms-of-Service-40b8093e87e04429b862a601a1d23fc1/) and [Privacy Policy](https://cello-growth.notion.site/Privacy-Policy-for-Platform-76a94bd64cb44e1f92a6cec3ec5643ca) and can access details through the links that are provided. Referrers are able to get rewarded as a business and receive invoices for tax purposes.
Users are required to provide additional taxpayer information based on the specific country of residence and local reward thresholds or choose to be paid as a business by providing their VAT number.
Cello allows users to download credit notes directly from the Cello Referral Component. If they have at least one reward, they will see a link "Tax Information" link from the rewards tab under "Update Payment Details". Users who no longer have access to the Cello component can contact [support@cello.so](mailto:support@cello.so) to receive their credit notes through a standard support process.
*Supported Reward Countries: Australia, Austria, Bahrain, Belgium, Bermuda, Botswana, Brazil, Bulgaria, Canada, Cayman Islands, Chile, Croatia, Czechia, Denmark, Dominican Republic, Estonia, Faroe Islands, Finland, France, French Guiana, Georgia, Germany, Gibraltar, Greece, Greenland, Guatemala, Hong Kong SAR, Hungary, Iceland, India, Ireland, Israel, Italy, Japan, Latvia, Lesotho, Liechtenstein, Lithuania, Luxembourg, Malta, Mauritius, Mozambique, Netherlands, Nicaragua, Norway, Oman, Philippines, Poland, Portugal, Qatar, Romania, San Marino, Saudi Arabia, Senegal, Slovakia, Slovenia, South Africa, Spain, Sweden, Switzerland, Thailand, Ukraine, United Kingdom, United States, Uruguay, Zambia, Zimbabwe.*
## Texts and language
You can customize the default text that appears on the Referral Component and provide different language options for your users. The Cello component detects a user's language automatically or you can set it [using Referral Component JS methods](/sdk/client-side/cello-js).
We provide English, German, Spanish, French, Dutch, Italian, Portuguese, Japanese, Danish and Slovak by default and Cello will help you add additional languages on request.
# Personalizing Referrals
Source: https://docs.cello.so/guides/user-experience/personalizing-referrals
Add personalized messages to your landing pages to increase conversion rates
In this guide we will go through:
* The benefits of personalization
* How to add personalization to your landing pages:
* [Inline](#add-personalization-to-the-headline-or-other-page-element) Recommended
* [Using the new user banner](#add-personalization-with-new-user-banner) No code
## Why personalization?
Personalization and social proof, such as including the referrer's name in the landing page headline, are crucial for converting referees into signed-up users due to several key reasons:
1. **Enhanced Trust and Credibility:** Seeing a familiar name like "Bob has gifted you a free month to try Moonly" immediately establishes a sense of trust. The referee recognizes the referrer, which lends credibility to the offer.
2. **Increased Relevance and Engagement:** Personalization makes the offer feel more tailored and relevant to the referee. A message that appears to be handpicked for them can create a stronger emotional connection and engagement with the content, increasing the likelihood of a positive response.
3. **Leveraging Existing Relationships:** Utilizing the referrer's name capitalizes on the existing relationship between the referrer and the referee. This relational dynamic can be a powerful motivator, as referees often value and trust the opinions and choices of their friends or contacts.
4. **Creating a Sense of Community and Belonging:** Personalized messages can give referees the feeling of being part of an exclusive group or community, especially when the message implies a gift or a special offer from someone they know. This sense of belonging can be a strong incentive to join and participate.
5. **Reducing Perceived Risk:** For new users, trying a new service involves some level of perceived risk or uncertainty. A personalized referral reduces this perceived risk, as it comes with an implicit endorsement from someone the referee trusts.
6. **Emotional Appeal:** Personalized messages can evoke an emotional response. Knowing that a friend or acquaintance has thoughtfully extended an offer can create feelings of appreciation and reciprocity, further encouraging the referee to sign up.
To add the referrer's name to an element on the page that the new user lands on when following an invite link, you need to follow these steps:
### Turn personalization on for your product
Go to [New User Experience setup in Cello Portal -> Personalization tab](https://portal.cello.so/setup/new-user-experience) and add personalization.
When personalization is turned on, an extra parameter will be added to the URL of your landing page, e.g. `celloN=VGFuamE`
```html
https://getmoonly.com/?productId=getmoonly.com&ucc=pNRB1aYqArN&celloN=VGFuamE
```
### Use parameter to get the name of the referrer
Value of parameter `celloN` is an base64 encoded name of the referrer. In this example, `VGFuamE` is decoded to `Tanya` . You can try it yourself [here](https://www.base64decode.org/). By accessing this parameter from the URL and decoding in, you can add it to any element on any landing pages which are relevant.
## Add personalization with the New user banner
No code
The banner with a personalized message is easily added in a few steps:
* Add [Cello attribution library](/sdk/client-side/attribution-lib) to your landing page.
* Go to [New User Experience setup in Cello Portal -> Personalization tab](https://portal.cello.so/setup/new-user-experience) and turn the banner on.
Visitors who follow the Cello invite link will have a banner displayed with a custom message containing an offer and the name of their referrer.
# Referral Notifications and Emails
Source: https://docs.cello.so/guides/user-experience/referral-notifications-and-emails
Cello provides notifications that are seamlessly integrated with your product experience to inform, activate and continuously engage users with the referral program
Cello provides notifications that are seamlessly integrated with your product experience to inform, activate and continuously engage users with the referral program. This page provides details on the notifications types and how to customize based on your needs.
## Notifications types and triggers
Notifications the we support fall into 2 categories: **in-product** announcement and alert and **external** like email. These notifications and their associated triggers are designed to work in conjunction your existing product engagement touch points in a seamless way.
### Alert and Badge
**Alert** is a notification that appears under Rewards tab. It is accompanied with a **badge**.
A **badge** is a small colored dot displayed on the launcher opening the widget (Cello button or [Custom Launcher](/referral-component/custom-launcher)) to draw attention to the activity with the referral program without being too distracting from your core product experience.
| Type | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| "New referrer activation" alert | Displayed after referrer has used the product more then 1 day after signs up to bring subtle attention to the referral program. |
| "Successful share" alert | Displayed every time referrer has a new link view. |
| "New reward" alert | Displayed every time the referrer receives a new signup or reward. |
### Announcement
Announcements are callout style message that appears anchored to the launcher, either Cello button or [Custom Launcher](/referral-component/custom-launcher). Announcements can be dismissed by clicking on them or their "X" dismiss button.
| Type | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| "New referrer activation" announcement | Sent 7 days after a ["New referrer activation" alert](#alert-and-badge) is sent and the user has not acted on it. |
| "New reward" announcement | Sent if the user has not entered their payment details after 7 days of receiving the first reward. |
### Email
Emails are a way to keep your users aware and engage with the referral program without them needing to log into the application. By default, Cello will send emails about the key events in the referral lifecycle.
## Activation campaign
In addition to the default notification journey, you can run **an activation campaign** with Cello to activate users for your referral program with recurring announcements.
**How it works:**
1. Activation campaign starts 30 days after ["New referrer activation" announcement](#announcement) is sent and the user has not acted on it.
2. The recurring announcements will be only send if the user full-fills a certain activity pattern in the product like:
* Referrer has used the app at least once after reading the last announcement.
* Last activation announcement was read.
* Referrer didn't share in the last 30 days.
## Notification settings
You can preview and configure which notifications you want Cello to send in your [Cello Portal](https://portal.cello.so/setup/notifications).
Cello distinguishes between **Essential** and **Engagement** notifications. Essential notifications are **always on** as they are required for the program to run successfully. You can choose to turn off Engagement notifications, however, they do give a significant performance improvement.
# Setup Overview
Source: https://docs.cello.so/integration-overview
Get started with Cello in 4 easy steps
## Setup Steps
If you did not find your integration guide, complete these steps to integrate Cello, regardless of your tech stack or payment gateway.
## Add a custom launcher
1. **Choose an element** in your app to launch Referral Component. It can be a button, a menu item, a link. Make sure your element has a unique identifier in your application DOM. It can be a **class ID**, **an attribute selector**, **an element ID**.
2. **Add the ID or class to the HTML element** where you want the Referral Component to open when clicked.
## Add reward in launcher
1.5x activation rate
3.5x sharing rate
Increase the sharing activity of your users by highlighting the reward directly in the referral launcher inside your menu item.
You can get the text for the menu launcher from [cello.js](/sdk/client-side/cello-js). Text will be localized to the [referrer's language](/guides/user-experience/overview#texts-and-language) and the reward amount is based on the [referrer's campaign](/guides/campaigns/setting-up-campaigns).
```javascript
const labels = await window.Cello("getLabels")
const myCustomLauncherLabel = labels.customLauncher
```
## Disable Cello button
**Cello button** is a floating action button or bookmark style button provided as a default Referral Component launcher. When integrating a Customer Launcher, you may choose to disable the Cello button or keep it as an additional launcher.
You can choose to disable the default launcher, the Cello button. Go to [Referrer experience](https://portal.cello.so/setup/referrer-experience) settings in Cello Portal and **uncheck** "Show Cello Button".
## Configure notification badge
You can control the behaviour of the [notification badge](/guides/user-experience/referral-notifications-and-emails#alert-and-badge), which is attached to your Custom Launcher Selector by default:
Announcement are callout style notifications used to [communicate important information](/guides/user-experience/referral-notifications-and-emails#announcement) to the user if we need to grab their attention and direct them to the Referral Component.
Here you can also configure where you want announcement to be shown relative to the Announcement Selector by specifying **Announcement position** and **Announcement position offset.**
## What is the Referral Component?
The Referral Component provides a complete referral experience within your product through:
* **First-time onboarding** that explains how your referral program works
* **Multiple sharing options** including link copy, social media, email, and QR codes
* **Progress tracking** showing clicks, signups, and earned rewards in real-time
* **Automated reward payouts** via PayPal, Venmo, and other payment methods
* **In-app and Email notifications** to keep users engaged with referral activity
Learn more about the [complete user experience](/guides/user-experience/overview).
## Key Features
* **Easy Integration** - Add as a floating button to launch the Referral Component or integrate into your existing menu with [custom launcher](/referral-component/custom-launcher)
* **Customizable Offer** - [Configure reward amounts, text, and program details](/guides/campaigns/setting-up-campaigns)
* **In-app Notifications** - [Alerts and announcements](/guides/user-experience/referral-notifications-and-emails) to keep users engaged with updates, promotions, and milestones
* **Email Notifications** - [Automated emails for signups, rewards, and milestones](/guides/user-experience/referral-notifications-and-emails)
* **Multi-language Support** - Available in 10+ languages with automatic detection
* **Cross-platform** - Native SDKs [for Web](/sdk/client-side/cello-js), [iOS, Android, and React Native](/sdk/mobile/introduction)
## Installation Options
## Installation Steps
Follow these steps to integrate the Referral Component:
1. Load the Cello script from our CDN
2. Generate a JWT token server-side for user authentication
3. Initialize the component with the token to connect your user session
## Step 1: Load the script
Add the Cello script to your HTML. The script loads asynchronously to avoid blocking page rendering and can be included anywhere on your website. This approach is recommended for optimal SEO performance.
## Available Mobile SDKs
Cello provides native mobile SDKs that embed a complete referral experience directly into your mobile applications, enabling users to share referral links, track rewards, and receive payouts—all without leaving your app.
#### Option 3: Install Cello manually
1. Download Cello for iOS and extract the zip. (👉 [**Cello iOS zip download**](https://github.com/getcello/cello-ios-sp/releases))
2. Drag `CelloSDK.xcframework` into your project. Make sure **Copy items if needed** is selected and click Finish.
3. In the target settings for your app, set the `CelloSDK.xcframework` to **Embed & Sign** in the **Frameworks, Libraries, and Embedded Content** section of the **General** tab.
### Choose an Environment
In your Cello SDK setup, you have the flexibility to select the environment in which your application will run. This feature is especially useful for different stages of development, such as testing in a development or staging environment before going live in production. The available environments are:
Available environments:
* `prod` (Production)
* `sandbox` (Sandbox)
*`Default environment: prod`*
#### Configuration Steps
* Open your iOS project in Xcode.
* Navigate to the `Info.plist` file.
* Add a new key-value pair:
```xml