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


# Get new user reward info
Source: https://docs.cello.so/api-reference/new-users/get-reward

GET /new-users/{productUserId}/reward
Retrieve details on eligibility for the new user reward (discount) and referral information.

## Common reasons for `eligible: false`

If the response is `{ "eligible": false }` even though the user has a `cello_ucc`, the most common causes are:

* **No active new-user reward on the campaign** - the campaign tied to the UCC has no new-user discount configured, or the reward is inactive/expired.
* **`productUserId` mismatch** - the `productUserId` you passed isn't the user who actually signed up through the referral.
* **Attribution arrived after the first invoice** - `cello_ucc` was added to the customer after the first `invoice.paid`; attribution can be retroactive, but reward eligibility is still evaluated against the reward rules.
* **Self-referral** - the new user signed up using their own UCC, or the signup was flagged as a [self-referral](/guides/fraud-detection) by Cello's fraud detection. Self-referrals are not eligible for new-user discounts.

To verify, compare `referralUcc`, `campaignId`, and `campaignRevision` from the response (when `eligible: true`) against what you expect, and check the [Review Referrals](https://portal.cello.so/manage/reviewreferrals) section in the portal for self-referral flags.


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



# Apply Discounts
Source: https://docs.cello.so/attribution/apply-discounts

Learn how to apply discounts to referred users when the purchase a subscription

## Implementation steps

Implementing automated discounts for referred users follows a consistent pattern across all subscription platforms. Here's the complete workflow:

<Steps>
  <Step title="Configure discounts in your subscription platform">
    Create discount coupons in your subscription platform (Stripe, Chargebee, Paddle, Recurly, etc.):

    **Platform Setup:**

    * Configure discounts at the plan/price level
    * Create multiple variations for different subscription plans:
      * Monthly plans: e.g., 25% off for 3 months
      * Annual plans: e.g., 50% off first year
    * Store provider coupon IDs in application configuration. You will need them later to apply the correct coupon at subscription time based on plan/price and referral status.

    <Note>
      Once you’ve set up discounts in your subscription platform, a potential next step would be to [display the discount information on your pricing or landing page](/guides/user-experience/new-user-discounts).
    </Note>
  </Step>

  <Step title="Subscription step: Check if new user is a Cello referral">
    During subscription creation, check if the new user is a Cello referral and discount needs to be assigned:

    * New ⭐: Use our [New User Reward API](/api-reference/new-users/get-reward) to validate the eligibility for a new user reward (discount)

    or

    * **Using Stripe or Chargebee only:** Check your Stripe/Chargebee Customer if a `cello_ucc` is present in the [**Customer Object**](https://apidocs.chargebee.com/docs/api/customers)**.**
    * **Using CelloAPI to track signups and Stripe/Chargebee to track purchases:** Check your Stripe/Chargebee customer if a `cello_ucc` is present in the [**Customer Object**](https://apidocs.chargebee.com/docs/api/customers)
    * **Cello API to track all conversion events:** Check if the new user with this id has a `cello_ucc` in your profile you stored during [signup tracking](/attribution/tracking-signups).
  </Step>

  <Step title="Subscription step: Apply discount">
    During subscription creation, pass the determined coupon code to your subscription platform:

    **Required Data for Subscription:**

    * Plan/Price information
    * Coupon/discount code

    **Platform-Specific Application:**

    * **Stripe**: Use `discounts` array or `coupon` parameter on Checkout Session
    * **Chargebee**: Apply `coupon_ids` on Subscription or via Hosted Pages (not at customer creation)
  </Step>
</Steps>

### Key Implementation Notes

* **Timing**: Discounts must be applied during initial subscription creation, not afterward
* **Validation**: Always verify the user is eligible for referral discounts
* **Fallback**: Handle cases where discount codes are invalid or expired
* **Configuration**: Maintain an application-level mapping of coupon IDs to plan type and referral status so the correct coupon can be applied at subscription time

## Stripe implementation

Stripe offers flexible discount mechanisms through **coupons**. For referral discounts, apply coupons during Subscription creation or Checkout. You cannot attach discounts at customer creation.

### Overview

There are two ways to apply coupons in Stripe, depending on your integration style:

* Server-side Subscription API (apply during `subscriptions.create`) - best for custom UIs. See [Stripe documentation](https://stripe.com/docs/billing/subscriptions/discounts).
* Prebuilt Checkout Session (apply during `checkout.sessions.create`) - best for hosted checkout. See [Stripe documentation](https://stripe.com/docs/payments/checkout/discounts).

Stripe's discount system works through:

* **Coupons**: Define the discount structure (percentage, duration, limits)
* **Application methods**: Apply coupons to Subscriptions or Checkout Sessions

<Steps>
  <Step title="Create referral coupons in Stripe">
    Set up discount coupons for your referral program:

    **Via Stripe Dashboard:**

    1. Go to [Stripe Dashboard > Coupons](https://dashboard.stripe.com/coupons)
    2. Click "Create coupon"
    3. Configure discount parameters:
       * **Name**: e.g., `Referral Discount - Monthly 25%`
       * **Type**: Percentage
       * **Percent off**: 25%
       * **Duration**: Repeating (3 months)
       * After creation, store the returned coupon ID in your config

    **Via Stripe API:**

    ```javascript theme={null}
    const stripe = require('stripe')('sk_live_...');

    const coupon = await stripe.coupons.create({
      name: 'Referral Discount - Monthly 25%',
      percent_off: 25,
      duration: 'repeating',
      duration_in_months: 3,
      metadata: {
        campaign_type: 'user-referrals',
        plan_type: 'monthly'
      }
    });
    // Save coupon.id to your configuration
    ```
  </Step>

  <Step title="Apply coupon during subscription creation">
    ```javascript theme={null}
    const subscription = await stripe.subscriptions.create({
      customer: user.customerId,
      items: [{
        price: 'price_monthly_plan'
      }],
      discounts: [{
        coupon: couponId
      }]
    });
    ```
  </Step>
</Steps>

### Handle checkout sessions with discounts

For Stripe Checkout, include discounts in session creation:

```javascript theme={null}
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{
    price: 'price_monthly_plan',
    quantity: 1
  }],
  customer: user.customerId,
  discounts: [{
    coupon: couponId
  }],
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel'
});
```

The Stripe UI automatically displays the discount during checkout:

<img alt="Stripe checkout with discount visualization" />

### Manual discount application (not recommended)

For testing or special cases, you can manually attach coupons on a Subscription in the Stripe Dashboard:

1. Navigate to the subscription in [Stripe Dashboard](https://dashboard.stripe.com/subscriptions)
2. Click **Update subscription** → **Add coupon**
3. Select the appropriate referral coupon

<img alt="Stripe Console apply coupon action" />

<Warning>
  Manual application is not scalable for automated referral programs. Use the API methods above for production implementations.
</Warning>

## Chargebee implementation

Chargebee uses **coupons** to apply discounts on subscriptions. For referral discounts, apply coupons during subscription creation or via Hosted Pages.

### Overview

There are two ways to apply coupons in Chargebee:

* Subscription API (apply during `subscription.create`) - for server-side subscription creation. See [Chargebee documentation](https://apidocs.chargebee.com/docs/api/subscriptions?prod_cat_ver=2#create_a_subscription).
* Hosted Pages (apply via `coupon_ids` during checkout) - for provider-hosted checkout. See [Chargebee documentation](https://apidocs.chargebee.com/docs/api/hosted_pages?prod_cat_ver=2#checkout_new_subscription).

Chargebee's discount system works through:

* **Coupons**: Define discount rules (percentage, amount, duration)
* **Application methods**: Apply to subscriptions or via Hosted Pages

<Steps>
  <Step title="Create referral coupons in Chargebee">
    Set up discount coupons for your referral program:

    **Via Chargebee Dashboard:**

    1. Go to [Chargebee Dashboard > Coupons](https://www.chargebee.com/docs/2.0/coupons.html#creating-coupons)
    2. Click "Create Coupon"
    3. Configure discount parameters:
       * **Coupon Name**: e.g., `Referral Discount - Monthly 25%`
       * **Discount Type**: Percentage
       * **Discount**: 25%
       * **Duration Type**: Limited Period (3 months)
       * After creation, store the coupon ID in your config

    **Via Chargebee API:**

    ```javascript theme={null}
    const chargebee = require('chargebee');
    chargebee.configure({
      site: 'your-site',
      api_key: 'your-api-key'
    });

    const coupon = await chargebee.coupon.create({
      id: 'YOUR_COUPON_ID',
      name: 'Referral Discount - Monthly 25%',
      discount_type: 'percentage',
      discount_percentage: 25,
      duration_type: 'limited_period',
      period: 3,
      period_unit: 'month'
    });
    ```
  </Step>

  <Step title="Apply coupons during subscription creation">
    ```javascript theme={null}
    const subscription = await chargebee.subscription.create({
      customer_id: user.id,
      plan_id: 'monthly_plan',
      coupon_ids: [couponId]
    });
    ```
  </Step>
</Steps>

### Handle Hosted Pages with discounts

For Chargebee Hosted Pages, include coupons in checkout URLs:

```javascript theme={null}
const hostedPage = await chargebee.hosted_page.checkout_new({
  subscription: {
    plan_id: 'monthly_plan',
    coupon_ids: [couponId]
  },
  customer: {
    id: user.id,
    email: user.email
  }
});

// Redirect user to hostedPage.url
```

## Cello API integration (for other platforms)

If you use another billing platform (for example, Paddle, Recurly, Braintree) or a home-grown system, follow the same general approach described above:

1. Create and manage coupons/discounts in your billing system.
2. Keep an application-level mapping of coupon IDs by plan and referral status.
3. Apply the correct coupon at subscription/checkout creation time.


# 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/).

<Note>
  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.
</Note>

## 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 theme={null}
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 theme={null}
https://yourbrand.app.link/abc123?referral_ucc=A1B2C
↓
Branch.io captures and stores:
- referral_ucc: A1B2C
- Device fingerprint
- Click timestamp
```

#### App Installation

```html theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
// 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 theme={null}
// 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<String, String>().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 theme={null}
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:

<CardGroup>
  <Card title="Embedded Script Tag" icon="code" href="/sdk/client-side/embedded-script-tag" />

  <Card title="Google Tag Manager" icon="google" href="/sdk/client-side/google-tag-manager" />
</CardGroup>

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 theme={null}
   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 theme={null}
   window.CelloAttribution('getUcc')
   ```

   Expected response:

   ```javascript theme={null}
   Promise {<fulfilled>: 'test'}
   ```

If this test passes, the script is installed correctly.

<Tip>
  **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).
</Tip>


# 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:

<img alt="Cello Attribution Capture UCC HubSpot deal with Hubspot Form" />

## Step 2: Include the Cello Attribution Library

Add the Cello attribution script to your website's `<head>` section or before the closing `</body>` tag:

```html theme={null}
<script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>
```

## 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 theme={null}
<script>
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
}
</script>
```

<Warning>
  **Important:** This script must be added before any calls to `window.CelloAttribution()` to prevent race conditions.
</Warning>

## 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 theme={null}
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 theme={null}
   // Test if ucc is available
   window.CelloAttribution('getUcc')
   ```

   Expected response: `Promise {<fulfilled>: '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

<img alt="Cello Attribution Capture UCC HubSpot deal with Hubspot Form" />

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.

<img alt="Cello Attribution Capture UCC HubSpot deal with Hubspot Form" />

## 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:

<img alt="Cello Attribution Capture UCC HubSpot deal with Hubspot Form" />

### 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 theme={null}
<!-- On the page containing your scheduling page -->
<script>
// Same attribution command queue as above
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
}

// Wait for scheduling page to load, then populate `ucc`
document.addEventListener('DOMContentLoaded', function() {
    // Use MutationObserver to detect when scheduling form is loaded
    const observer = new MutationObserver(function(mutations) {
        mutations.forEach(function(mutation) {
            if (mutation.type === 'childList') {
                const uccField = document.querySelector('input[name="ucc"]');
                if (uccField && !uccField.value) {
                    window.CelloAttribution('getUcc').then((celloUcc) => {
                        if (celloUcc) {
                            uccField.value = celloUcc;
                            console.log('ucc populated in scheduling form:', celloUcc);
                        }
                    }).catch((error) => {
                        console.log('No referral code available:', error);
                    });
                }
            }
        });
    });
    
    // Start observing
    observer.observe(document.body, {
        childList: true,
        subtree: true
    });
});
</script>
```

### 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

<Tip>
  **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.
</Tip>


# 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:

<img alt="Cello Referral conversion process four-step attribution flow overview diagram" />

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

<Tip>
  Accurate referral conversion tracking depends on properly passing the referral code `ucc` through each step of the referral journey.
</Tip>

<Warning>
  **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`
</Warning>

# Getting started with referral conversion tracking

Learn how to track conversions with Cello in the following resources:

<CardGroup>
  <Card title="Web signup flow" icon="browser" href="/attribution/for-web">
    Capture referral code during web signup flow
  </Card>

  <Card title="Mobile signup flow" icon="mobile" href="/attribution/for-mobile">
    Capture referral code during mobile signup
  </Card>

  <Card title="Track signups" icon="user-plus" href="/sdk/client-side/embedded-script-tag">
    A full guide on tracking signup events
  </Card>

  <Card title="Track purchases" icon="credit-card" href="/sdk/client-side/embedded-script-tag">
    A full guide on tracking purchase events
  </Card>
</CardGroup>

or choose a step-by-step quickstart guide for your integration scenario:

<CardGroup>
  <Card title="Stripe Webhook Quickstart" icon="book-open" href="/attribution/use-cases/stripe" />

  <Card title="Chargebee Webhook Quickstart" icon="book-open" href="/attribution/use-cases/chargebee" />
</CardGroup>


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

<Tip>
  After sending purchase events, check [Integration Status](/guides/support/portal/integration-status) to confirm Purchases tracking is **Connected**. For per-event detail and to troubleshoot any field validation errors, open the [Event Feed](https://portal.cello.so/integrations/events-feed) in the Cello Portal.
</Tip>

# 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)

<Warning>
  **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`
</Warning>

<Note>
  If you are providing discounts to new users, they need to be [applied at the point of creating a subscription](/attribution/apply-discounts) in your subscription platform
</Note>

# Track purchase events with Webhooks

Depending on which payment gateway you’re using, we offer webhooks for the following:

<CardGroup>
  <Card
    title="Stripe Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clipPath="url(https://mintlify.s3.us-west-1.amazonaws.com/cello/attribution#clip0_19722_44991)">
<path d="M18 36C27.9411 36 36 27.9411 36 18C36 8.05888 27.9411 0 18 0C8.05888 0 0 8.05888 0 18C0 27.9411 8.05888 36 18 36Z" fill="#635BFF"/>
<path fillRule="evenodd" clipRule="evenodd" d="M16.596 13.995C16.596 13.149 17.289 12.816 18.441 12.816C20.097 12.816 22.185 13.32 23.841 14.211V9.09898C22.032 8.37898 20.25 8.09998 18.45 8.09998C14.031 8.09998 11.097 10.404 11.097 14.256C11.097 20.259 19.368 19.305 19.368 21.897C19.368 22.896 18.495 23.22 17.28 23.22C15.471 23.22 13.167 22.482 11.34 21.483V26.658C13.365 27.531 15.408 27.9 17.28 27.9C21.807 27.9 24.921 25.659 24.921 21.762C24.885 15.282 16.596 16.434 16.596 13.995Z" fill="white"/>
</g>
<defs>
<clipPath id="clip0_19722_44991">
<rect width="36" height="36" fill="white"/>
</clipPath>
</defs>
</svg>}
    href="/integrations/webhooks/stripe-webhook"
  >
    Send events using Stripe Webhook
  </Card>

  <Card
    title="Chargebee Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12.1464 18.0024L35.9265 12.3313V0H23.5953L12.1464 18.0024Z" fill="#FF3300"/>
<path d="M0.36 17.7853C0.36 19.2605 0.539827 20.6924 0.879691 22.0664L12.1451 18.0017L0.786251 13.9024C0.509734 15.1512 0.36 16.4499 0.36 17.7819V17.7853Z" fill="#FF3300"/>
<path d="M4.54902 6.32317L12.1436 18.0031L15.6415 0.177188C11.2091 0.799913 7.3026 3.05771 4.54902 6.32317V6.32317Z" fill="#FF3300"/>
<path d="M12.1464 18.0008L35.9265 23.6686V35.9998H23.5953L12.1464 18.0008Z" fill="#FF3300"/>
<path d="M4.54902 29.6798L12.1436 17.9978L15.6415 35.8204C11.2091 35.1977 7.3026 32.9399 4.54902 29.6744L4.54902 29.6798Z" fill="#FF3300"/>
</svg>}
    href="/integrations/webhooks/chargebee-webhook"
  >
    Send events using Chargebee Webhook
  </Card>
</CardGroup>

# 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 theme={null}
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`, `weekly`, `bi-weekly`, `monthly`, `quarterly`, `semi-annual`, `yearly`, `biennial`, `triennial`, `lifetime`                                                                                             |
| `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. When Cello receives this event, it automatically cancels any pending reward for that transaction.

```bash theme={null}
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).

<Tip>
  After sending signup events, check [Integration Status](/guides/support/portal/integration-status) to confirm Signups tracking is **Connected**. For per-event detail and to troubleshoot any field validation errors, open the [Event Feed](https://portal.cello.so/integrations/events-feed) in the Cello Portal.
</Tip>

# 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

<Warning>
  **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`
</Warning>

# 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

<Tip>
  Use this option if your payment gateway is Stripe and you **create a Stripe customer at signup**
</Tip>

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 theme={null}
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
			}
});
```

<Check>
  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.
</Check>

## Option 2: Using Chargebee - I create Chargebee customer at signup

<Tip>
  Use this option if your payment gateway is Chargebee and you **create a Chargebee customer at signup**
</Tip>

You can pass the following metadata to Chargebee on customer creation.

<Note>
  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)
</Note>

* `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 theme={null}
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
			}
//   ..
// })
```

<Check>
  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.
</Check>

## Option 3: Using Cello API POST /events API endpoint

<Tip>
  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
</Tip>

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**.
* `newUser.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
* `newUser.email` - new user email
* `newUser.name` - new user name
* `newUser.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 theme={null}
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": {
		"newUser": {
			"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

<Tip>
  Use this option if your product follows a sales-led model where successful conversions are driven by users attending a demo call.
</Tip>

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**.
* `newUser.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
* `newUser.email` - new user email
* `newUser.name` - new user name
* `newUser.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 theme={null}
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

<Steps>
  <Step title="Create a new form">
    Create a new form in Typeform
  </Step>

  <Step title="Add Hidden Fields">
    On the initial question in your form, go to **Hidden Fields** via **Logic → Hidden Fields** on the panel on the right
  </Step>

  <Step title="Add ucc field">
    Add a new field named `ucc` and click Save
  </Step>
</Steps>

<img alt="Cello Capture UCC Typeform hidden fields setup" />

## Setup of Sync from Typeform to HubSpot

<Steps>
  <Step title="Connect HubSpot">
    Navigate to the **Connect** Section in the header of Typeform and connect HubSpot
  </Step>

  <Step title="Select HubSpot object">
    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.

    <Note>
      You can also sync the `ucc` to multiple objects at the same time: contact, company and deals.
    </Note>
  </Step>

  <Step title="Configure pipeline">
    If you sync the `ucc` to a deal, you have to specify in which pipeline at which stage the deals should be created
  </Step>

  <Step title="Save and test">
    After finalizing the setup of the integration, save the settings and run a short test run
  </Step>
</Steps>

<img alt="Cello Capture UCC Typeform HubSpot integration setup" />

## Test the created Typeform and HubSpot integration

<Steps>
  <Step title="Open Typeform">
    Open the created Typeform
  </Step>

  <Step title="Add ucc parameter">
    Add either `?ucc=12341234` or `&ucc=12341234` to the link depending on if there is already a "?" present in the link

    <img alt="Cello Capture UCC Typeform URL with UCC parameter" />
  </Step>

  <Step title="Submit form">
    Submit the Typeform
  </Step>

  <Step title="Verify in HubSpot">
    Open HubSpot and check that the contact, company or deal was created and the `ucc` was synced correctly

    <img alt="Cello Capture UCC Typeform HubSpot deal with UCC" />
  </Step>
</Steps>

## Further hints

<Tip>
  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/).
</Tip>


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

<Tip>
  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
</Tip>

# Step 1: Integrate the Referral Component

First, integrate Cello Referral Component into your web app to provide referrers with full referral experience.

Referral Component is integrated using one of our SDKs. For your web app, use Cello JS - our client-side SDK. You can install it by:

1. Adding a script tag to the `<head>` of your application
2. Generating a JWT token for user authentication
3. Booting the component with the provided token and user details

Follow this installation guide:

<CardGroup>
  <Card title="Referral Component Quickstart" icon="js" href="https://docs.cello.so/referral-component/quickstart" />
</CardGroup>

You can also integrate Referral Component into your mobile applications:

<CardGroup>
  <Card title="iOS SDK" icon="apple" href="https://docs.cello.so/sdk/mobile/ios" />

  <Card title="Android SDK" icon="android" href="https://docs.cello.so/sdk/mobile/android" />

  <Card title="React Native SDK" icon="react" href="https://docs.cello.so/sdk/mobile/react-native" />
</CardGroup>

# 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:

   <CardGroup>
     <Card title="Embedded Script Tag" icon="code" href="https://docs.cello.so/sdk/client-side/embedded-script-tag" />

     <Card title="Google Tag Manager" icon="google" href="https://docs.cello.so/sdk/client-side/google-tag-manager" />
   </CardGroup>
3. Verify the installation

   <Check>
     To verify, follow these steps:

     1. Add `?productId=test` and `?ucc=test` to your website URL

        ```html theme={null}
         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 theme={null}
        window.CelloAttribution('getUcc')
        ```

        This method should return a promise with value `test`

        ```javascript theme={null}
        Promise {<fulfilled>: 'test'}
        ```

     **If this check passes, the script is installed correctly.**
   </Check>

For capturing referral code in your mobile signup flow, follow this guide:

<CardGroup>
  <Card title="Mobile signup flow" icon="mobile" href="https://docs.cello.so/attribution/for-mobile" />
</CardGroup>

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

<Note>
  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)
</Note>

* `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 theme={null}
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"
			}
//   ..
// })
```

<Check>
  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.
</Check>

# 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:

<CardGroup>
  <Card
    title="Chargebee Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12.1464 18.0024L35.9265 12.3313V0H23.5953L12.1464 18.0024Z" fill="#FF3300"/>
<path d="M0.36 17.7853C0.36 19.2605 0.539827 20.6924 0.879691 22.0664L12.1451 18.0017L0.786251 13.9024C0.509734 15.1512 0.36 16.4499 0.36 17.7819V17.7853Z" fill="#FF3300"/>
<path d="M4.54902 6.32317L12.1436 18.0031L15.6415 0.177188C11.2091 0.799913 7.3026 3.05771 4.54902 6.32317V6.32317Z" fill="#FF3300"/>
<path d="M12.1464 18.0008L35.9265 23.6686V35.9998H23.5953L12.1464 18.0008Z" fill="#FF3300"/>
<path d="M4.54902 29.6798L12.1436 17.9978L15.6415 35.8204C11.2091 35.1977 7.3026 32.9399 4.54902 29.6744L4.54902 29.6798Z" fill="#FF3300"/>
</svg>}
    href="/integrations/webhooks/chargebee-webhook"
  >
    Send events using Chargebee Webhook
  </Card>
</CardGroup>

<Check>
  **Congratulations!** You are done and now able to try out the full Cello referral experience 🎉
</Check>


# HubSpot + Zapier Quickstart
Source: https://docs.cello.so/attribution/use-cases/hubspot-zapier

Learn how to send Cello signup events from HubSpot deal stage changes using a no-code Zapier workflow.

<Tip>
  This guide is **optimized for sales-led products** where conversions are driven by demos, sales calls, or other manual qualification steps tracked in HubSpot.

  Use this guide if you:

  * Use **HubSpot** as your source of truth for deals
  * Want to send Cello signup events (e.g. `demo-call-attended`) **without writing any backend code**
  * Trigger events based on **HubSpot deal stage changes** (e.g. "Demo Done", "Qualified", "Purchase Consideration")
</Tip>

# Overview

This guide walks you through building a no-code Zapier workflow that:

1. **Watches HubSpot** for deals moving into a specific stage (e.g. "Demo Done")
2. **Filters** deals to only those with a captured `ucc` referral code
3. **Authenticates** with the Cello API to obtain an access token
4. **Sends a signup event** to Cello using the `POST /events` endpoint

By the end, every qualified deal in HubSpot will automatically generate a Cello conversion event — letting you reward referrers as soon as their referee attends a demo or hits any milestone in your sales pipeline.

# Prerequisites

Before you start, make sure you have:

* A **HubSpot account** with deals flowing through your sales pipeline
* A **Zapier account** (Starter plan or above — Code by Zapier steps require a paid plan)
* A **Cello account** with API credentials (`accessKeyId` and `secretAccessKey`) — generate these in the [Cello Portal](https://portal.cello.so)
* A **`ucc` property** on your HubSpot deal or company object, populated when the referral lands. Follow the [HubSpot Forms attribution guide](/attribution/hubspot) to set this up.
* [Cello JS Referral Component](/referral-component/quickstart) integrated in your product so referrers can share referral links

<Warning>
  If `ucc` is not being captured on your HubSpot deals, the Zap will skip every event. Complete the [HubSpot Forms attribution setup](/attribution/hubspot) first and verify with a test referral before continuing.
</Warning>

# The completed Zap

Your finished Zap will have four steps:

<img alt="HubSpot + Zapier flow with four steps: retrieve deal info, filter on ucc, create access token, send signup event" />

# Step 1: Trigger on HubSpot deal stage change

The Zap fires whenever a deal enters the stage you choose (typically the one that represents a qualified conversion — "Demo Done", "Purchase Consideration", or similar).

1. In Zapier, create a new Zap and choose **HubSpot** as the trigger app.
2. Pick the event **"Deal in stage"** (or "Deal Property Changed" depending on your HubSpot plan).
3. Select your **Deal Pipeline** and the **Deal Stage** that should trigger the event (e.g. `Demo Done/Purchase Consideration`).
4. Under **Additional properties to retrieve**, add the `ucc` property so it's available in later steps.

<img alt="HubSpot trigger configured with pipeline, deal stage, and ucc as an additional property" />

<Note>
  The HubSpot trigger checks for matching deals every 15 minutes and only picks up deals moved into the stage in the **last 30 minutes**. Plan your stage transitions accordingly.
</Note>

Test the trigger and confirm Zapier returns a sample deal with the expected fields: `dealname`, `hs_object_id`, `ucc`, plus any contact/company info you want to forward.

# Step 2: Filter deals without a `ucc`

You only want to send events for deals that came from a referral. Add a **Filter by Zapier** step:

1. Choose **Filter by Zapier**.
2. Set the rule to: `1. Deal information: ucc` **Exists**.

<img alt="Zapier filter step: only continue if deal property ucc exists" />

Deals without a `ucc` will stop here and no Cello event will be sent.

# Step 3: Create a Cello access token

Cello uses short-lived access tokens for API auth. Add a **Code by Zapier** step using Python:

1. Choose **Code by Zapier** → **Run Python**.
2. Leave **Input Data** empty (credentials are hardcoded in this step).
3. Paste the snippet below and replace `<accessKeyId>` and `<secretAccessKey>` with your Cello API credentials.

```python theme={null}
import json
import urllib.request

ACCESS_KEY_ID = "<accessKeyId>"
SECRET_ACCESS_KEY = "<secretAccessKey>"

body = {
    "accessKeyId": ACCESS_KEY_ID,
    "secretAccessKey": SECRET_ACCESS_KEY
}

req = urllib.request.Request(
    url="https://api.cello.so/token",
    data=json.dumps(body).encode("utf-8"),
    method="POST",
    headers={"Content-Type": "application/json"}
)

try:
    with urllib.request.urlopen(req, timeout=10) as resp:
        data = json.loads(resp.read().decode("utf-8"))
    output = {
        "access_token": data.get("accessToken"),
        "expires_in": data.get("expiresIn"),
        "status": resp.status
    }
except urllib.error.HTTPError as e:
    output = {
        "access_token": "",
        "status": e.code,
        "error": e.read().decode("utf-8")
    }
```

<img alt="Code by Zapier step creating a Cello access token via POST /token" />

Test the step — you should see an `access_token` value and `status: 200` in the output.

<Tip>
  For production, store your `accessKeyId` and `secretAccessKey` in Zapier's **Storage by Zapier** or as **Code by Zapier environment variables** rather than hardcoding them. See [Zapier's guide on storing credentials](https://help.zapier.com/hc/en-us/articles/8496300064525) for details.
</Tip>

Reference: [Cello Authentication API](/api-reference/authentication/get-token).

# Step 4: Send the signup event to Cello

Add a second **Code by Zapier (Python)** step that posts the event to `POST /events`.

1. Choose **Code by Zapier** → **Run Python**.

2. Map the following **Input Data** fields from the previous steps:

   | Input Data key | Map from                                                                      |
   | -------------- | ----------------------------------------------------------------------------- |
   | `access_token` | Step 3 → `Access Token`                                                       |
   | `ucc`          | Step 1 → `Deal information: ucc`                                              |
   | `user_id`      | Step 1 → `Deal information: Record ID` (or your own product user ID property) |
   | `email`        | Step 1 → `Deal information: email_of_demo_request` (or contact email)         |
   | `name`         | Step 1 → `Deal information: Deal Name` (or contact name)                      |
   | `org_id`       | Step 1 → company / organization ID (optional)                                 |

3. Paste the snippet below:

```python theme={null}
import json
import urllib.request
from datetime import datetime, timezone

access_token = input_data.get("access_token", "")
ucc = input_data.get("ucc", "")
user_id = input_data.get("user_id", "")
email = input_data.get("email", "")
name = input_data.get("name", "")
org_id = input_data.get("org_id", "")

timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")

body = {
    "eventName": "ReferralUpdated",
    "payload": {
        "ucc": ucc,
        "newUserId": user_id
    },
    "context": {
        "newUser": {
            "id": user_id,
            "email": email,
            "name": name,
            "organizationId": org_id
        },
        "event": {
            "trigger": "demo-call-attended",
            "timestamp": timestamp
        }
    }
}

req = urllib.request.Request(
    url="https://api.cello.so/events",
    data=json.dumps(body).encode("utf-8"),
    method="POST",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {access_token}"
    }
)

try:
    with urllib.request.urlopen(req, timeout=10) as resp:
        response_body = resp.read().decode("utf-8")
        output = {"status": resp.status, "response": response_body}
except urllib.error.HTTPError as e:
    output = {"status": e.code, "response": e.read().decode("utf-8")}
```

<img alt="Code by Zapier step sending a demo-call-attended event to Cello with mapped HubSpot fields" />

<Note>
  The `event.trigger` value (`demo-call-attended` in this example) determines how Cello classifies the event. Common values:

  * `new-signup` — user signed up but no demo yet
  * `demo-call-attended` — user attended a sales/demo call
  * `qualified-lead` — user has been qualified by sales

  Match the trigger to the HubSpot deal stage you're firing from.
</Note>

Test the step and confirm you receive `status: 200` from Cello.

# Step 5: Verify and publish

1. **Publish your Zap.**
2. Move a test deal into the trigger stage in HubSpot.
3. Wait up to 15 minutes for Zapier to pick up the change.
4. Open the [Event Feed](https://portal.cello.so/integrations/events-feed) in the Cello Portal and confirm the event was received with the correct `ucc`, `newUserId`, and `trigger`.
5. Check [Integration Status](/guides/support/portal/integration-status) — **Signups** should now show as **Connected**.

<Check>
  **You're done!** Every qualified deal in HubSpot will now generate a Cello signup event automatically. To also track purchase events, pair this with the [Stripe](/attribution/use-cases/stripe) or [Chargebee](/attribution/use-cases/chargebee) webhook integrations — or extend this Zap with an additional Code step that posts a `purchase` event when the deal closes won.
</Check>

# Variations

* **Different trigger stages.** Duplicate the Zap and change the HubSpot deal stage + `event.trigger` value to track multiple milestones (e.g. one Zap for `demo-call-attended`, another for `qualified-lead`).
* **Reward at the organization level.** Set `newUserId` to the HubSpot company ID instead of the deal/contact ID, and populate `newUser.organizationId` accordingly. See [Tracking Signups](/attribution/tracking-signups) for the organization-level attribution model.
* **Use the Zapier HTTP action instead of Code steps.** If you prefer not to write Python, both API calls can be done with **Webhooks by Zapier → POST**. The body and headers are the same as in the snippets above.


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

<Tip>
  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
</Tip>

# Step 1: Integrate the Referral Component

First, integrate Cello Referral Component into your web app to provide referrers with full referral experience.

Referral Component is integrated using one of our SDKs. For your web app, use Cello JS - our client-side SDK. You can install it by:

1. Adding a script tag to the `<head>` of your application
2. Generating a JWT token for user authentication
3. Booting the component with the provided token and user details

Follow this installation guide:

<CardGroup>
  <Card title="Referral Component Quickstart" icon="js" href="https://docs.cello.so/referral-component/quickstart" />
</CardGroup>

You can also integrate Referral Component into your mobile applications:

<CardGroup>
  <Card title="iOS SDK" icon="apple" href="https://docs.cello.so/sdk/mobile/ios" />

  <Card title="Android SDK" icon="android" href="https://docs.cello.so/sdk/mobile/android" />

  <Card title="React Native SDK" icon="react" href="https://docs.cello.so/sdk/mobile/react-native" />
</CardGroup>

# 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:

   <CardGroup>
     <Card title="Embedded Script Tag" icon="code" href="https://docs.cello.so/sdk/client-side/embedded-script-tag" />

     <Card title="Google Tag Manager" icon="google" href="https://docs.cello.so/sdk/client-side/google-tag-manager" />
   </CardGroup>
3. Verify the installation

   <Check>
     To verify, follow these steps:

     1. Add `?productId=test` and `?ucc=test` to your website URL

        ```html theme={null}
         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 theme={null}
        window.CelloAttribution('getUcc')
        ```

        This method should return a promise with value `test`

        ```javascript theme={null}
        Promise {<fulfilled>: 'test'}
        ```

     **If this check passes, the script is installed correctly.**
   </Check>

For capturing referral code in your mobile signup flow, follow this guide:

<CardGroup>
  <Card title="Mobile signup flow" icon="mobile" href="https://docs.cello.so/attribution/for-mobile" />
</CardGroup>

# 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 theme={null}
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
			}
});
```

<Check>
  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.
</Check>

# 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:

<CardGroup>
  <Card
    title="Stripe Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clipPath="url(https://mintlify.s3.us-west-1.amazonaws.com/cello/attribution/use-cases#clip0_19722_44991)">
<path d="M18 36C27.9411 36 36 27.9411 36 18C36 8.05888 27.9411 0 18 0C8.05888 0 0 8.05888 0 18C0 27.9411 8.05888 36 18 36Z" fill="#635BFF"/>
<path fillRule="evenodd" clipRule="evenodd" d="M16.596 13.995C16.596 13.149 17.289 12.816 18.441 12.816C20.097 12.816 22.185 13.32 23.841 14.211V9.09898C22.032 8.37898 20.25 8.09998 18.45 8.09998C14.031 8.09998 11.097 10.404 11.097 14.256C11.097 20.259 19.368 19.305 19.368 21.897C19.368 22.896 18.495 23.22 17.28 23.22C15.471 23.22 13.167 22.482 11.34 21.483V26.658C13.365 27.531 15.408 27.9 17.28 27.9C21.807 27.9 24.921 25.659 24.921 21.762C24.885 15.282 16.596 16.434 16.596 13.995Z" fill="white"/>
</g>
<defs>
<clipPath id="clip0_19722_44991">
<rect width="36" height="36" fill="white"/>
</clipPath>
</defs>
</svg>}
    href="https://docs.cello.so/integrations/webhooks/stripe-webhook"
  >
    Send events using Stripe Webhook
  </Card>
</CardGroup>

<Check>
  **Congratulations!** You are done and now able to try out the full Cello referral experience 🎉
</Check>


# Cello + Claude integration
Source: https://docs.cello.so/coding-apps/claude-integration

How to add user referrals to your app using Cello with Claude

Claude can implement Cello user referrals end-to-end if you give it the **right guide** and force it to create a plan before coding. Use **Claude Code** (the CLI coding agent) to build the integration, and connect the Cello MCP so Claude can look up docs and verify your setup as it goes.

<Note>
  This page covers using **Claude Code** to build your referral integration. To connect the **Claude desktop or web app** so you can chat about your program, see the [Claude](/mcp/connect#claude) section of the MCP connect guide.
</Note>

<img alt="Cello + Claude integration" />

## Prerequisites

Before integrating Cello, ensure the following prerequisites are met:

* User signup and authentication is functional
* Stripe subscription flow is functional
* You have a Cello account and API keys at hand.

<Note>
  Make sure to use Cello **Sandbox environment** when developing and testing
</Note>

## Optional: Connect the Cello MCP

The [Cello MCP server](/mcp/introduction) gives Claude direct access to Cello's documentation, integration health checks, and best-practice recommendations. Connecting it before you start means Claude can look up the right docs itself, verify your setup as it goes, and follow best practices automatically - instead of relying only on the guide link you paste.

This step is optional but recommended. The integration steps below work either way. See [Connect your client → Claude Code](/mcp/connect#claude-code) for the setup steps.

## Cello user referrals integration

<Note>
  For a step-by-step technical implementation (source of truth + acceptance criteria), follow the detailed guide:

  * [React + Node.js Integration Guide](/resources/react-nodejs-integration)

  The guide uses React + Node.js as an example, but it can be any other combination - the steps stay the same.
</Note>

<Steps>
  <Step title="Prep your project">
    * Signup and authentication flow is functional
    * Stripe subscription flow is functional
    * Cello API keys are handy
  </Step>

  <Step title="Add Cello Webhook Endpoint to Stripe">
    * Get your webhook URL from [Cello Portal](https://portal.cello.so/integrations/webhooks)
    * Add a Webhook endpoint in Stripe (Log into your Stripe Dashboard -> Go to Developer Mode -> Add a Webhook endpoint and enter endpoint URL -> Select the events to send -> Click "Add endpoint")
    * Secure the Webhook with "Signing secret"

    Events to send:

    * `charge.refunded`, `charge.succeeded`, `charge.updated`
    * `customer.created`, `customer.deleted`, `customer.updated`
    * `customer.subscription.created`, `customer.subscription.deleted`, `customer.subscription.updated`
    * `invoice.paid`

    See [Stripe Webhook Integration](/integrations/webhooks/stripe-webhook#steps) for more details.
  </Step>

  <Step title="Prompt Claude Code to add User Referrals to your app">
    Ask Claude Code to create a plan first - it stays in **plan mode** until you approve. Paste this prompt:

    <Tabs>
      <Tab title="With Cello MCP connected">
        ```text theme={null}
        I want to add user referrals to my app using Cello.

        Use the Cello MCP to search the integration documentation, check my current integration status, and create a thorough implementation plan. Follow all best-practice recommendations from Cello.
        ```

        Claude will pull the relevant guides, check what's already set up, and tailor the plan to your project.
      </Tab>

      <Tab title="Without MCP">
        ```text theme={null}
        I now want to add user referrals. I chose platform Cello for this.

        I added a Cello integration guide according to which you should do the implementation. parsed the documentation more carefully from the start rather than assuming standard patterns would work. create a thorough implementation plan based on guidance, patterns and AC from the provided guide. Don't skip any content, it is all relevant

        Guide: https://docs.cello.so/resources/react-nodejs-integration
        ```
      </Tab>
    </Tabs>

    Claude asks you guiding questions and creates an implementation plan based on your answers.
  </Step>

  <Step title="Confirm executing the plan">
    Review the plan carefully. It should cover:

    * Cello JS SDK initialization and user authentication
    * Referral component placement and configuration
    * Attribution setup for tracking referred signups
    * Stripe webhook integration for conversion tracking

    If it looks correct, tell Claude to proceed and start implementing it.
  </Step>

  <Step title="Run & Test">
    Run your app and test the end-to-end flow. If everything was implemented correctly, you should see events coming in to [Cello Dashboard](https://portal.cello.so/dashboard/referrer).

    <Tip>
      If you have the Cello MCP connected, ask Claude to run a health check after deploying:

      *"Use Cello to check my integration status and confirm all four components are connected."*
    </Tip>
  </Step>
</Steps>

## After you're live

If you have the Cello MCP connected, it continues to be useful after the initial integration:

| Prompt                                           | What happens                                                                             |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| *"Is my Cello integration working?"*             | Checks all four integration components and reports which are connected or broken         |
| *"Why aren't referral rewards being triggered?"* | Inspects recent events to find missing or malformed fields preventing attribution        |
| *"How can I improve my referral program?"*       | Returns a prioritized list of recommendations across activation, sharing, and conversion |
| *"How do I set up a custom referral launcher?"*  | Searches the docs for custom launcher implementation guides                              |


# Cello + Cursor integration
Source: https://docs.cello.so/coding-apps/cursor-integration

How to add user referrals to your app using Cello with Cursor

Cursor can implement Cello user referrals end-to-end if you give it the **right guide** and force it to create a plan before coding.

<img alt="Cello + Cursor integration" />

<Accordion title="Watch the walkthrough">
  <iframe title="Cello + Cursor integration walkthrough" />
</Accordion>

## Prerequisites

Before integrating Cello, ensure the following prerequisites are met:

* User signup and authentication is functional
* Stripe subscription flow is functional
* You have a Cello account and API keys at hand.

<Note>
  Make sure to use Cello **Sandbox environment** when developing and testing
</Note>

## Optional: Connect the Cello MCP

The [Cello MCP server](/mcp/introduction) gives Cursor direct access to Cello's documentation, integration health checks, and best-practice recommendations. Connecting it before you start means Cursor can look up the right docs itself, verify your setup as it goes, and follow best practices automatically - instead of relying only on the guide link you paste.

This step is optional but recommended. The integration steps below work either way. See [Connect your client → Cursor](/mcp/connect#cursor) for the setup steps.

## Cello user referrals integration

<Note>
  For a step-by-step technical implementation (source of truth + acceptance criteria), follow the detailed guide:

  * [React + Node.js Integration Guide](/resources/react-nodejs-integration)

  The guide uses React + Node.js as an example, but it can be any other combination - the steps stay the same.
</Note>

<Steps>
  <Step title="Prep your project">
    * Signup and authentication flow is functional
    * Stripe subscription flow is functional
    * Cello API keys are handy
  </Step>

  <Step title="Add Cello Webhook Endpoint to Stripe">
    * Get your webhook URL from [Cello Portal](https://portal.cello.so/integrations/webhooks)
    * Add a Webhook endpoint in Stripe (Log into your Stripe Dashboard -> Go to Developer Mode -> Add a Webhook endpoint and enter endpoint URL -> Select the events to send -> Click "Add endpoint")
    * Secure the Webhook with "Signing secret"

    Events to send:

    * `charge.refunded`, `charge.succeeded`, `charge.updated`
    * `customer.created`, `customer.deleted`, `customer.updated`
    * `customer.subscription.created`, `customer.subscription.deleted`, `customer.subscription.updated`
    * `invoice.paid`

    See [Stripe Webhook Integration](/integrations/webhooks/stripe-webhook#steps) for more details.
  </Step>

  <Step title="Prompt Cursor to add User Referrals to your app">
    Switch Cursor to **Plan mode**, then paste this prompt:

    <Tabs>
      <Tab title="With Cello MCP connected">
        ```text theme={null}
        I want to add user referrals to my app using Cello.

        Use the Cello MCP to search the integration documentation, check my current integration status, and create a thorough implementation plan. Follow all best-practice recommendations from Cello.
        ```

        Cursor will pull the relevant guides, check what's already set up, and tailor the plan to your project.
      </Tab>

      <Tab title="Without MCP">
        ```text theme={null}
        I now want to add user referrals. I chose platform Cello for this.

        I added a Cello integration guide according to which you should do the implementation. parsed the documentation more carefully from the start rather than assuming standard patterns would work. create a thorough implementation plan based on guidance, patterns and AC from the provided guide. Don't skip any content, it is all relevant

        Guide: https://docs.cello.so/resources/react-nodejs-integration
        ```
      </Tab>
    </Tabs>

    Cursor asks you guiding questions and creates an implementation plan based on your answers.
  </Step>

  <Step title="Confirm executing the plan">
    Review the plan carefully. It should cover:

    * Cello JS SDK initialization and user authentication
    * Referral component placement and configuration
    * Attribution setup for tracking referred signups
    * Stripe webhook integration for conversion tracking

    If it looks correct, tell Cursor to proceed and start implementing it.
  </Step>

  <Step title="Run & Test">
    Run your app and test the end-to-end flow. If everything was implemented correctly, you should see events coming in to [Cello Dashboard](https://portal.cello.so/dashboard/referrer).

    <Tip>
      If you have the Cello MCP connected, ask Cursor to run a health check after deploying:

      *"Use Cello to check my integration status and confirm all four components are connected."*
    </Tip>
  </Step>
</Steps>

## After you're live

If you have the Cello MCP connected, it continues to be useful after the initial integration:

| Prompt                                           | What happens                                                                             |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| *"Is my Cello integration working?"*             | Checks all four integration components and reports which are connected or broken         |
| *"Why aren't referral rewards being triggered?"* | Inspects recent events to find missing or malformed fields preventing attribution        |
| *"How can I improve my referral program?"*       | Returns a prioritized list of recommendations across activation, sharing, and conversion |
| *"How do I set up a custom referral launcher?"*  | Searches the docs for custom launcher implementation guides                              |


# Cello + Lovable integration
Source: https://docs.cello.so/coding-apps/lovable-integration

How to add user referrals to your app using Cello with Lovable

Lovable now lets you integrate Cello user referrals entirely through **chat**. Just ask Lovable to **"Add user referrals to your app"** and it will do the rest - no manual coding required.

<img alt="Cello + Lovable integration" />

<Accordion title="Watch the walkthrough">
  <iframe title="Cello + Lovable integration walkthrough" />
</Accordion>

## Prerequisites

Before integrating Cello, ensure the following prerequisites are met:

* The project **must** be connected to Supabase. [Learn more about Supabase](https://docs.lovable.dev/integrations/supabase)
* User signup and authentication via Supabase is functional
* Stripe subscription flow is functional
* You have a Cello account and API keys at hand.

<Note>
  Make sure to use Cello **Sandbox environment** when developing and testing
</Note>

## Connect the Cello MCP

The [Cello MCP server](/mcp/introduction) gives Lovable direct access to Cello's documentation, integration health checks, and best-practice recommendations. Connecting it before you start means Lovable can look up the right docs itself, verify your setup as it goes, and follow best practices automatically - instead of relying only on the guide link you paste.

This step is optional but recommended. The integration steps below work either way. See [Connect your client → Lovable](/mcp/connect#lovable) for the setup steps.

## Cello user referrals integration

<Note>
  For a step-by-step technical implementation (source of truth + acceptance criteria), follow the detailed guide:

  * [Cello + Lovable Detailed Integration Guide](/resources/cello-lovable-detailed-integration)
  * [Cello + Lovable Detailed Integration (Credit-based Rewards)](/resources/cello-lovable-detailed-integration-credit-based-rewards)
</Note>

<Steps>
  <Step title="Prep your project">
    * Signup and authentication flow with Supabase is functional
    * Stripe subscription flow is functional
    * Cello API keys are handy
  </Step>

  <Step title="Add Cello Webhook Endpoint to Stripe">
    * Get your webhook URL from [Cello Portal](https://portal.cello.so/integrations/webhooks)
    * Add a Webhook endpoint in Stripe (Log into your Stripe Dashboard -> Go to Developer Mode -> Add a Webhook endpoint and enter endpoint URL -> Select the events to send -> Click "Add endpoint")
    * Secure the Webhook with "Signing secret"

    Events to send:

    * `charge.refunded`, `charge.succeeded`, `charge.updated`
    * `customer.created`, `customer.deleted`, `customer.updated`
    * `customer.subscription.created`, `customer.subscription.deleted`, `customer.subscription.updated`
    * `invoice.paid`

    See [Stripe Webhook Integration](/integrations/webhooks/stripe-webhook#steps) for more details.
  </Step>

  <Step title="Prompt Lovable to add User Referrals to your app">
    Switch Lovable to **Plan mode**, then paste this prompt:

    <Tabs>
      <Tab title="With Cello MCP connected">
        ```text theme={null}
        I want to add user referrals to my app using Cello.

        Use the Cello MCP to search the integration documentation, check my current integration status, and create a thorough implementation plan. Follow all best-practice recommendations from Cello.
        ```

        Lovable will pull the relevant guides, check what's already set up, and tailor the plan to your project.
      </Tab>

      <Tab title="Without MCP">
        ```text theme={null}
        I now want to add user referrals. I chose platform Cello for this.

        I added a Cello integration guide according to which you should do the implementation. parsed the documentation more carefully from the start rather than assuming standard patterns would work. create a thorough implementation plan based on guidance, patterns and AC from the provided guide. Don't skip any content, it is all relevant

        Guide: https://docs.cello.so/resources/cello-lovable-detailed-integration
        ```
      </Tab>
    </Tabs>

    Lovable asks you guiding questions and creates an implementation plan based on your answers.
  </Step>

  <Step title="Confirm executing the plan">
    Review the plan carefully. It should cover:

    * Cello JS SDK initialization and user authentication
    * Referral component placement and configuration
    * Attribution setup for tracking referred signups
    * Stripe webhook integration for conversion tracking

    If it looks correct, tell Lovable to proceed and start implementing it.
  </Step>

  <Step title="Publish & Test">
    You cannot try the full end-to-end flow in Preview mode. Publish your changes to test.

    If everything was implemented correctly, you should see events coming in to [Cello Dashboard](https://portal.cello.so/dashboard/referrer).

    <Tip>
      If you have the Cello MCP connected, ask Lovable to run a health check after publishing:

      *"Use Cello to check my integration status and confirm all four components are connected."*
    </Tip>
  </Step>
</Steps>

## After you're live

If you have the Cello MCP connected, it continues to be useful after the initial integration:

| Prompt                                           | What happens                                                                             |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| *"Is my Cello integration working?"*             | Checks all four integration components and reports which are connected or broken         |
| *"Why aren't referral rewards being triggered?"* | Inspects recent events to find missing or malformed fields preventing attribution        |
| *"How can I improve my referral program?"*       | Returns a prioritized list of recommendations across activation, sharing, and conversion |
| *"How do I set up a custom referral launcher?"*  | Searches the docs for custom launcher implementation guides                              |


# Cello + Replit integration
Source: https://docs.cello.so/coding-apps/replit-integration

How to add user referrals to your app using Cello with Replit

Replit Agent can implement Cello user referrals end-to-end if you give it the **right guide** and force it to create a plan before coding.

<img alt="Cello + Replit integration" />

## Prerequisites

Before integrating Cello, ensure the following prerequisites are met:

* Signup and authentication flow with a database to store user records is functional
* Stripe subscription flow is functional
* You have a Cello account and API keys at hand.

<Note>
  Make sure to use Cello **Sandbox environment** when developing and testing
</Note>

## Cello user referrals integration (Coding-agent flow)

<Note>
  For a step-by-step technical implementation (source of truth + acceptance criteria), follow the detailed guide:

  * [React + Node.js Integration Guide](/resources/react-nodejs-integration)

  The guide uses React + Node.js as an example, but it can be any other combination - the steps stay the same.
</Note>

<Steps>
  <Step title="Step 1">
    **Prep your project**

    * Signup and authentication flow with a database to store user records is functional
    * Stripe subscription flow is functional
    * Cello API keys are handy
  </Step>

  <Step title="Step 2">
    **Add Cello Webhook Endpoint to Stripe**

    * Get your webhook URL from [Cello Portal](https://portal.cello.so/integrations/webhooks)
    * Add a Webhook endpoint in Stripe (Log into your Stripe Dashboard -> Go to Developer Mode -> Add a Webhook endpoint and enter endpoint URL -> Select the events to send -> Click "Add endpoint")
    * Secure the Webhook with "Signing secret"

    Events to send:

    * `charge.refunded`, `charge.succeeded`, `charge.updated`
    * `customer.created`, `customer.deleted`, `customer.updated`
    * `customer.subscription.created`, `customer.subscription.deleted`, `customer.subscription.updated`
    * `invoice.paid`

    See [Stripe Webhook Integration](/integrations/webhooks/stripe-webhook#steps) for more details.
  </Step>

  <Step title="Step 3">
    **Prompt Replit Agent to add User Referrals to your app**

    Paste this prompt into Replit Agent (includes the detailed guide):

    ```text theme={null}
    I now want to add user referrals. I chose platform Cello for this.

    I added a Cello integration guide according to which you should do the implementation. parsed the documentation more carefully from the start rather than assuming standard patterns would work. create a thorough implementation plan based on guidance, patterns and AC from the provided guide. Don't skip any content, it is all relevant

    Guide: https://docs.cello.so/resources/react-nodejs-integration
    ```

    Replit Agent asks you guiding questions and creates an implementation plan based on your answers.
  </Step>

  <Step title="Step 4">
    **Confirm executing the plan**

    Review the plan carefully. If it looks correct, tell Replit Agent to proceed and start implementing it.
  </Step>

  <Step title="Step 5">
    **Publish & Test**

    Run your app and test the end-to-end flow. If everything was implemented correctly, you should see events coming in to [Cello Dashboard](https://portal.cello.so/dashboard/referrer).
  </Step>
</Steps>


# AI Assistant
Source: https://docs.cello.so/guides/ai-assistant/overview

Get answers about your referral program performance and take action faster - directly in the Cello portal

The Cello AI Assistant helps you understand program performance and take action faster - directly inside the Cello portal. It answers questions using your Cello data, metrics, benchmarks, and documentation.

<Info>
  This feature is available to growth managers in the Cello portal. Your feedback helps us improve - see [Providing feedback](#providing-feedback) below.
</Info>

<Note>
  Prefer to work from your own AI client like Claude? The same data is available through the [Cello MCP server](/mcp/growth/use-cases).
</Note>

## Using the assistant

The assistant is available in the Cello portal. To get started:

1. Open the assistant from the portal navigation
2. Type your question or select an example from the [AI Prompt Library](/guides/ai-assistant/prompt-library)
3. Review the response - the assistant will link to relevant charts, reports, or settings when applicable

<img alt="AI Assistant" />

The assistant works best with specific questions about your program. See the [AI Prompt Library](/guides/ai-assistant/prompt-library) for examples organized by category.

## How responses are generated

Responses are grounded in your portal context, Cello metrics, benchmarks (when available), and Cello documentation. The assistant links to relevant charts, reports, or settings so you can verify data and take action quickly.

## When the assistant can't help

If the assistant can't answer a question confidently, it will let you know and help you reach Support so your request is handled quickly.

## Providing feedback

Your feedback helps us improve quality and coverage:

* **Rate responses** using thumbs up/down to help us understand what's working
* **Share details** when something is off - what you asked, what you expected, and a screenshot if possible

We use feedback to improve prompts, add missing documentation, expand the AI Prompt Library, and refine the assistant's capabilities.

## Privacy and data

The AI Assistant runs in Cello's EU-hosted AWS environment. Customer content is not used to train foundation models. The assistant only uses the minimum context needed to answer using approved Cello sources.


# AI Prompt Library
Source: https://docs.cello.so/guides/ai-assistant/prompt-library

Example questions to ask the Cello AI Assistant

The AI Assistant handles a wide range of questions about your referral program. Here are examples organized by category - you'll also find these in the Prompt Library inside the assistant.

## Performance and analytics

Understand how your referral program is performing and how it compares to similar programs.

* "How do my metrics compare to benchmarks?"
* "What's my conversion rate from views to signups?"
* "How does my activation rate compare to benchmark?"

## Optimization

Get recommendations on where to focus your efforts to improve program performance. The assistant can help you prioritize actions from your [Performance Recommendations](/guides/attribution/recommendations) score.

* "What are the most impactful improvements I should prioritize?"
* "Which improvements require the least dev effort?"
* "How can I improve my sharing rate?"
* "How can I improve my active rate?"

## Referrers

Identify your top-performing referrers and understand where users are dropping off.

* "Which referrers drive the most signups?"
* "Which referrers drive the most revenue?"
* "What's causing my biggest drop-offs?"

## Conversion

Find ways to improve conversion rates at each stage of the referral funnel.

* "How can I increase new user signups to meet benchmarks?"
* "How can I improve purchase conversion vs. benchmark?"

## Fraud and review

Get help reviewing flagged referrals and potential fraud cases.

* "Can you help me review open fraud cases?"

## Notifications

Configure notification settings and get recommendations for engaging referrers.

* "How can I configure my notification settings?"
* "Which notification updates are recommended?"


# Performance Benchmarks
Source: https://docs.cello.so/guides/attribution/benchmarks

Understand how your program performance compares to similar companies

Cello provides industry benchmarks to help you understand how your referral program stacks up against similar companies. Benchmarks appear as horizontal reference lines on your dashboard charts, making it easy to identify where your program excels and where there's room for improvement.

Cello uses these benchmarks along with deep analysis of your program data to generate specific, actionable [Performance Recommendations](/guides/attribution/recommendations) tailored to your situation. Visit the [Recommendations page](https://portal.cello.so/dashboard/recommendations) in the Cello Portal to see exactly what to focus on next.

## Benchmarked Metrics

Cello provides benchmarks for four key metrics across the referral funnel. Benchmarks are hidden by default. Toggle them on from any supported chart to see how you compare.

<img alt="Benchmark lines on a Cello dashboard chart" />

* **Active Rate**: Percentage of enabled users who open the referral widget. Calculated as `Active Referrers / Enabled Referrers`.

* **Sharing Rate**: Percentage of active users who share their referral link. Calculated as `Sharing Referrers / Active Referrers`.

* **Signup Rate**: Percentage of unique referral link views that convert to signups. Calculated as `New User Signups / Unique Views`.

* **Unique Views per Share**: Average number of unique people who view each shared referral link. Calculated as `Unique Views / Sharing Referrers`.

<Info>
  Sharing rate benchmarks are adjusted based on your active rate. Cello automatically determines which benchmark band applies to you, so you're always comparing against relevant peers.
</Info>

## Methodology

Benchmarks are calculated from anonymized, aggregated monthly performance rates across all Cello customers. Your performance is compared using your latest 30-day rolling rates.

Charts show two benchmark lines:

* **Median (Average)**: The 50th percentile, half of customers perform better, half perform worse
* **Best in Class**: The 75th percentile, top 25% of customers achieve this or better

Benchmarks are segmented by Go-to-Market model so you're compared against similar businesses:

* **Free Trial**: Customers offering free trials before purchase
* **Freemium**: Customers with free tiers and paid upgrades
* **Demo Only**: Customers requiring demos before purchase
* **Overall**: All customers combined (used when your GTM model doesn't match the above)

Cello automatically detects your GTM model and shows the appropriate benchmarks.

## Interpreting Your Results

Visit [Performance Recommendations](/guides/attribution/recommendations) to understand your score, or go directly to the [Recommendations page](https://portal.cello.so/dashboard/recommendations) in the Cello Portal to see your specific next steps.

**Above Best in Class**\
Your program is in the top 25% for this metric. This is a strength worth maintaining - consider what's driving this success and whether those practices can be applied elsewhere.

**Between Median and Best in Class**\
You're performing above average but have room to reach best-in-class status. Review the relevant best practices guides to identify optimization opportunities.

**Below Median**\
There's a clear opportunity for improvement. See recommendations in the [Cello Portal](https://portal.cello.so/dashboard/recommendations) or explore these best practices:

* **Low active rate?** See [Increase Discoverability](/guides/best-practices/Increase-discoverability-of-your-referral-program) to get more users opening the widget
* **Low sharing rate?** Review [Contextual Sharing](/guides/best-practices/contextual-sharing) to prompt referrals at high-intent moments
* **Low signup rate?** Check [Optimizing Signup Conversion](/guides/best-practices/optimizing-signup-conversion) for landing page and flow improvements

You can query benchmark data from your own AI client using [`cello_get_program_metrics`](/mcp/tools#cello_get_program_metrics) via the [Cello MCP](/mcp/growth/use-cases).


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

<Warning>
  Cello will only import transaction events linked to a manually attributed referral that is less than 30 days old. If a purchase is older, please reach out to the Cello support team.
</Warning>

## How to Manually Attribute Referrals

<Tabs>
  <Tab title="Stripe webhook only">
    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

    <img alt="Step 4a,b: Open invoice.paid event" />

    <img alt="Step 4c: View event details" />

    <img alt="Step 4d: Resend past invoice.paid events" />
  </Tab>

  <Tab title="Chargebee webhook only">
    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.
  </Tab>

  <Tab title="Cello API & Webhook">
    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.

    <Info>
      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. The report templates will be provided by Cello Support team.
    </Info>
  </Tab>

  <Tab title="Cello API only">
    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).

    <Info>
      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. The report templates will be provided by Cello Support team.
    </Info>
  </Tab>
</Tabs>

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


# Program Performance and ARR
Source: https://docs.cello.so/guides/attribution/program-performance

Understand how Cello calculates Annual Recurring Revenue to measure your referral program's performance

Cello tracks **Net New Annual Recurring Revenue (ARR)** - the annualized value of recurring revenue from referred customers. ARR is calculated from **invoice paid events** rather than looking at subscription objects in Stripe or Chargebee. This approach reflects actual revenue collected and works consistently across different billing systems.

## Why invoice-based?

Using invoice paid events means you see real revenue collected, not theoretical subscription values. It also handles complex scenarios like prorations, upgrades, and plan changes automatically - without requiring special configuration.

## Annualizing different billing intervals

Customers pay on different schedules, so Cello normalizes everything to an annual basis. This lets you compare the true value of different customers regardless of how they chose to pay.

Here are examples of how subscription intervals are annualized:

* A \$50 **monthly** subscription becomes \$600 ARR
* A \$150 **quarterly** subscription becomes \$600 ARR
* A \$600  **yearly** subscription stays at \$600 ARR
* A \$1,200 two-year **biannual** contract becomes \$600 ARR

## Rolling forward recurring revenue

When a customer pays for a yearly subscription in January, that revenue represents value for the entire year. Cello "rolls forward" non-monthly subscriptions so your monthly ARR charts reflect ongoing revenue, not just the months when invoices happen to be paid.

This also means churn is detected automatically - if a renewal invoice doesn't arrive when expected, the ARR stops being rolled forward and drops off your charts.

### What this means for your dashboard

The ARR shown in Cello represents actual paid revenue from referred customers, annualized. When comparing to your billing system's total ARR, remember that Cello shows only **attributed ARR** - revenue from customers who came through your referral program.

## Handling real-world billing scenarios

Cello automatically adjusts for common situations:

* **Late invoicing** – If an invoice comes in a few days late (within 7 days), it's attributed to the expected month to prevent artificial dips or jumps in your charts
* **Early renewals** – Overlapping subscription periods are detected to avoid double-counting
* **Prorations** – When customers upgrade mid-cycle, proration credits are factored in to show the true subscription value

<Info>
  The Proration feature gradually being rolled out gradually across customers where applicable.
</Info>

## ARR movement breakdown

Cello breaks down ARR changes into components so you can understand what's driving growth:

* **New ARR** – Revenue from newly referred customers
* **Expansion ARR** – Increases from existing customers upgrading or adding seats
* **Contraction ARR** – Decreases from downgrades
* **Churned ARR** – Lost revenue when customers cancel or don't renew

You can choose to enable or disable  the ARR movement from the **New User ARR** chart menu.

<img alt="Image" title="Image" />

You can query program performance data from your own AI client using [`cello_get_program_metrics`](/mcp/tools#cello_get_program_metrics) via the [Cello MCP](/mcp/growth/use-cases).


# Performance Recommendations
Source: https://docs.cello.so/guides/attribution/recommendations

Prioritized actions to improve your referral program performance

The Recommendations page in the Cello portal shows you a prioritized list of actions to improve your referral program. Each recommendation includes a point value indicating its potential impact on your overall score.

## How it works

Your **Recommendations Score** reflects how well your referral program is configured for success. The score is based on proven best practices across activation, sharing, and conversion.

<img alt="Recommendations page" />

Each recommendation shows:

* **Point value** – the impact on your score when completed
* **Category** – which area of your program it affects
* **Action** – what you need to do, with links to settings or documentation

As you complete recommendations, your score increases and you'll see new recommendations unlock.

## Recommendation areas

### Activation

Actions that help users discover your referral program and understand its value. This includes launcher visibility, announcements, and activation campaigns.

### Sharing

Actions that encourage users to share more often and more effectively. This includes contextual prompts, reward messaging, and launcher configuration.

### Conversion

Actions that improve signup and purchase rates for referred users. This includes dual-sided rewards and personalization.

To see how your current metrics compare to industry benchmarks, see [Performance Benchmarks](/guides/attribution/benchmarks).

## Using recommendations with AI

You can ask the [AI Assistant](/guides/ai-assistant/overview) built into the portal to help you prioritize recommendations:

* "What are the most impactful improvements I should prioritize?"
* "Which improvements require the least dev effort?"

The assistant will reference your current recommendations and help you decide where to focus.

Prefer working from your own AI client? The same data is available via the [Cello MCP](/mcp/growth/use-cases) using the `cello_get_recommendations` tool.


# Increase Discoverability Of Your Referral Program
Source: https://docs.cello.so/guides/best-practices/Increase-discoverability-of-your-referral-program

Learn how to drive organic activation of your referral program with high discoverability

To drive organic activation for your referral program, high discoverability is key.

1. **1st-level visibility** - Creating basic awareness for your referral program with a launcher that is always visible is an absolute must-have to see success.
2. **Multiple referral launchers** - Add launchers in positions where they naturally attract user attention, the biggest lever for recurring traction

<img alt="Increase Discoverability 1 St Level Launcher Multiple Launchers" />

## **1st-level visibility**

<span>+4.4x activation rate</span>

<span>+21 performance points</span>

Display the **CTA link in the navigation menu at 1st-level**. When the link is displayed in a prominent position on screen, it can improve activation significantly. **Its positioning is crucial.** If the CTA is placed in a secondary menu, the activation rate is drastically reduced (\<1%).

### How to implement?

1. Choose a 1st level menu position and give it a unique html identifier.
2. Decide what your CTA is. We advice [adding a reward amount](https://docs.cello.so/referral-component/custom-launcher#add-reward-in-launcher) as it **increases activation by 1.5x** and give you score uplift by **6 performance points**.
3. Set the Custom Launcher Selector in [Cello Portal -> User Experience](https://portal.cello.so/setup/user-experience) to match your element identifier.

For a step-by-step guide, go to [Custom Launcher documentation](/referral-component/custom-launcher).

## **Multiple referral launchers**

<span>+8.8x activation rate</span>

<span>+14 performance points</span>

Integrating multiple launchers into your product pages can significantly increase activation, especially on pages where users are **primed for sharing such as upgrades, subscriptions, sharing content, and inviting team members.** The benefits of adding a custom launcher is that you can craft an activation message specific to that particular context.

### How to implement?

You can add a custom button anywhere in your UI 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 theme={null}
window.Cello("open");
```

## Performance impact

The chart below shows all Cello average active users rates. User activation increases by 8.8x when applying these 2 recommendations.

<img alt="Increase Discoverability" />


# 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)

<Tip>
  **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.
</Tip>

<img alt="Contextual sharing strategy overview showing integration points in user journey" />

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

<img alt="In-app announcement introducing referral program at moment of delight" />

### How to implement?

<span>For Developers</span>

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 theme={null}
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.

<img alt="Examples of referral CTAs integrated at moments of delight" />

### How to implement?

<span>For Developers</span>

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 theme={null}
window.Cello("showAnnouncement", { "type": "welcome-announcement-1" } );
```

<Tip>
  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).
</Tip>

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

<img alt="Email template with referral link integration example" />

### How to implement?

<span>For Developers</span>

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/referral-codes/fetch-active-link) and enrich the emails you already send to your users with information about referral program and their personal invite link.


# Optimize signup conversion
Source: https://docs.cello.so/guides/best-practices/optimizing-signup-conversion

Recommendations to optimize the signup conversion of referred users

Improve signup conversion for referred users with personalized experiences. These best practices can significantly increase conversion rates.

1. **Show personalization and discounts** - Display the referrer's name and discount offer on your website
2. **Custom referral landing page** - Create a dedicated landing page and disable the Cello-hosted page

## **Show personalization and discounts**

<span>\~50% higher signup rate</span>

When a referred user lands on your website, showing them who referred them and what discount they're getting makes the offer feel personal.

They're not seeing a generic signup page. They're seeing a recommendation from someone they know, with a clear incentive to act.

<img alt="Personalization example" />

### How it works

1. **Personalization**: Referrer names can be integrated into your website or into Cello's new user banner. The name is provided via the Cello boot inside your product.
2. **Full integration**: Your developer can set up personalization directly in your website based on URL parameters and cookie information provided by Cello.
3. **New user banner**: Cello can activate a banner on your website to display the offer to referred users. Personalization is optional.
4. **Disable Cello-hosted landing page**: The Cello hosted-landing page can be disabled since discount information is displayed on your website. One conversion step is eliminated.

### How to implement

Your developer can add personalization in two ways:

* **Inline personalization**: Use the [Cello Attribution script](/sdk/client-side/attribution-js-usage) to fetch referrer info and display it in your page headlines, banners, or CTAs
* **New user banner**: Enable the no-code [Cello banner](/guides/user-experience/personalizing-referrals#add-personalization-with-the-new-user-banner) that automatically appears for referred visitors

To fetch referrer information for personalization, use the [referral code API](/api-reference/referral-codes/fetch-referral-code-info).

For detailed implementation guides, see:

* [Personalizing referrals](/guides/user-experience/personalizing-referrals)
* [New user discounts](/guides/user-experience/new-user-discounts)

### Examples

🔗 [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 with personalized new user banner](https://meetgeek.ai/meetgeek-referral?productId=app.meetgeek.ai\&ucc=vTlj7ne4Fkf\&n=VG9iaWFz)

***

## **Custom referral landing page**

<span>\~2x higher signup rate</span>

Instead of sending referred users to the Cello-hosted landing page, send them directly to a page you control. You can tailor the messaging, show your product's value, and get them to signup without an extra redirect. Fewer steps can lead to less drop-offs.

### Key building blocks

1. **Personalized headline** - Include the referrer's name
2. **New user discount** - Make the discount clear and visible
3. **Hero message** - Your key value proposition
4. **Product visual** - Show what the product does
5. **CTA** - Direct signup with the offer highlighted
6. **Social proof** - G2/Capterra badges, Trustpilot, customer logos
7. **Customer quotes** - Real testimonials
8. **FAQs** - Answer common questions

<Tip>
  **Leverage existing assets** - Do you already have an optimized landing page for ads? Reuse the content and directly include the signup form for the fastest path to success.
</Tip>

### How to set up

1. Create your landing page using the building blocks above
2. Go to [New User Experience setup](https://portal.cello.so/setup/new-user-experience) in Cello Portal
3. Switch to **Custom landing page** and add your URL

For a detailed guide, see [Optimizing referral landing pages](/guides/user-experience/optimizing-landing-pages).

### Examples

🔗 [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/)


# 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 referrer earns recurring rewards with each payment until they reach the **maximum cap of \$100** for this referral. In this example, that happens to take 6 months based on the referred user's spending. These regular rewards encourage further sharing.

<img alt="Recurring rewards example over 6 months" />

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

<img alt="Campaign settings in Cello Portal" />

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

<Warning>
  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.
</Warning>

### Running promotional campaigns

Cello supports one active campaign at a time. To run a time-limited promotion (e.g., Black Friday):

1. Adjust your reward percentages and new user discounts in [Campaign Settings](https://portal.cello.so/setup/campaigns)
2. Revert the settings when the promotion ends

There's no automated scheduling, so set a reminder to update your settings before and after the promotional period.


# Cello vs. FirstPromoter
Source: https://docs.cello.so/guides/competitor-comparison/cello-vs-firstpromoter

Compare Cello and FirstPromoter for referral programs: integration effort, server vs client tracking, in‑app UI, notifications, campaign rules, payouts, and trade‑offs.

If you're deciding between **Cello and FirstPromoter** for referrals, this page gives a practical comparison to help you choose. You'll find what you need to build for each option and the trade‑offs across attribution reliability, in‑app UX, notifications, campaigns, and payouts.

<Tip>
  **Cello** embeds a native referral component, coordinates in‑app + email journeys, and uses server‑side attribution via Stripe and webhooks. **FirstPromoter** provides a tracking snippet and hosted affiliate portal; teams typically build or embed the user experience themselves.
</Tip>

## Overview

* **In‑product referral UI**: Cello provides a native in‑app referral panel for web and mobile; users see their link, status, and rewards inside your app.
* **Affiliate portal model**: FirstPromoter centers on a JavaScript tracking snippet (`fpr.js`) and a hosted portal; there is no pre‑built in‑app referral panel.

## Integration and UX embedding

| **Topic**                       | **Cello**                                                                    | **FirstPromoter**                                                                                           |
| ------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Referral UI embedding**       | Native Referral Component; in‑app panel shows link, status, rewards.         | JS tracking snippet; no embedded referral widget. Affiliate UI is hosted externally or embedded via iframe. |
| **Custom launcher / placement** | Custom Launcher to open panel from any UI element with full styling control. | No equivalent launcher pattern; developers wire UI to APIs or redirect to hosted pages.                     |
| **Branding & control**          | Inherits your design system; theming is automatic.                           | Branding primarily on the hosted portal or via white‑label settings.                                        |

### Example

Open Cello’s referral panel from a profile menu item; keep the experience fully in‑app and on‑brand.

<img alt="Referral Component Pn" />

### Notifications and engagement

Cello includes an in‑app and email notification system for referral programs:

* **In‑app alerts and badges:** e.g., an alert under a “Rewards” tab and a badge on the launcher when a reward is earned.
* **Announcements (callouts):** prompts for next actions such as adding payout details after earning a reward.
* **Email notifications:** lifecycle emails at moments like welcome, first share, reward earned, and unclaimed reminders.
* **Journey logic:** behavior‑based timing (e.g., alert now, then announcement after 7 days if no action).

![Announcement feature examples](https://uploads.developerhub.io/prod/d316/ctsxd2yb6srflbb9e4aejnc85yabjrh8lzuhw2cw9xf5i03m9czkjbh3pm59vh1e.png)

FirstPromoter offers **email notifications** and **webhooks** for events. There is **no native in‑app notification layer**; teams implement journeys via external tooling, **requiring additional development effort**.

## Mobile SDKs

| **Topic**               | **Cello**                                                                                                                       | **FirstPromoter**                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Native mobile SDKs**  | iOS, Android, and React Native SDKs with a plug‑and‑play referral component.                                                    | No native mobile SDK; web‑first via JavaScript (`fpr.js`) and REST API/webhooks.             |
| **Integration pattern** | Quick install (SPM/CocoaPods/Gradle). Initialize with product ID/user token; supports custom launchers and native share sheets. | Mobile apps embed a web view/portal or build custom flows against the REST API and webhooks. |
| **In‑app referral UI**  | Embedded panel inside the mobile app; users copy links, view progress, manage rewards natively.                                 | No pre‑built in‑app panel; experiences are web/portal‑based or custom‑built.                 |
| **Payout support**      | Platform includes automated payouts via PayPal/Venmo with credit note issuance and VAT handling (outside SDK code).             | Payouts handled externally via dashboard/API; not native to the mobile app.                  |

<Warning>
  If you need native, in‑app referral UX on iOS/Android with minimal build, Cello’s SDKs provide a faster path. FirstPromoter requires custom mobile implementation or redirecting to a web portal.
</Warning>

## Attribution: client vs server flow

| **Topic**           | **Cello**                                                                                                                                                 | **FirstPromoter**                                                                                                                             |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tracking model**  | Backend‑centric attribution using secure IDs and event webhooks (e.g., Stripe). No reliance on cookies or client scripts.                                 | Client‑side cookie tracking by default (`_fprom_ref`, `_fprom_tid`). API‑only mode exists but requires custom setup.                          |
| **Conversion flow** | Ties referrals to backend payment events via Stripe metadata (`cello_ucc`, `new_user_id`) or API payloads. Deterministic even in blocked/mobile contexts. | Attributes sales by matching customer emails from client‑recorded leads to billing events; sensitive to missing cookies or mismatched emails. |
| **Resilience**      | Works in privacy‑restricted or JS‑disabled environments; ideal for mobile, embedded, or secure checkout flows.                                            | Dependent on browser state; cookie‑less or JS‑restricted scenarios require custom logic.                                                      |

<Warning>
  In environments with strict CSP, script blockers, mobile apps, or server‑rendered checkouts, server‑first attribution reduces reliance on client events. FirstPromoter can be configured via API but requires additional work.
</Warning>

## Campaigns, rewards, and payouts

### Campaign design and reward rules

| Aspect                   | **Cello**                                                                    | **FirstPromoter**                                                               |
| ------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Campaign flexibility** | Multi‑condition campaigns (percentage, fixed, discount) within one rule set. | One primary reward per campaign; advanced structures require manual setup.      |
| **Double‑sided**         | Native friend incentives (“give $X, get $Y”) built into campaign logic.      | Implemented via coupon codes synced with Stripe; manual configuration required. |
| **Recurring rewards**    | Recurring rewards with configurable caps per campaign.                       | Recurring commissions supported; limits are defined per campaign manually.      |
| **Computation**          | Reward logic executed server‑side; rewards auto‑registered via events.       | Tracked on client lead creation; resolved by matching purchase webhooks.        |

### Payout management

| Aspect              | **Cello**                                                                 | **FirstPromoter**                                                    |
| ------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Fulfillment**     | Automated reward registration and payout initiation.                      | Aggregates commissions; payouts executed manually or via PayPal API. |
| **User experience** | Users select payout method (e.g., PayPal, Venmo) inside your application. | Payouts managed on the hosted portal; not within your product UI.    |

## Summary: key differences

1. **In‑app referral UX vs portal**: Cello provides a native embedded panel; FirstPromoter uses a hosted affiliate portal and snippet.
2. **Engagement**: Cello offers in‑app + email journeys; FirstPromoter relies on email and webhooks with no in‑app layer.
3. **Attribution**: Cello is server‑first via metadata/webhooks; FirstPromoter defaults to client cookies and email matching.
4. **Campaigns**: Cello supports multi‑type and double‑sided rewards in one campaign; FirstPromoter is more single‑reward oriented.
5. **Payouts**: Cello manages payouts inside your app; FirstPromoter manages payouts externally.
6. **Mobile SDKs**: Cello offers native iOS/Android/React Native SDKs with a plug‑and‑play component; FirstPromoter has no native mobile SDK and is web‑first.

Select the option that fits your integration model (in‑app vs portal), attribution requirements (server‑side vs client‑side), and operational preferences (built‑in journeys vs custom tooling).


# Cello vs. Impact Advocate (SaaSquatch)
Source: https://docs.cello.so/guides/competitor-comparison/cello-vs-impact-advocate

Compare Cello and Impact Advocate (SaaSquatch): integration effort, widgets vs embedded UI, server vs client attribution, notifications, campaign rules, and payouts.

If you're deciding between **Cello and Impact Advocate (SaaSquatch)** for referrals, this page gives a practical comparison across integration effort, attribution reliability, in‑app experience, notifications, campaigns, and payouts.

<Tip>
  **Cello** embeds a native referral component, coordinates in‑app + email journeys, and uses server‑side attribution via Stripe metadata. **Advocate** relies on embeddable widgets and external portals that often require additional styling and setup to feel native.
</Tip>

## Overview

* **Embedded referral UI**: Cello’s Referral Component integrates natively in your app (web/mobile) with automatic theming and a launcher.
* **Widget/portal model**: Advocate provides widgets (`squatch.js`, `<squatch-embed>`), which are external elements styled separately or surfaced via a portal.

## Integration and UX embedding

| **Topic**                       | **Cello**                                                                                                  | **Impact Advocate (SaaSquatch)**                                                                                                  |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Referral UI embedding**       | Native Referral Component; in‑app panel with link, status, rewards; floating or custom launcher supported. | Widgets via `squatch.js` or `<squatch-popup>`; iframe‑like embeds requiring separate styling; no pre‑built native referral panel. |
| **Custom launcher / placement** | Custom Launcher to open panel from any UI element, keeping the flow in context.                            | Developers manually wire triggers (e.g., `<squatch-popup>`); no built‑in launcher button.                                         |

### Example

Open Cello’s referral panel from a menu item; keep users in‑app with a cohesive look and feel. Widgets typically need extra work to match your design system.

<img alt="Referral Component Pn" />

### Notifications and engagement

Cello includes an in‑app and email notification system for referral programs:

* **In‑app alerts and badges** for important moments like reward earned.
* **Announcements (callouts)** to prompt next actions, such as adding payout details.
* **Email lifecycle notifications** (welcome, first share, reward earned, unclaimed reminders).
* **Behavior‑based timing** to coordinate in‑app and email touchpoints.

![Announcement feature examples](https://uploads.developerhub.io/prod/d316/ctsxd2yb6srflbb9e4aejnc85yabjrh8lzuhw2cw9xf5i03m9czkjbh3pm59vh1e.png)

**Advocate** provides **event webhooks** and **email templates** but no native in‑app notification layer. Teams typically build in‑app nudges with other systems,  **requiring additional development effort**.

## Mobile SDKs

| **Topic**               | **Cello**                                                                                                                       | **Impact Advocate (SaaSquatch)**                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Native mobile SDKs**  | iOS, Android, React Native SDKs with a plug‑and‑play referral component.                                                        | iOS and Android SDKs available; mobile widgets and deep‑linking supported.                                |
| **Integration pattern** | Quick install (SPM/CocoaPods/Gradle). Initialize with product ID/user token; supports native share sheets and custom launchers. | Hybrid model: combine SDK with server‑side REST API calls; SDKs do not support payment‑provider programs. |
| **In‑app referral UI**  | Embedded mobile panel showing link, progress, rewards; theming aligns with app UI.                                              | SDK gives control over in‑app presentation; also offers mobile widgets to embed experiences.              |
| **Payout support**      | Platform includes automated payouts via PayPal/Venmo with credit note issuance and VAT handling (outside SDK code).             | Rewards tracked in platform; payout fulfillment handled via platform/integrations, not SDK.               |

<Warning>
  Impact’s SDKs cover core referral mechanics but require server APIs and do not support payment‑provider programs. Cello’s SDKs include a pre‑built component and platform payout automation to reduce custom work.
</Warning>

## Attribution: client vs server flow

| **Topic**                  | **Cello**                                                                                             | **Impact Advocate (SaaSquatch)**                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Client dependency**      | Backend‑centric attribution driven by webhooks and secure metadata; resilient without client scripts. | Client + cookie‑based tracking by default; server API integration is optional and requires extra setup.        |
| **Payment/Stripe linkage** | Stripe metadata (`cello_ucc`, `new_user_id`) for direct backend attribution - no client JS required.  | Relies on browser cookies or manual event calls; payment integrations exist but typically require more config. |

<Warning>
  In strict CSP environments, with script blockers, mobile apps, or server‑rendered checkouts, server‑first attribution reduces points of failure. Advocate can reach parity with extra server work.
</Warning>

## Campaigns, rewards, and payouts

### Campaign design and reward rules

| Aspect                   | **Cello**                                                                                          | **Impact Advocate (SaaSquatch)**                                                   |
| ------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Campaign flexibility** | Multiple reward types in one campaign (fixed, %, signup bonus, discounts); double‑sided supported. | Complex structures via rules engine but often split across multiple programs.      |
| **Reward types**         | Combines cash, % commissions, and friend discounts in one flow.                                    | Wide catalog (points, gift cards, coupons) but often one primary type per program. |
| **Configuration**        | Managed in Cello dashboard or via API.                                                             | Configured mainly in Advocate portal; APIs for advanced use cases.                 |

### Payout management

| Aspect              | **Cello**                                                               | **Impact Advocate (SaaSquatch)**                                                      |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Fulfillment**     | Fully automated payouts (PayPal, Venmo) with tracking and tax handling. | Tracks rewards; fulfillment via provider integrations (PayPal, Tango Card) or manual. |
| **User experience** | Users claim and manage payouts inside your app.                         | Users redeem via portal, email, or third‑party sites.                                 |
| **Workflow**        | End‑to‑end: reward earned → notified → paid.                            | Requires configuration of a payout provider or manual redemption flow.                |

### Recurring rewards and multi‑month commissions

| Aspect                    | **Cello**                                        | **Impact Advocate (SaaSquatch)**                      |
| ------------------------- | ------------------------------------------------ | ----------------------------------------------------- |
| **Recurring commissions** | Native recurring rewards with configurable caps. | Supports recurring events; caps require custom logic. |
| **Granular controls**     | Built‑in duration and cap settings per campaign. | Requires advanced rule setup or calculated fields.    |

## Summary: key differences

1. **Embedded UI vs widgets/portal**: Cello is native in‑app; Advocate relies on widgets and portals.
2. **Engagement**: Cello provides in‑app + email journeys; Advocate requires external tooling for in‑app nudges.
3. **Attribution**: Cello is server‑first via Stripe metadata; Advocate defaults to client/cookie tracking.
4. **Campaigns**: Cello composes multiple reward types in one campaign; Advocate often splits across programs.
5. **Payouts**: Cello automates payouts inside your product; Advocate integrates with providers or uses manual flows.
6. **Mobile SDKs**: Both provide native iOS/Android SDKs; Cello includes a plug‑and‑play component and platform payout automation, while Advocate’s SDK is hybrid (server APIs) and does not support payment‑provider programs.

Choose the option that aligns with your integration model (embedded vs widgets/portal), attribution requirements, and operations (built‑in journeys vs custom assembly).


# Cello vs. PartnerStack
Source: https://docs.cello.so/guides/competitor-comparison/cello-vs-partnerstack

Compare Cello and PartnerStack for referrals: embedded UI vs external portal, server vs client tracking, notifications, campaign rules, payouts, and trade‑offs.

If you're evaluating **Cello vs PartnerStack** for referral programs, this guide summarizes integration effort, attribution reliability, in‑app experience, notifications, campaigns, and payouts to inform your choice.

<Tip>
  **Cello** embeds a native referral panel with server‑side attribution and in‑app + email journeys. **PartnerStack** focuses on a broad partner portal and JS SDK; users typically manage links and payouts on an external dashboard.
</Tip>

## Overview

* **In‑product referral UI**: Cello’s Referral Component lives inside your app; users can copy links, view stats, and manage rewards without leaving.
* **Portal‑centric model**: PartnerStack centers on an external portal and SDK; in‑app referral UI is minimal and often redirects to PartnerStack.

## Integration and UX embedding

| **Topic**                       | **Cello**                                                                                                                                    | **PartnerStack**                                                                                                                                   |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Referral UI embedding**       | Embedded referral panel in‑app; shows each user’s link, stats, rewards, fully native to your UX.                                             | JS SDK and simple iFrame form for collecting emails/generating links. No in‑app referral dashboard; users manage referrals on PartnerStack’s site. |
| **Custom launcher / placement** | Flexible launcher: attach panel open to any element (menu item, button). Replace or hide the default floating button for a fully branded UX. | No native launcher concept; teams create custom buttons/links to open forms or redirect to the portal.                                             |

### Example

Open Cello’s panel from an “Invite Friends” button in your app; PartnerStack typically takes users out to an external dashboard for management.

<img alt="Referral Component Pn" />

### Notifications and engagement

Cello includes an in‑app and email notification system for referral programs:

* **In‑app alerts & badges** for referral joins or rewards earned.
* **Announcements** prompting next steps (e.g., add payout details).
* **Email lifecycle** for welcome, reward earned, and unclaimed reminders.
* **Behavior‑based timing** to coordinate prompts and reminders.

![Announcement feature examples](https://uploads.developerhub.io/prod/d316/ctsxd2yb6srflbb9e4aejnc85yabjrh8lzuhw2cw9xf5i03m9czkjbh3pm59vh1e.png)

**PartnerStack** does not provide native in‑app notifications. It relies on **webhooks** and external email triggers; custom in‑app messaging requires manual builds,  **requiring additional development effort**.

## Mobile SDKs

| **Topic**               | **Cello**                                                                                                                       | **PartnerStack**                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Native mobile SDKs**  | iOS, Android, React Native SDKs with a plug‑and‑play referral component.                                                        | No native mobile SDK; focuses on partner portal, JS tracking, and referral iFrame.                            |
| **Integration pattern** | Quick install (SPM/CocoaPods/Gradle). Initialize with product ID/user token; supports native share sheets and custom launchers. | Mobile apps embed a portal/iFrame or build custom UI against REST APIs; referrals managed in external portal. |
| **In‑app referral UI**  | Embedded mobile panel that is themable and aligns with app UI.                                                                  | No pre‑built in‑app referral panel; experiences are portal/web‑based.                                         |
| **Payout support**      | Platform includes automated payouts via PayPal/Venmo with credit note issuance and VAT handling (outside SDK code).             | Payouts managed via PartnerStack portal on monthly cycles; not inside your app.                               |

<Warning>
  If you need native iOS/Android referral experiences, Cello’s SDKs provide the in‑app component. PartnerStack is portal‑centric and requires custom app work or redirects.
</Warning>

## Attribution: client vs server flow

| **Topic**             | **Cello**                                                                                                              | **PartnerStack**                                                                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client dependency** | Backend‑centric tracking: attribution on server events (e.g., Stripe webhooks); no cookies or client scripts required. | Client‑centric tracking via JS snippet and cookies; requires a front‑end call to confirm conversions. Missing scripts or blockers can break attribution. |
| **Stripe / metadata** | Server metadata‑based: referral codes stored on Stripe objects; attribution via webhooks.                              | Cookie & ID matching: matches by email or client IDs, often with delays. Server‑side setup is optional and more complex.                                 |

<Warning>
  Server‑first attribution remains reliable across strict privacy environments, mobile apps, and blocked scripts. PartnerStack’s JS flow is browser‑dependent unless hardened with server integrations.
</Warning>

## Campaigns, rewards, and payouts

### Campaign design and reward rules

| Aspect                   | **Cello**                                                                                  | **PartnerStack**                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Campaign flexibility** | Multiple reward types in one campaign: % commissions, bonuses, caps, and friend discounts. | Managed via Triggers: one reward per trigger; complex logic requires multiple triggers.             |
| **Reward types**         | Combine % and fixed bonuses, plus new‑user discounts, in a single setup.                   | Each trigger offers a single flat or % reward; no native friend‑gets‑X incentives in the same flow. |

### Payout management

| Aspect              | **Cello**                                                             | **PartnerStack**                                                   |
| ------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Fulfillment**     | Automated payout calculation and initiation.                          | Monthly batch payouts via the portal or manual approval.           |
| **User Experience** | Referrers choose payout method (e.g., PayPal, Venmo) inside your app. | Users get paid via PartnerStack’s portal, not inside your product. |
| **Workflow**        | Real‑time payout updates and in‑app notifications.                    | External batch payout cycle, disconnected from your UX.            |

### Recurring rewards and multi‑month commissions

| Aspect                    | **Cello**                                        | **PartnerStack**                                            |
| ------------------------- | ------------------------------------------------ | ----------------------------------------------------------- |
| **Recurring commissions** | Native recurring rewards with configurable caps. | Recurring commissions supported; caps require manual setup. |
| **Control**               | Built‑in duration and reward caps.               | Requires manual review or multi‑trigger management.         |

## Summary: key differences

1. **In‑app UI vs portal**: Cello is embedded; PartnerStack is portal‑centric.
2. **Engagement**: Cello provides in‑app + email journeys; PartnerStack relies on external comms.
3. **Attribution**: Cello is server‑first via metadata/webhooks; PartnerStack defaults to client/cookie tracking.
4. **Campaigns**: Cello composes multiple rewards in one campaign; PartnerStack uses single‑reward triggers.
5. **Payouts**: Cello supports in‑app payout flows; PartnerStack manages payouts externally.
6. **Mobile SDKs**: Cello offers native iOS/Android/React Native SDKs with an embedded component; PartnerStack has no native mobile SDK (portal‑centric).

Choose the platform that matches your desired integration model, attribution requirements, and operational ownership.


# Cello vs. Rewardful
Source: https://docs.cello.so/guides/competitor-comparison/cello-vs-rewardful

Evaluate and prototype Cello vs Rewardful: what to build, risks, and trade‑offs across attribution, UI, notifications, rewards, and payouts.

If you're deciding between **Cello and Rewardful** for referrals, this page gives a practical comparison to help you choose. You'll find a concise overview of what you need to build for each option, the trade‑offs around attribution reliability, in‑app UX, notifications, campaigns, and payouts, and practical pros/cons to inform your architecture.

<Tip>
  **Cello** offers an embedded referral UI, built‑in journeys, and server‑first attribution that can reduce time‑to‑value; **Rewardful** provides a lightweight tracking layer suited to teams that plan to build out user experience and messaging orchestration themselves.
</Tip>

## Overview

* **In‑product referral UI**: Cello embeds a panel directly in your application so users can copy links, view progress, and manage rewards without leaving your app.
* **Snippet‑based tracking**: Rewardful centers on a JavaScript snippet and REST API. You implement the user‑facing UI yourself or link out to an external portal.

## Integration and UX embedding

| **Topic**                       | **Cello**                                                                                                                                                                 | **Rewardful**                                                                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Referral UI embedding**       | Cello’s referral component embeds in your UI. Use a floating action button or a custom launcher to open an in‑app panel with a user’s referral link, status, and rewards. | Implements a JS snippet that exposes a browser API (`rewardful` function) to track conversions. No pre‑built in‑app referral panel; you build the user‑facing experience or use their portal. |
| **Custom launcher / placement** | Cello supports a custom launcher: attach any element (button, menu item, etc.) to open the referral panel; you may hide the default floating button.                      | No native embedded launcher. Teams wire up their own UI to call methods like `rewardful('ready', ...)` and `rewardful('convert', {...})`.                                                     |

### Example

**Cello** Referral Component opens from a custom launcher in your product menu. This keeps the experience in‑app and aligned with your UI.

<img alt="Referral Component Pn" />

**Rewardful** does not provide a pre‑built in‑app referral panel; you build the user‑facing experience or use their portal.

### Notifications and engagement

Cello includes an in‑app and email notification system for referral programs:

* **In‑product alerts and badges:** e.g., an alert under a “Rewards” tab with a badge on the launcher when a reward is earned.
* **Announcements (callouts):** anchored prompts for next actions (e.g., add payout details after earning a reward). Dismissible.
* **Email notifications:** lifecycle emails at moments such as welcome, first share, reward earned, and unclaimed reminders.
* **Journey logic:** timing based on behavior (e.g., alert now, follow‑up announcement after 7 days if no action; recurring reminders only for recently active users).

### Example

**Cello** in‑app “new reward” notification prompts a user to add payout details in the referral component.

![Announcement feature examples](https://uploads.developerhub.io/prod/d316/ctsxd2yb6srflbb9e4aejnc85yabjrh8lzuhw2cw9xf5i03m9czkjbh3pm59vh1e.png)

**Rewardful** does not include a native in‑app notification framework; Instead Rewardful exposes webhooks for events (e.g., referral created, converted, payout due). Teams typically connect these to their email/in‑app systems, **requiring additional development effort**.

## Attribution: client vs server flow

| **Topic**             | **Cello**                                                                                                                                                                                                                   | **Rewardful**                                                                                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Client dependency** | Backend‑centric attribution. Attribution runs on backend events (e.g., Stripe webhooks). SDK initialization can pass `productUserDetails` for identification and fraud checks ([docs.cello.so](http://docs.cello.so/)).     | Client‑side default. Requires snippet load and `rewardful('convert', { email })` on a confirmation page. Referrals are linked via email lookup in Stripe (\~24 h) ([developers.rewardful.com](http://developers.rewardful.com/)). |
| **Stripe / metadata** | Server‑side, metadata‑based. Add `cello_ucc` and `new_user_id` to Stripe Customer / Checkout Session. Webhooks link and reward automatically - no client conversion call required ([docs.cello.so](http://docs.cello.so/)). | Client‑dependent linking. Uses Stripe `client_reference_id` and a \~24 h email‑match window. Can be hardened with custom server logic ([help.rewardful.com](http://help.rewardful.com/)).                                         |

<Warning>
  In environments with strict CSP, script blockers, mobile apps, or server‑rendered checkouts, a server‑first pattern reduces dependency on client events. Rewardful can be configured server‑side but requires additional work.
</Warning>

## Campaigns, rewards, and payouts

### Campaign design and reward rules

| Aspect                      | **Cello**                                                                                                      | **Rewardful**                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Campaign flexibility**    | Multiple payout rules within one campaign: % commissions, fixed bonuses, reward caps, and new‑user discounts.  | One reward type/rate per campaign.                         |
| **Reward types**            | Combine % of revenue, fixed bonuses (e.g., signup or first purchase), and new‑user discounts in a single flow. | Choose either % commission or fixed amount per conversion. |
| **Example setup**           | 50% of payments up to $100, plus $5 signup bonus, and 50% discount for 6 months - in one configuration.        | Set a % or fixed reward per conversion.                    |
| **Double‑sided incentives** | New‑user discounts integrated into campaign logic.                                                             | Possible via Stripe coupons (plan‑dependent).              |
| **Configuration**           | Managed in‑app or via API.                                                                                     | Configurable via REST API.                                 |

### Payout management

| Aspect                | **Cello**                                                               | **Rewardful**                                                  |
| --------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Fulfillment**       | Automated reward registration and payout initiation.                    | Tracks payout data; execution handled externally.              |
| **User experience**   | End‑users choose payout method (e.g., PayPal, Venmo) inside your app.   | No native end‑user payout UI.                                  |
| **Workflow**          | Rules calculate rewards, trigger notifications, and mark payouts ready. | Commissions accumulate; payouts marked paid via dashboard/API. |
| **Integration depth** | In‑app payout management via hosted component.                          | Developer‑level API integration.                               |

### Recurring rewards and multi‑month commissions

| Aspect                    | **Cello**                                                    | **Rewardful**                              |
| ------------------------- | ------------------------------------------------------------ | ------------------------------------------ |
| **Recurring commissions** | Native support for recurring rewards with configurable caps. | Recurring commissions via Stripe renewals. |
| **Granular controls**     | Reward caps configurable in campaign setup.                  | Reward caps often require custom logic.    |
| **Common use cases**      | Multi‑month or capped rewards configured directly.           | Lifetime or one‑off bounties are typical.  |
| **Implementation**        | Defined in campaign configuration.                           | Tracked via Stripe events.                 |

## Summary: key differences

1. **In‑app referral UI vs snippet‑only**: Cello includes an embedded panel; Rewardful provides tracking APIs.
2. **Notifications**: Cello includes in‑app and email journeys; Rewardful relies on webhooks to power your own stack.
3. **Attribution**: Cello is server‑first via Stripe metadata; Rewardful defaults to client conversion calls (server hardening is possible).
4. **Campaigns**: Cello supports multiple reward rules per campaign; Rewardful focuses on a single reward type/rate.
5. **Payouts**: Cello provides in‑app payout flows; Rewardful tracks balances and leaves payout UX external.

Select the option that best aligns with your integration model (in‑app vs external), attribution requirements (server‑side vs client‑side), and operational preferences (built‑in journeys vs custom tooling).


# Fraud Detection
Source: https://docs.cello.so/guides/fraud-detection

Cello provides automated capabilities to detect and automatically mitigate potential cases of self-referrals and fraudulent activity

Cello provides automated capabilities to detect and automatically mitigate potential cases of self-referrals and fraudulent activity. With Cello, you can maintain complete control of how any potential cases are handled, either by automatically rejecting or reviewing some on a case-by-case basis.

### Reviewing potential cases

Potential cases of self-referrals or other fraudulent activity are flagged in the Cello portal under the **[Review Referrals](https://portal.cello.so/manage/reviewreferrals)** section. You can then see all cases that are **In Review** or **Completed** using the filters at the top of the table.

<img alt="Review Referrals section with filters" />

### Automation and risk factors

Cello automates detection based on a number of factors to determine the potential risk of fraudulent activity. A complete list can be provided upon request. To see the individual risk factors that are available, you can hover over the status column for a referral.

<img alt="Risk factors displayed on hover" />

<Info>
  Note that risk factors can change over time during the initial 30 day review period.
</Info>

### Manually accepting or rejecting

For pending referrals, you can manually accept or reject them at any time by clicking on the **Review** button and selecting your choice. You can optionally provide additional reasons for accepting or rejecting. This information is used by Cello to improve and customize detection.

<img alt="Manual review interface with accept/reject options" />

When reviewing transactions manually, we recommend looking for the following factors:

* Issuing chargebacks or canceling within a short amount of time
* Unusual patterns of usage
* Is the referrer still a paying user?

### Payout delays

Long payout delays are typically not required. Programs using spaced rewards with low percentages naturally have less exposure, and Cello automatically cancels pending rewards when refunds occur.

If your program requires additional protection, Cello can configure a longer waiting period before rewards are paid out. Contact your CSM or [support@cello.so](mailto:support@cello.so) to set this up.

You can review fraud analysis from your own AI client using [`cello_get_fraud_analysis`](/mcp/tools#cello_get_fraud_analysis) via the [Cello MCP](/mcp/growth/use-cases).


# 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**

* [Integration Status](/guides/support/portal/integration-status) – Get a real-time health view of your integration
* [Event Feed](/guides/support/portal/event-feed) – Monitor and debug your integration events

## 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

<Note>
  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).
</Note>


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

<Info>
  If you don't see the **Partner Users** or **Partner Resources** pages, check that the **Sandbox / Production** toggle in the upper left of the portal is set to **Production**. Partner pages are only visible in Production mode. If you've switched to Production and the pages are still missing, contact Cello support to have the necessary permissions applied to your account.
</Info>

<img alt="Partner Users page with Add New Partner button" />

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.

<img alt="Add new partner form with email, campaign, and Product User ID fields" />

<Info>
  **What is the Product User ID?** It is the unique identifier your product already assigns to that user - the same ID you pass as `productUserId` when generating the JWT token and booting the Referral Component. You can look up an existing user's ID in the **Referrer Id** column of the Referrals dashboard in the Cello Portal.

  **When to provide it:** always fill in the Product User ID when the person you're inviting as a partner is already a user in your product. This ensures their existing referral code (`ucc`) is retained through the transition, so their referral link stays the same.

  If you do not specify the Product User ID, Cello automatically creates a new identifier, and the user will end up with two separate referral links: one inside your product and one in the Cello partner portal, with split referral tracking.
</Info>

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

<img alt="Partner registration email with sign up options" />


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

<img alt="Partner program overview" />

<Info>
  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
</Info>

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

<img alt="Partner portal interface overview" />

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.

<img alt="Partner Resources dashboard overview" />

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

<img alt="Add new guide interface" />

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

<img alt="Partner view of resources" />

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

***


# Support FAQ
Source: https://docs.cello.so/guides/support/faqs

Frequently asked questions about integrating, running, and troubleshooting Cello

## Partners & affiliate programs

<AccordionGroup>
  <Accordion title="How do I view affiliate stats in the Cello portal?">
    Switch to the **Partner Campaign** in the upper-right of the Cello portal. Your dashboard will filter to display the affiliate/partner program numbers. Note: ensure you have the toggle in the upper-left toggled to production. 
  </Accordion>

  <Accordion title="How can I provide marketing materials for the affiliates to use?">
    See [Partner resources](/guides/partners/partner-resources).
  </Accordion>

  <Accordion title="Can we automatically add partners/affiliates via API sync?">
    Partners and affiliates are added via the [Cello Portal](https://portal.cello.so/partners/management). There is no API endpoint for bulk partner creation today.

    For complex migrations or large partner onboarding, Cello works directly with customers to handle bulk imports. Contact your CSM to coordinate.
  </Accordion>

  <Accordion title="Is coupon-code-only tracking supported (without an affiliate link)?">
    Cello's attribution is link-based - referral links with a `ucc` parameter are the supported tracking method. Standalone coupon-code tracking (where a code is shared and attributed at checkout without a referral link) is not available today.

    If your referrers promote through channels where links aren't practical (podcasts, video, print), consider using a short, memorable referral URL instead. If coupon-code-only tracking is important for your program, share the use case with your CSM.
  </Accordion>

  <Accordion title="What is the Product User ID when adding a partner, and where do I find it?">
    The **Product User ID** is the unique identifier your product already assigns to that user - the same value you pass as `productUserId` when generating the JWT token and booting the Referral Component. It is not a Cello-generated ID.

    To look up an existing user's ID: go to the **Referrals** dashboard in the Cello Portal. The **Referrer Id** column shows the `productUserId` for each referrer.

    You should provide the Product User ID whenever the person you're inviting as a partner is already a user in your product. This links their new partner identity to their existing referrer identity, so their referral link (`ucc`) stays the same and their referral tracking remains unified. If you skip it, Cello creates a new identity and the user ends up with two separate referral links.
  </Accordion>

  <Accordion title="When I upgrade a user referrer to a partner, do they keep the same referral link?">
    In general, Cello is designed to be seamless across **user referrals** and **partner/affiliate referrals**:

    * Users access Cello via the in-product Referral Component.
    * Partners can access a separate Cello partner portal, and can also use the in-product Referral Component.
    * The same campaign code can be shared across your product and the partner portal. To do so: when adding the partner in the Cello admin portal, ensure the partner is mapped using their `productUserId` so they retain the same UCC/link across your product and the Cello partner portal.
  </Accordion>

  <Accordion title="When upgrading a referrer to a partner, does historical performance carry over?">
    If the partner is mapped correctly to the existing user via `productUserId`, the intent is for the partner to retain their current UCC and associated performance history across your product and the Cello partner portal.
  </Accordion>

  <Accordion title="When upgrading a referrer to a partner, do commissions change retroactively?">
    No. When a referrer is upgraded to a partner campaign, existing signups keep the reward terms from the campaign that was active when they signed up. Only new signups after the upgrade use the new campaign’s reward structure. This grandfathering is handled automatically.
  </Accordion>

  <Accordion title="Do we need to remove the referral widget when someone becomes a partner?">
    No. Partners can still use the Cello widget to access their referral link and rewards experience.
  </Accordion>

  <Accordion title="I don't see the Partner Users or Partner Resources pages in the Cello portal">
    The partner pages are only visible in **Production** mode. Check the **Sandbox / Production** toggle in the upper left of the portal and make sure it is set to **Production**. If the pages are still not visible after switching, contact Cello support to have the necessary permissions enabled on your account.
  </Accordion>
</AccordionGroup>

## Attribution & cookies

<AccordionGroup>
  <Accordion title="What is attribution?">
    Attribution is the process of tracking and linking new user signups and purchases back to the referrer who originally shared the referral link. It ensures referrers are correctly rewarded and that your referral analytics stay accurate.

    Cello's attribution works in four steps:

    1. **Referral link sharing** - referrers share links containing a unique referral code (`ucc` parameter)
    2. **Landing page capture** - your website or app captures and stores the `ucc` as a first-party cookie
    3. **Signup tracking** - new user registrations are linked to their referrer via the stored `ucc`
    4. **Purchase tracking** - revenue events are attributed back to the original referrer

    Attribution is available for both web and mobile signup flows. For mobile apps, the referral code is passed through deep-link attribution providers (e.g., Branch.io, AppsFlyer) so it persists through app store redirects and installation.

    **Related docs**

    * [Attribution introduction](/attribution/introduction)
    * [Web attribution](/attribution/for-web)
    * [Mobile attribution](/attribution/for-mobile)
  </Accordion>

  <Accordion title="Why is the Attribution Library required?">
    The Attribution Library ([Attribution JS](/sdk/client-side/attribution-js-introduction)) is a lightweight JavaScript library that captures the referral code (`ucc`) from referral links and stores it as a first-party cookie. This cookie persists for 3 months, which is critical because users often don’t sign up immediately - they may click a referral link, browse your site, leave, and return days later before converting.

    Without the library, the `ucc` parameter would be lost as soon as the user navigates away from the landing page URL, breaking attribution for these indirect signups.

    Beyond persistence, the library also provides APIs to:

    * **Retrieve the referral code** - `getUcc()` for passing into signup and purchase events
    * **Get the referrer’s name** - `getReferrerName()` for personalizing landing pages
    * **Access campaign config** - `getCampaignConfig()` for displaying referral discounts
    * **Manage cookie consent** - built-in methods for privacy compliance

    You can install it via an [embedded script tag](/sdk/client-side/embedded-script-tag) or [Google Tag Manager](/sdk/client-side/google-tag-manager).

    **Related docs**

    * [Attribution JS introduction](/sdk/client-side/attribution-js-introduction)
    * [Web attribution](/attribution/for-web)
  </Accordion>

  <Accordion title="Do I need the attribution library if I only want cookies stored?">
    You could technically store the `ucc` as a cookie yourself, but the Attribution Library ([Attribution JS](/sdk/client-side/attribution-js-introduction)) does significantly more than cookie storage:

    * **Automatic form injection** - the library auto-injects a hidden `ucc` field into signup forms, so attribution works without custom form logic
    * **API access** - provides `getUcc()`, `getReferrerName()`, and `getCampaignConfig()` methods for programmatic access to referral data, referrer personalization, and discount display
    * **Fraud detection signals** - the script collects telemetry that feeds into Cello's [fraud and self-referral detection](/guides/fraud-detection), which is not possible with a plain cookie
    * **Cross-session persistence** - stores the `ucc` as a first-party cookie with a 3-month lifetime, handling delayed and indirect signups automatically

    Skipping the library means you would need to manually parse the `ucc` from the URL, store it, inject it into forms, and lose fraud detection capabilities. For most integrations, using the library is the simpler and more reliable path.

    **Related docs**

    * [Attribution JS introduction](/sdk/client-side/attribution-js-introduction)
    * [Attribution JS usage & API](/sdk/client-side/attribution-js-usage)
  </Accordion>

  <Accordion title="Is the cookie with the Cello UCC available across pages/subdomains?">
    Yes. The Attribution Library stores the referral code in first-party cookies (`cello-referral` and `cello-productId`) that are scoped to your root domain. This means:

    * **Across pages** - the cookies are available on every page of your site, as long as the attribution script is installed on each page (recommended in the `<head>` tag site-wide)
    * **Across subdomains** - the cookies work across subdomains of the same root domain (e.g., `www.example.com` and `app.example.com`). Cross-subdomain attribution is supported natively

    The cookies persist for 3 months, so they survive across sessions and return visits.

    Note: cookies are **not** shared across different root domains (e.g., `example.net` and `example.app`). If your landing page and product use different root domains, see the FAQ below on cross-domain strategies.

    **Related docs**

    * [Manage cookie consent](/landing-pages/manage-cookies)
    * [Attribution JS introduction](/sdk/client-side/attribution-js-introduction)
  </Accordion>

  <Accordion title="We have different root domains for landing vs product. Will attribution work?">
    The Attribution Library stores the `ucc` in a first-party cookie scoped to the root domain where it was set. This means the cookie set on `example.net` is **not** automatically available on `example.app` - browsers enforce this as a security boundary.

    If your landing page and product use different root domains, here are your options (in order of preference):

    1. **Use the same root domain** (recommended) - host your landing page on a subdomain of your product domain (e.g., `www.example.app` for landing, `app.example.app` for the product). This makes attribution seamless with no extra work, since cookies are shared across subdomains of the same root domain.

    2. **Persist the `ucc` in URLs across domains** - install the Attribution Library on both domains and ensure all links between them append the `?ucc={ucc}` parameter. This way the `ucc` is recaptured by the Attribution Library when the user arrives on the second domain.

    3. **Build a custom cross-domain bridge** - implement server-side logic to store and forward the `ucc` when users transition between domains (e.g., pass it through your authentication or redirect flow so it’s available on the product domain at signup time).

    **Related docs**

    * [Web attribution setup](/attribution/for-web)
    * [Attribution JS introduction](/sdk/client-side/attribution-js-introduction)
  </Accordion>

  <Accordion title="Does Cello integrate with cookie consent management platforms (OneTrust, CookieBot, etc.)?">
    Yes. Cello's Attribution Library supports integration with cookie consent management platforms so that referral cookies are only stored after the user grants consent.

    **Supported platforms:**

    * **OneTrust** - fully supported. Cello enables the integration on their side; no setup required from you
    * **CookieFirst** - coming soon
    * **CookieBot** - coming soon
    * **Civic Cookie Control** - coming soon

    If your consent platform isn't listed above, you can use the **custom consent method** via the Attribution JS API:

    ```javascript theme={null}
    // After user grants consent
    window.CelloAttribution('allowCookies');

    // If user withdraws consent
    window.CelloAttribution('deleteCookies');
    ```

    This gives you full control to integrate Cello's cookie handling with any consent management platform or custom consent flow.

    **Related docs**

    * [Manage cookie consent](/landing-pages/manage-cookies)
    * [Attribution JS introduction](/sdk/client-side/attribution-js-introduction)
  </Accordion>

  <Accordion title="What is direct vs indirect signups?">
    * **Direct signup**: user clicks a referral link and signs up immediately.
    * **Indirect signup**: user clicks a referral link, navigates around, and signs up later from a different page.

    For both, ensure attribution rules are followed so the referrer’s UCC is tracked and rewards are correctly attributed.
  </Accordion>

  <Accordion title="Can we track purchases without requiring a prior signup event?">
    Yes, but Cello still needs to know *who* the referred user is before attributing a purchase. If you skip the standard signup flow, you'll need to send a `new-signup` or `sign_in` event via the [Cello API](/attribution/tracking-signups) before sending `invoice-paid` events - otherwise the purchase has no user to attribute to.

    A common use case is **existing-user attribution**, where a current user clicks a referral link and you want to credit the referrer for their next purchase. The recommended approach:

    1. **Check for a `ucc` on login** - not just on signup. Use `getUcc()` from the Attribution Library or read the `ucc` URL parameter directly.
    2. **Validate the `ucc`** - call Cello’s [Referral Codes API](/api-reference/referral-codes/fetch-referral-code-info) to confirm the code is valid and identify the referrer.
    3. **Prevent self-attribution** - compare the referrer’s `productUserId` with the logged-in user’s ID. If they match, ignore the `ucc`.
    4. **Store the `ucc`** - save it in your database linked to the user, so it’s available when sending events.
    5. **Send events to Cello** - send a `sign_in` event (to establish the attribution) followed by `invoice-paid` events as purchases occur.

    **Related docs**

    * [Track signups](/attribution/tracking-signups)
    * [Track purchases](/attribution/tracking-purchase)
    * [Fetch referral code info](/api-reference/referral-codes/fetch-referral-code-info)
  </Accordion>

  <Accordion title="How do I manually backfill attribution for a missed signup or purchase?">
    If a referral wasn’t automatically attributed - due to a technical issue, missing metadata, or a user dispute - you can manually backfill it. The exact steps depend on your integration type:

    **For Stripe or Chargebee webhook integrations:**

    1. Get the referrer’s `cello_ucc` from the [Cello Portal](https://portal.cello.so) and the new user’s `new_user_id` from your system.
    2. Add `cello_ucc` and `new_user_id` to the new user’s customer metadata in Stripe or Chargebee.
    3. Cello will receive a `customer.updated` (Stripe) or `customer_changed` (Chargebee) event automatically.
    4. If past invoices were already paid, resend the `invoice.paid` (Stripe) or `payment_succeeded` (Chargebee) events from within your payment platform’s dashboard.

    **For Cello API integrations:**

    1. Get the referrer’s `cello_ucc` and the new user’s ID.
    2. Resend the signup event via the [POST /events API](/api-reference/generic-events/send-event).
    3. Resend any past transaction events via the same API.

    If events cannot be resent via API, Cello Support can accept manual reports - contact [support@cello.so](mailto:support@cello.so) for report templates.

    **Related docs**

    * [Manual Attribution guide](/guides/attribution/manual-attribution)
    * [Track purchases](/attribution/tracking-purchase)
    * [Stripe webhook](/integrations/webhooks/stripe-webhook)
    * [Chargebee webhook](/integrations/webhooks/chargebee-webhook)
  </Accordion>

  <Accordion title="My flow is purchase first, signup later. Does that work?">
    Yes, this is a supported pattern. Cello can handle flows where the payment gateway customer is created at checkout (purchase) rather than at signup, as long as the referral metadata is attached within 7 days of the purchase.

    **How it works with Stripe:**

    1. User clicks a referral link and the `ucc` is captured by the Attribution Library.
    2. User completes a Stripe Checkout session, which creates a Stripe customer.
    3. After the checkout session completes, update the Stripe customer with `cello_ucc` and `new_user_id` metadata via `customer.update`.
    4. Cello receives the `customer.updated` event and uses it to establish the attribution.
    5. Even if the first `invoice.paid` event arrived before the metadata was added, Cello will retroactively attribute it once the customer is updated.

    **How it works with Chargebee:**
    Follow the same pattern - add `cello_ucc` and `new_user_id` to the Chargebee customer metadata after checkout. Cello will receive the `customer_changed` event.

    **How it works with Cello API:**
    If your payment gateway is Paddle, Recurly, or another provider, use the [POST /events API](/api-reference/generic-events/send-event) to send a `new-signup` event after the customer is created at purchase.

    **Related docs**

    * [Track signups - Option 3: customer created at purchase](/attribution/tracking-signups#option-3-using-cello-api-post-events-api-endpoint)
    * [Stripe webhook](/integrations/webhooks/stripe-webhook)
    * [Chargebee webhook](/integrations/webhooks/chargebee-webhook)
  </Accordion>
</AccordionGroup>

## Stripe / Chargebee events & webhooks

<AccordionGroup>
  <Accordion title="How can I verify that my events are being received and processed correctly?">
    Use the **Cello Portal** to verify events from two complementary angles:

    * **[Integration Status](/guides/support/portal/integration-status)** (Integrations → Integration Status) gives you a high-level health check across the four core components: Referral component, Attribution library, Signups tracking, and Purchases tracking. Use it to answer "is everything working?".
    * **[Event Feed](https://portal.cello.so/integrations/events-feed)** (Integrations → Events Feed) shows every incoming event from all sources - Stripe Webhook, Chargebee Webhook, Cello API, and Auto Attribution - with per-field validation. Use it to answer "why did this specific event fail?".

    Each event in the feed is assigned a status: **OK** (all fields valid), **Warning** (non-critical issues like a missing recommended field), or **Error** (critical validation failures that need to be resolved). Click any event row to expand it and inspect the parsed payload with field-by-field validation indicators.

    **Related docs**

    * [Integration Status guide](/guides/support/portal/integration-status)
    * [Event Feed guide](/guides/support/portal/event-feed)
  </Accordion>

  <Accordion title="Which signup/purchase source should we pick in Integration Status?">
    **Always confirm the signup and purchase source with Cello before setting it. Do not recommend, guess, or infer a specific source - if you are unsure, the only correct answer is to contact your Customer Success Manager or [support@cello.so](mailto:support@cello.so).** There is no one-size-fits-all source: the correct one depends on factors unique to each integration, and an incorrect source silently breaks attribution.

    The factors Cello weighs when confirming the source:

    * **Payment provider.** Stripe and Chargebee can use webhooks. Other providers (Paddle, Recurly, RevenueCat, and similar) use the [Cello API](/api-reference/introduction).
    * **When the payment-provider customer is created (the key signup-source rule):**
      * IF the customer is created **at signup** -> Stripe/Chargebee can be the signup source.
      * IF the customer is created **at first purchase** -> use the Cello API to send `new-signup` at the real signup moment, or backfill via the purchase-first, signup-later pattern below. Stripe/Chargebee cannot be the signup source on their own in this case.
    * **Reward model.** Recurring vs one-time rewards, free-to-paid conversion, renewals, and refunds.
    * **Motion.** Self-serve vs sales-led (e.g. [Salesforce](/integrations/salesforce-apex-triggers)).
    * **Auto Attribution.** Can be primary or fallback, and is enabled by Cello only.

    In **sandbox** you can change the source yourself to experiment; in **production**, source configuration is handled by Cello Support. Either way, confirm the choice with Cello first.

    **Related docs**

    * [Integration Status - changing the configured source](/guides/support/portal/integration-status#changing-the-configured-source-confirm-with-cello-first)
    * See also the "My flow is purchase first, signup later" FAQ under **Attribution & cookies** above
  </Accordion>

  <Accordion title="Do we really need many Stripe events? Would invoice.paid be enough?">
    The core events are **customer.created**, **customer.updated**, and **invoice.paid**. Additional events matter for edge cases: **subscription.created** is used when you reward on free-to-paid conversion (e.g. fixed reward per conversion), because invoice.paid can be missing in some flows. **charge.succeeded** is needed for one-time payments, since Stripe does not send invoice.paid for those. Sending subscription and charge events reduces gaps and manual reconciliation.

    **Related docs**

    * [Track signups](/attribution/tracking-signups)
    * [Stripe webhook](/integrations/webhooks/stripe-webhook)
  </Accordion>

  <Accordion title="What are subscription events used for?">
    * **created**: detect signups, free-to-paid conversion, and capture subscription details
    * **updated**: same as **created**; they additionally detect plan/seat changes, downgrades, expansions, churn
    * **deleted** (or **canceled**): detect churn for paid subscriptions
  </Accordion>

  <Accordion title="Why send subscription events if we already send invoice.paid?">
    Subscription events help when invoice flows and subscription state diverge (e.g. pricing changes, discounts, failed payments). They improve reconciliation and reward accuracy.
  </Accordion>

  <Accordion title="What is invoice.paid used for?">
    It is usually the main “payment received” signal: it drives recurring payouts, reward calculation, referral ARR calculation. If a payment fails, you may get subscription events without invoice.paid. For one-time or fixed-amount transactions, invoice.paid may still be the primary event depending on your setup.
  </Accordion>

  <Accordion title="What is customer.created / customer.updated used for?">
    * **customer.created**: typically used as the signup signal when the customer is created at signup
    * **customer.updated**: used when you add or change attribution metadata (e.g. `cello_ucc`, `new_user_id`) after the customer already exists (e.g. at first purchase)
  </Accordion>

  <Accordion title="What is charge.succeeded used for?">
    It indicates a payment. For subscriptions, invoice.paid is usually preferred for interval logic. For **one-time payments**, Stripe does not send invoice.paid, so charge.succeeded (or equivalent) is what Cello uses.
  </Accordion>

  <Accordion title="What is charge.refunded used for?">
    It signals refunds/cancellations so Cello can correct attribution and reward outcomes (e.g. cancel or adjust pending rewards).
  </Accordion>

  <Accordion title="What events do we need if we use Cello API only?">
    * Send signup events via API.
    * Send at least purchase events (e.g. invoice-paid equivalent) via the Cello API.
    * Include amount (in **cents**), currency, and payment frequency (monthly vs annual) where applicable.
    * Send renewal purchase events for continuous rewarding and referral ARR computation.

    **Related docs**

    * [API reference](/api-reference/introduction)
    * [Track signups](/attribution/tracking-signups)
    * [Track purchases](/attribution/tracking-purchase)
  </Accordion>

  <Accordion title="What events do we need if we use Stripe or Chargebee webhooks only?">
    Connect the Stripe or Chargebee webhooks, add `cello_ucc` and `new_user_id` to the **customer object** (on customer.created or customer.updated, depending on when you create the customer). That customer update is the signup signal; subscription and invoice events are then used automatically for rewards.

    **Related docs**

    * [Track signups](/attribution/tracking-signups)
    * [Stripe webhook](/integrations/webhooks/stripe-webhook)
    * [Chargebee webhook](/integrations/webhooks/chargebee-webhook)
  </Accordion>

  <Accordion title="What if we use a payment provider other than Stripe/Chargebee?">
    Use the **Cello API** from your backend to send conversion events (signups and purchases). You keep full control over which events are sent. First time purchases and renewals have to be shared as purchase events.

    **Related docs**

    * [Integration overview](/integration-overview)
    * [API reference](/api-reference/introduction)
  </Accordion>

  <Accordion title="Which user ID should we send as new_user_id / productUserId?">
    Send the **new user (referee)** ID. The referrer is identified via the UCC in the referral link; the referee is identified by this ID.
  </Accordion>

  <Accordion title="Will connecting Stripe webhooks affect our payment architecture?">
    No. Cello only **listens** to webhook events. Your payment flow and architecture stay unchanged.
  </Accordion>

  <Accordion title="Are accessKeyId and productId the same thing?">
    In the **Stripe webhook** context they are used interchangeably. Everywhere else (API, portal, docs) the product identifier is referred to as **productId**.
  </Accordion>

  <Accordion title="Reward amount is less than expected. What could be wrong?">
    Check that amounts are sent in **cents** (or smallest currency unit). For example, 100 USD should be **10000**. If you send 100, Cello treats it as 1.00 USD.
  </Accordion>

  <Accordion title="Stripe can’t send webhook events to our server. What should we check?">
    Verify that the **Webhooks** section of the Cello Portal is populated with the correct Stripe signing secret. Without it, events will fail to authenticate. Ensure the signing secret matches the environment (staging vs prod). In a next step verify in your **Stripe dashboard** if the webhook url is correct and active. In the webhook event feed in Stripe's dashboard you can check if an event resulted in an error. You can also check the [Event Feed](https://portal.cello.so/integrations/events-feed) in the Cello Portal to see if events are arriving.
  </Accordion>

  <Accordion title="What events are needed when using Cello API plus Stripe or Chargebee webhooks?">
    * Send `new-signup` events via the Cello API.
    * Connect Stripe or Chargebee webhooks.
    * Add `cello_ucc` and `new_user_id` to the **customer object** (on `customer.created` or `customer.updated`).
    * Subscription and invoice events are detected automatically once the above is triggered - no need to add `cello_ucc` and `new_user_id` to subscription or transaction events.
  </Accordion>

  <Accordion title="Is there deduplication for invoice-paid events (e.g. by invoiceId) when using Cello API?">
    There is no fully automated deduplication (similar to idempotency rules) yet. However, Cello has simple deduplication logic based on `new_user_id` + time difference + `invoiceId` (if provided).

    * The current time-difference threshold for detecting duplicate `invoice-paid` events is **one minute**.
    * Flagged events go through manual review, and the threshold is adjusted if there are too many false positives.
    * There are scenarios where a customer can buy multiple subscriptions within a minute, so the threshold is kept conservative.
    * If you can send an `invoiceId`, this significantly improves deduplication accuracy since it becomes the primary identifier for detecting duplicates.
  </Accordion>
</AccordionGroup>

## Rewards, payouts, taxes & billing

<AccordionGroup>
  <Accordion title="What payout methods are supported (besides PayPal/Venmo)?">
    Currently, payouts are primarily via **PayPal** (and **Venmo** for the US on request). Bank transfer/SEPA are not offered today.
  </Accordion>

  <Accordion title="How does Cello invoicing work?">
    Most customers receive two separate invoices: one for the Platform Fee and one for the Advertising Fee, issued as part of Cello's Advertising Services. Invoices are typically issued monthly, though frequency and timing may vary based on your specific arrangement. For questions about your invoicing setup, contact your Cello representative.
  </Accordion>

  <Accordion title="When will we receive invoices?">
    Invoices are routinely sent around the middle of the month. Timing may differ based on your agreement or customer setup; your Cello contact can confirm the schedule that applies to you.
  </Accordion>

  <Accordion title="How should we handle refunds and reward clawbacks?">
    Cello campaign rules are designed to mitigate refund risk. Rewards are spaced and delayed so that during the delay period no payment is made, and when a subscription is refunded or canceled, future payouts can be automatically stopped. Programs set up with the recommended delay and spacing significantly reduce the risk of incorrect payouts.

    If you believe rewards have been incorrectly issued, contact Cello support to discuss your options.
  </Accordion>

  <Accordion title="How do we apply the referee discount if we don’t use the Cello↔Stripe discount integration?">
    Referee discounts are usually implemented on your side. Many customers use Stripe discounts/coupons for this.

    **Related docs**

    * [New user discounts](/guides/user-experience/new-user-discounts)
  </Accordion>

  <Accordion title="If a referrer churns from our product, do their rewards stop?">
    Referral rewards are tied to the referred customer's activity, not the referrer's subscription status. If a referrer is no longer a user of your product, they can continue to access their referral dashboard and claim rewards through the Cello portal, provided they have access to the email address they used to register for rewards.
  </Accordion>

  <Accordion title="What happens if a referee cancels and later resubscribes? Does the referrer keep earning?">
    If the payment record is the same and the UCC metadata is preserved, rewarding can continue. One-time bonus rewards typically do not repeat.
  </Accordion>

  <Accordion title="What happens when a referred user cancels an annual subscription?">
    If rewards are recurring percentage-based, the monthly reward typically stops when the subscription stops.
  </Accordion>

  <Accordion title="If a customer prepays annually, is the reward paid on the full year or prorated?">
    By default, rewards are prorated with the referrer reward spread over the payment period rather than paid on the full year upfront. Spaced rewards reduce risk and the need to introduce long payout delays, while also driving better referrer engagement through regular, recurring payouts. Some customers opt for front-loading, but this is generally not recommended as it reduces these benefits.
  </Accordion>

  <Accordion title="Can we cap rewards by time instead of total reward amount?">
    Cello's campaign design favors capping based on reward amounts rather than time horizons. User research across referral programs has shown that time-based caps are less well received by referrers and can reduce sharing rates.

    If you have a specific requirement around time-based caps, discuss it with your CSM to explore what configuration options are available.
  </Accordion>

  <Accordion title="What currencies are supported for campaigns?">
    Cello supports multiple currencies for setting a campaign’s primary currency (configured in the portal).
  </Accordion>

  <Accordion title="What currencies are supported for reward payouts?">
    Rewards are typically paid in the local currency supported by the referrer’s PayPal/Venmo account. Additional payout methods may be added in the future.
  </Accordion>

  <Accordion title="What happens for users from unsupported payout countries? How should we handle them?">
    Users from countries not on the [supported payout list](/guides/user-experience/overview#reward-countries-and-payout-methods) (e.g. Mexico, Argentina) will not be able to set up a payout method - their country won't appear in the payout country dropdown. This is due to PayPal-side restrictions and compliance, tax, or regulatory rules. Cello cannot issue payouts to unsupported countries.

    **Two approaches:**

    1. **Hide the widget for unsupported countries** - pass `productUserCountryCode` in `cello.boot()`. If the country is unsupported, the component won't be shown to that user, preventing a confusing experience where they can share and earn but not receive payouts.

    2. **Show the widget to everyone** - simpler to implement. Users in unsupported countries can still share and earn, but won't be able to complete payout setup. This avoids incorrectly hiding the widget from users who might actually be eligible.

    **Why the hide approach is imperfect:** `productUserCountryCode` reflects the country in your system, which may differ from the user's actual PayPal payout country. Three scenarios:

    * Product country unsupported, payout country also unsupported → hiding works correctly.
    * Product country supported, payout country unsupported → user sees the widget and can share/earn, but can't receive payouts. No way to prevent this upfront.
    * Product country unsupported, payout country supported → worst case: user is incorrectly hidden even though they could use Cello and receive payouts.

    The right choice depends on how accurately your system reflects your users' actual locations.

    **Edge case - PayPal account country vs. physical location:** A user may live in an unsupported country (e.g. Argentina) but hold a PayPal account registered in a supported country (e.g. Brazil). They should enter the address matching their PayPal account's registered country in the widget. Cello cannot issue payouts to unsupported countries regardless of physical location.
  </Accordion>

  <Accordion title="Can we restrict payment countries shown to referrers (e.g. US only)?">
    The country list shown to referrers during payout setup is not restricted because referrers and partners can earn rewards from any country they participate in. Restricting the list could prevent eligible referrers from setting up their payout details and receiving rewards.

    If you need to limit who can participate in your referral program, you can control eligibility on your side by restricting which users see the Referral Component (e.g., only booting the Cello SDK for users in eligible regions).
  </Accordion>

  <Accordion title="Rewards earned shows $0 in the widget. When does that update?">
    The “Rewards earned” indicator reflects how much has been **credited to a PayPal account**. Until a referrer enters valid PayPal credentials, it will show \$0. Attributed rewards still accumulate in the rewards list below.
  </Accordion>

  <Accordion title="Can end users see a dashboard of their referrals and rewards?">
    Referrers can see link views, signup history, and reward history in the **rewards tab** inside the referral widget.

    For a more detailed dashboard, the Partner add-on provides a unified view of user referrals and affiliate programs on a single platform - with no extra technical setup required.
  </Accordion>

  <Accordion title="Successful referrals are missing from the customer view. What should I check?">
    Referral activity should be visible in the Cello Portal dashboards. If data is missing, check the following:

    * Open [Integration Status](/guides/support/portal/integration-status) and confirm the relevant tracking component (Signups or Purchases) is **Connected**. If it shows **Connected with warnings** or **Not connected**, that's where the problem is.
    * Check the [Event Feed](https://portal.cello.so/integrations/events-feed) to verify events are arriving with the correct field values and passing validation
    * Verify that signup and purchase events are being sent correctly and contain the expected `cello_ucc` and `new_user_id` values
    * Confirm that the `productUserId` is consistent - if the same user signs up via different channels with different IDs, attribution may not match
    * Check whether there have been any recent code changes that could affect how events are sent to Cello
  </Accordion>

  <Accordion title="Do referrers handle taxes themselves? Do we need to explain tax implications?">
    Referrers are responsible for determining and complying with their own tax obligations. Cello may provide general informational materials and, where applicable, payout statements, credit notes, or similar documentation relating to rewards paid through the platform. Such information and documentation are provided for informational and record-keeping purposes only, are not exhaustive, and do not constitute tax, legal, or financial advice.
  </Accordion>

  <Accordion title="When exactly are invoices generated, and how do cancellations affect them?">
    An invoice may be triggered within the first **3–5 days** after the close of the previous month. For cancellations, the corresponding credit-note rewards are triggered **14 days later**, which means they appear on the following month’s invoice.

    Note: this adjustment only applies to the invoice covering rewards that Cello pays to referrers on your behalf - not to the platform/subscription fee invoice.
  </Accordion>

  <Accordion title="When referrers add their payment details, when exactly is the reward applied?">
    Cello rewards users on a daily basis, barring any additional reward-delay policy you have configured for your program. Because rewarding runs daily, it typically takes only a few days for referrers to receive their reward (assuming they add their payment details promptly).
  </Accordion>

  <Accordion title="Is the payout always in USD, or can it be in EUR/GBP based on the referrer's preference?">
    * Cello allows you to select only **one default currency** for your rewards (configured in the Campaigns tab).
    * Cello covers transfer and transaction fees, including currency conversion from the subscription event currency back to your nominated default currency.
    * Referrers receive rewards in their PayPal account in your default currency. If they convert to a different currency (e.g. their local one), the exchange rate depends on PayPal's currency exchange and may include additional PayPal fees.
  </Accordion>

  <Accordion title="I want to move my referrers to a higher revshare or reward, or move a user-led referrer to a higher partner campaign plan">
    Grandfathering of the prior campaign when a referrer moves to a new one is handled automatically.

    When a referee signs up through a referral link, the campaign rate at the time of signup is locked in for that referral. If you later move the referrer to a new campaign:

    * **Existing signups** keep the reward structure from the campaign that was active when they signed up
    * **New signups** (after the move) use the new campaign's reward structure

    For major campaign updates, coordinate with the Cello team to ensure the transition is configured correctly for your program.
  </Accordion>

  <Accordion title="I want to move a referrer from one Partner Campaign to another">
    Moving a referrer between Partner Campaigns is handled automatically. The referrer keeps the same referral link, and:

    * **Existing signups** retain the reward terms from the original campaign
    * **New signups** (after the move) use the new campaign's reward structure

    No data migration or new referral links are required. For major campaign updates, coordinate with the Cello team to ensure the transition is configured correctly for your program.
  </Accordion>

  <Accordion title="Can we implement a reward cap based on a time threshold AND/OR an amount ceiling?">
    Cello's campaign design favors capping based on reward amounts rather than time horizons. User research across referral programs has shown that time-based caps are less well received by referrers and can reduce sharing rates.

    If you have a specific requirement around time-based caps, discuss it with your CSM to explore what configuration options are available.
  </Accordion>
</AccordionGroup>

## Notifications & emails

<AccordionGroup>
  <Accordion title="If a referrer earns a reward but hasn’t set up payout details, will they be prompted?">
    Yes. Referrers will see an in-product notification prompting them to add payout details. If emails are enabled, they may also receive an email.

    If a reward payment has not been received by one of your users, check that they have added payment details. Verify that account details, country, and other mandatory fields are filled out in the correct format.
  </Accordion>

  <Accordion title="Can Cello provide sample email notifications?">
    All notification templates can be reviewed in the [Cello Portal](https://portal.cello.so/setup/notifications).
  </Accordion>

  <Accordion title="Can email templates be customized?">
    Yes - you can customize email templates self-serve directly in the [Cello Portal](https://portal.cello.so/setup/notifications). Open any email notification row to bring up the preview panel. Editable elements are highlighted on hover - click to change them.

    The following can be customized:

    * **Logo** - upload your company logo
    * **Presentation image** - upload a hero image shown prominently in the email body
    * **CTA link** - set the URL for the main call-to-action button

    The **Welcome email** has one additional option: a second CTA link, letting you point new users to a specific page alongside the referral program link.

    Changes apply across all email types at once. See [Email template customization](/guides/user-experience/referral-notifications-and-emails#email-template-customization) for full details.

    For changes to email body copy or wording, contact your Customer Success Manager.
  </Accordion>

  <Accordion title="How do I change the logo or image in my emails?">
    Go to **Notifications** in the [Cello Portal](https://portal.cello.so/setup/notifications) and click any email row to open the preview panel. Hover over the logo or image - a prompt will appear to click and replace it. Your changes apply across all email types automatically.
  </Accordion>

  <Accordion title="When are welcome emails triggered?">
    Welcome emails are typically sent to existing users after the referral program goes live, as well as to any new user who signs up after the program has gone live. 

    Common behavior:

    * Sent on the 6th day after a new user first signs up to introduce the referral program and its details.
    * Includes the referral link.
    * Sent only once per user.\
      \
      Please review the [notifications tab](https://portal.cello.so/setup/notifications) in portal for copy and timing. 
  </Accordion>

  <Accordion title="If a user views the widget in another language (example: French or German), will their emails match that language?">
    Email language is generally based on the last language used in the widget. Supported languages include English, German, Spanish, French, Dutch, Italian, Portuguese, Japanese, Danish, Slovak, and Romanian (more may be added on request).\
    \
    Enabling of email text in different languages requires config customization on the Cello side. Please coordinate with your Customer Success Manager for the additional languages required.
  </Accordion>

  <Accordion title="Why can’t we keep the notification dot always visible?">
    The dot is designed as an alerting mechanism to bring users into the widget when there’s something new. By design, it disappears once the user has seen the update.\
    \
    What we have seen work well for other customers are small "NEW" stickers on the right side of the menu items.
  </Accordion>

  <Accordion title="How do announcements, dots, and welcome/view emails work (typical timing)?">
    Typical sequence (often with \~1 day delay):

    * `welcome-dot`: after first boot if user remains inactive
    * `welcome-announcement`: a few days after first activity (or after the welcome-dot is displayed)
    * `welcome-email`: about one week after first boot. All other emails are transactional, meaning they are only sent in order to update the referrer on their referral activity.

    Note: actual timing can vary with payout delays and fraud/self-referral review. Please review the [notifications tab](https://portal.cello.so/setup/notifications) in portal for copy and timing.
  </Accordion>

  <Accordion title="My announcement is not showing even though showAnnouncement returns a fulfilled promise. What's wrong?">
    Most common cause: your **Announcement Selector** matches more than one element, and Cello (which uses `document.querySelector`) anchored the announcement to a hidden or zero-sized one. A fulfilled `showAnnouncement` promise only means the SDK accepted the call - it does **not** mean the announcement is visible.

    Run this in the browser console on the page where the announcement should appear:

    ```javascript theme={null}
    document.querySelectorAll("<your-announcement-selector>")
    ```

    * If the result is **more than one element**: narrow the selector. Cello uses the **first match in DOM order**, which may be a wrapper `<li>` or `<span>` with no layout box. Use a parent prefix or an `id` to target exactly one visible element.
    * If the result is **one element**: check `document.querySelector("<your selector>").getBoundingClientRect()`. If `width` or `height` is `0`, the class is on a wrapper, not the visible element - move the class/attribute to the icon or button you actually want anchored.
    * If the result is **zero elements**: the element doesn't exist when the announcement renders. Confirm it exists before `cello.boot()` and check `#`, `.`, `[]` prefix correctness.

    Update **Announcement Selector** in [Referrer Experience](https://portal.cello.so/setup/referrer-experience) once you have a selector that returns exactly one visible element.

    See [Troubleshooting: announcement not showing](/referral-component/custom-launcher#troubleshooting-announcement-not-showing) for the full diagnostic checklist and selector specificity examples.
  </Accordion>

  <Accordion title="How do I hide the notification badge?">
    Add `data-cello-badge="false"` to your custom launcher HTML element:

    ```html theme={null}
    <button
      id="your-launcher-element"
      data-cello-badge="false"
    >
      Invite a friend
    </button>
    ```

    This hides the badge while keeping the element clickable. See [Configure notification badge](/referral-component/custom-launcher#configure-notification-badge) for all options.

    **Common confusion:** there is no `hideDefaultBadge` boot option - this does not exist in the Cello JS SDK. The `hideDefaultLauncher` boot option is different - it hides the **entire default Cello button**, not just the badge.
  </Accordion>

  <Accordion title="The notification badge position is incorrect. How do I fix it?">
    You can test the notification badge by opening your own referral link. Common causes of incorrect positioning:

    * The badge is added on the menu level instead of the menu-item level.
    * The badge is positioned `absolute` but lacks a `relative` parent. Set the menu-item container to `position: relative`.
  </Accordion>

  <Accordion title="How are notifications managed overall? What is the notification logic?">
    Cello notifications fall into two categories:

    1. **In-product**: announcement banners and badge dots displayed inside the widget.
    2. **External**: emails (welcome, reward earned, first-view, etc.).

    These notifications and their triggers are designed to work alongside your existing product engagement touchpoints in a seamless way.
  </Accordion>

  <Accordion title="How can we subscribe to Cello release notes and new features?">
    Cello does not currently send out emails for new features or release notes. Reach out to your Cello contact for the latest updates.\
    \
    If we have major updates, we often post about them directly in a shared slack channel. We also have this section in our docs for updates: [Changelog](https://docs.cello.so/changelog)
  </Accordion>
</AccordionGroup>

## Fraud, self-referrals & abuse

<AccordionGroup>
  <Accordion title="What is the self-referral policy?">
    Cello provides automated capabilities to detect and mitigate self-referrals and fraudulent behavior. You can review marked referrals in our Cello Portal.

    **Related docs**

    * [Fraud detection](/guides/fraud-detection)
  </Accordion>

  <Accordion title="Can a rejected referral be reversed?">
    Yes. Reversals are done manually; coordinate with Cello support.
  </Accordion>

  <Accordion title="How do you handle abuse/self-referrals?">
    Cello uses multiple signals (including data you provide, e.g. emails) and behavioral patterns to detect likely self-referrals. High-certainty cases can be auto-rejected; others are flagged for review in the portal, where you can accept or reject.

    **Related docs**

    * [Fraud detection](/guides/fraud-detection)
  </Accordion>

  <Accordion title="Do you use hashed IP/fingerprinting to detect abuse?">
    Cello uses anonymized signals and patterns to detect suspicious behavior (e.g. matching anonymous identifiers across referrer and referee journeys). Exact methods may change over time.

    **Related docs**

    * [Fraud detection](/guides/fraud-detection)
  </Accordion>

  <Accordion title="If an account is suspended for fraud, will the referrer see that in the widget?">
    Currently, the widget may not show a detailed reason. In some cases, communication may happen via the referrer’s payout email (PayPal/Venmo).
  </Accordion>

  <Accordion title="How does the self-referral detection system work?">
    If a new user converts to a paying user, Cello looks at multiple data points before issuing a reward. These data points are checked for both sides:

    1. The **new user** (referred person).
    2. The **referrer** based on the **UCC** the new user used.

    These datapoints are compared to detect cases where the referrer and referred user are the same person or repeating pattern is used to abuse the program.
  </Accordion>
</AccordionGroup>

## Integrations, SDKs & implementation

<AccordionGroup>
  <Accordion title="What is the Cello Referral Component?">
    The Referral Component is an embeddable UI that integrates directly into your application, giving logged-in users a complete referral experience. It is powered by the [Cello JS SDK](/sdk/client-side/cello-js-introduction) and is separate from [Attribution JS](/sdk/client-side/attribution-js-introduction), which handles referral tracking on landing pages.

    The component provides:

    * **Referral link sharing** - users can copy their link, share via social media, email, or QR code
    * **Progress tracking** - real-time dashboard showing clicks, signups, and earned rewards
    * **Reward payouts** - automated payouts via PayPal, Venmo, and other methods
    * **Notifications** - in-app and email alerts for referral activity and milestones
    * **Multi-language support** - 10+ languages with automatic detection
    * **Dark mode** - light and dark themes with configurable colors per theme

    It can be added as a floating button or integrated into your existing navigation using a [custom launcher](/referral-component/custom-launcher). Native SDKs are available for web, iOS, Android, and React Native.

    Integration requires three steps: load the SDK, generate a JWT token server-side, and boot the component with the user’s details.

    **Related docs**

    * [Referral Component introduction](/referral-component/introduction)
    * [Quickstart](/referral-component/quickstart)
    * [Custom launcher](/referral-component/custom-launcher)
  </Accordion>

  <Accordion title="Which programming languages/frameworks are supported?">
    Cello is framework-agnostic. The [Cello JS SDK](/sdk/client-side/cello-js-introduction) is a browser-based JavaScript library that works with any web framework whose output is HTML/JavaScript, including:

    * **React**, **Next.js**, **Vue**, **Angular**, **Svelte**, and vanilla JavaScript

    For **server-side rendering** frameworks (e.g., Next.js), Cello interactions must occur client-side - the SDK runs in the browser and cannot be initialized server-side. For **Angular** specifically, avoid using `<body>` as your AppRoot element to prevent a race condition with Cello’s DOM injection (see the [Angular notes in the quickstart](/referral-component/quickstart#do-you-support-angular)).

    For **mobile apps**, native SDKs are available:

    * [iOS SDK](/sdk/mobile/ios) - Swift/Objective-C with CocoaPods and SPM
    * [Android SDK](/sdk/mobile/android) - Kotlin/Java with Gradle
    * [React Native SDK](/sdk/mobile/react-native) - cross-platform mobile
    * [Flutter SDK](/sdk/mobile/flutter) - cross-platform mobile

    **Related docs**

    * [Cello JS SDK introduction](/sdk/client-side/cello-js-introduction)
    * [Quickstart](/referral-component/quickstart)
    * [Mobile SDK introduction](/sdk/mobile/introduction)
  </Accordion>

  <Accordion title="Can we remove the Cello branding?">
    No - Cello branding on the Referral Component is required and cannot be removed. This is primarily a trust and compliance requirement, not advertising.

    When referrers receive reward payouts, the transaction appears on their bank or PayPal account as a payout **from Cello**. The branding in the widget ensures users understand that the referral program is powered by Cello before they receive a payout. Without it, users may not recognize the payment and could flag it as fraud or issue chargebacks - which can harm both your referral program and your referrers.

    The branding is designed to be non-intrusive. While the Cello logo cannot be removed, the Referral Component inherits your app’s theming - including separately configurable light and dark mode colors - and many other aspects of the UI can be customized through the [Cello Portal](/guides/user-experience/overview).
  </Accordion>

  <Accordion title="Can we customize widget text and UI?">
    The Referral Component splits into two buckets: visual configuration that you do self-serve in the [Cello Portal](https://portal.cello.so), and copy/text changes that are managed by Cello on request.

    **Self-serve in the Portal:**

    * **Brand colors** - primary color, Cello button color, Fab icon color, and notification badge color, with separate values for light and dark mode
    * **Button style and position** - choose from 3 styles, set screen position, or use a [custom launcher](/referral-component/custom-launcher) integrated into your own menu
    * **Component type** - display as a pop-up or a modal, with configurable position
    * **Sharing options** - enable/disable link copy, social sharing (Twitter, LinkedIn, email), and QR codes
    * **Payment methods** - configure PayPal, Venmo, or other payout options for referrers
    * **Announcement display style** - choose between toasts, banners, or anchored announcements
    * **Language switching at runtime** - language enablement itself is configured by Cello, but the SDK exposes [`language`](/sdk/client-side/cello-js-usage#cellobootoptions) and [`changeLanguage`](/sdk/client-side/cello-js-usage#changelanguagelanguage) to switch between enabled languages

    **Requires a request to Cello (not self-serve):**

    * **Widget text** - onboarding steps, offer description, button labels, and any other in-widget copy
    * **New User Banner copy** - banner message and CTA wording
    * **Announcement text content**
    * **Email body copy**
    * **Translated copy in any enabled language** - Cello maintains translations centrally; customers do not edit translation strings directly
    * **Default language for your product** - English by default; contact support to change it
    * **Enabling additional languages** beyond what's already enabled for your product

    Why this split exists: Cello maintains consistent copy across 10+ languages and many reward structures, so copy changes are reviewed and rolled out by the Cello team. To request a copy change, email [support@cello.so](mailto:support@cello.so) or message your CSM with the surface, the current text, and the proposed new text (and the language(s) it should apply to).

    **Related docs**

    * [Configuring Referral Component](/guides/user-experience/configuring-referral-component)
    * [User experience overview](/guides/user-experience/overview#texts-and-language)
    * [Setting up campaigns](/guides/campaigns/setting-up-campaigns)
  </Accordion>

  <Accordion title="Can we update or customize copy anywhere in Cello (widget, banner, announcements, emails)?">
    No - copy updates are **not self-serve** in Cello. This applies to **all** user-facing text: the Referral Component (widget) onboarding and offer description, the New User Banner message, announcement text, and email body copy. Cello maintains consistent copy across customers to support 10+ languages and multiple reward structures.

    What you **can** configure self-serve in the [Portal](https://portal.cello.so/setup/notifications):

    * **Enable or disable** specific notification types (alerts, announcements, emails)
    * **Choose announcement display style** - toasts, banners, or anchored to your launcher
    * **Configure the activation campaign** - recurring announcements to re-engage inactive referrers
    * **Set reward amounts and program details** - which flow into the standardized email templates automatically
    * **Email template visual elements** - logo, hero/presentation image, and CTA link (see [Email template customization](/guides/user-experience/referral-notifications-and-emails#email-template-customization))
    * **Enable/disable** the New User Banner and adjust any styling options exposed in the Portal

    What requires Cello involvement:

    * **Widget text** - onboarding steps, offer description, button labels, in-widget copy
    * **New User Banner copy** - banner message and CTA wording
    * **Announcement text content**
    * **Email body copy** (e.g., "How It Works" page, reward email wording)
    * **Translated wording** in any enabled language - translations are managed centrally by Cello

    To request a copy change, email [support@cello.so](mailto:support@cello.so) or message your CSM with the surface (widget / banner / announcement / email), the current text, the proposed new text, and the language(s) the change should apply to.

    Based on Cello’s experience across hundreds of programs, modifications to email or announcement copy have minimal impact on referral performance. The biggest drivers of success are creating more impactful in-product touchpoints, such as Moments of Delight and deeper mobile app integration.

    **Related docs**

    * [Referral notifications and emails](/guides/user-experience/referral-notifications-and-emails)
    * [Configuring Referral Component - text and copy](/guides/user-experience/configuring-referral-component#customize-text-and-copy)
    * [User experience overview](/guides/user-experience/overview#texts-and-language)
  </Accordion>

  <Accordion title="Can we change placement/style of the landing/referral messages?">
    Yes - the referral landing page experience is highly customizable. You control the landing page itself, and Cello provides several approaches for the referee signup flow:

    1. **Dedicated landing page** (recommended) - build a custom page optimized for referral conversions. Dedicated pages have shown up to **2x higher conversion rates**. You have full control over layout, design, messaging, and CTAs.

    2. **Home page with inline personalization** - use your existing home page and add referral-specific personalization (referrer name, discounts) directly into your headline and CTA using the Attribution JS API (\`getReferrerName()\`, \`getCampaignConfig()\`).

    3. **Home page with New User Banner** (no code) - add the Cello attribution script and enable the New User Banner in the [Cello Portal](https://portal.cello.so/setup/new-user-experience). The banner automatically displays personalization and discount info to visitors arriving via referral links.

    For the **Referral Component** (the in-app widget for logged-in referrers), you can configure its placement (floating button position or [custom launcher](/referral-component/custom-launcher)), display type (pop-up or modal), and brand colors in the Portal.

    For adjustments beyond what’s available in the Portal, contact your CSM or the Cello product team with screenshots and the desired behavior.

    **Related docs**

    * [Optimizing referral landing pages](/guides/user-experience/optimizing-landing-pages)
    * [Personalizing referrals](/guides/user-experience/personalizing-referrals)
    * [Configuring Referral Component](/guides/user-experience/configuring-referral-component)
  </Accordion>

  <Accordion title="How do we validate a UCC?">
    Use the Referral Codes API endpoint `GET /referral-codes/{code}` to validate a UCC and identify the referrer it belongs to.

    The API returns:

    * `valid` - whether the UCC is a legitimate, active referral code
    * `productUserId` - the referrer’s user ID in your system
    * `campaignId` - the campaign the UCC is associated with

    Example response for a valid code:

    ```json theme={null}
    {
      "code": "UIPIWa2Hnnr",
      "productUserId": "12345678",
      "valid": true,
      "campaignId": "campaign_partners_1"
    }
    ```

    Common use cases for UCC validation:

    * **Self-referral prevention** - compare the returned `productUserId` (referrer) with the logged-in user’s ID; if they match, ignore the UCC
    * **Existing-user attribution** - validate the UCC on login before storing it for future purchase attribution
    * **Tampered URL detection** - if someone modifies the `ucc` query parameter, the API will return `valid: false`
    * **Discount eligibility** - validate the UCC before applying a new-user discount to ensure the code hasn’t been tampered with

    **Related docs**

    * [Fetch referral code info](/api-reference/referral-codes/fetch-referral-code-info)
    * [API authentication](/api-reference/authentication/get-token)
  </Accordion>

  <Accordion title="Can we grab the UCC directly from the URL instead of calling getUcc()?">
    Yes - the `ucc` is always present as a query parameter in the URL when a user clicks a referral link (e.g., `https://yoursite.com/?ucc=ABC123`). You can parse it directly from the URL using standard JavaScript:

    ```javascript theme={null}
    const ucc = new URLSearchParams(window.location.search).get('ucc');
    ```

    However, using `getUcc()` from the [Attribution JS](/sdk/client-side/attribution-js-introduction) library is recommended because it:

    * **Falls back to cookies** - if the user navigated away and the `ucc` is no longer in the URL, `getUcc()` retrieves it from the stored cookie
    * **Handles async loading** - waits for the attribution script to initialize before returning data
    * **Works across sessions** - cookies persist for 3 months, covering indirect signups where the user returns later

    If you read the `ucc` from the URL yourself, make sure to store it in your database linked to the user at signup, so it’s available when sending [signup](/attribution/tracking-signups) and [purchase](/attribution/tracking-purchase) events to Cello.

    **Related docs**

    * [Attribution JS usage & API](/sdk/client-side/attribution-js-usage)
    * [Web attribution](/attribution/for-web)
  </Accordion>

  <Accordion title="Does Cello integrate with Salesforce?">
    Yes. Cello integrates with Salesforce via **Apex triggers** that call the Cello API when specific conditions are met in your Salesforce workflow. This is the recommended approach for sales-led referral attribution.

    A typical setup uses an Apex trigger on the Opportunity object to send events to Cello when:

    * An Opportunity reaches a specific stage (e.g., "Proposal/Price Quote")
    * The Opportunity has a `cello_ucc` custom field populated

    This allows you to attribute deals and revenue back to the referrer who generated the lead. The trigger calls the Cello API to send demo-attended or purchase events based on your sales flow.

    The integration is not a native Salesforce app - it uses standard Apex triggers and HTTP callouts to the Cello API, giving you full control over which events are sent and when. You can also send events directly via the [Cello API](/api-reference/generic-events/send-event) if you prefer not to use Apex triggers.

    **Related docs**

    * [Salesforce Apex triggers guide](/integrations/salesforce-apex-triggers)
    * [Cello API - send events](/api-reference/generic-events/send-event)
  </Accordion>

  <Accordion title="Turbo (turbo-rails / Hotwire) hides the widget iframe on navigation. Any guidance?">
    This happens because Turbo replaces the page’s DOM during navigation, but the Cello widget iframe persists in an orphaned state. The fix is to shut down the widget before Turbo transitions, then re-initialize it on the new page.

    Add an event listener to call `shutdown` before Turbo navigates:

    ```javascript theme={null}
    document.addEventListener("turbo:visit", () => {
      window.Cello("shutdown");
    });
    ```

    Or alternatively, just before Turbo renders new content:

    ```javascript theme={null}
    document.addEventListener("turbo:before-render", () => {
      window.Cello("shutdown");
    });
    ```

    `turbo:visit` (recommended) fires at the start of navigation before any network requests, giving the cleanest teardown. `turbo:before-render` fires later, just before the new page content replaces the DOM.

    After shutdown, Cello needs to be re-initialized on the new page. If your Cello boot script is in the page layout, it will run automatically after Turbo renders. If not, listen for `turbo:load` to re-boot:

    ```javascript theme={null}
    document.addEventListener("turbo:load", () => {
      window.cello.cmd.push(async function (cello) {
        await cello.boot({ /* your boot config */ });
      });
    });
    ```

    **Related docs**

    * [Cello JS SDK](/sdk/client-side/cello-js-introduction)
    * [Quickstart](/referral-component/quickstart)
  </Accordion>

  <Accordion title="We integrated React Native (Expo) and see APIError error 1 on init. What should we check?">
    This error (`InitializationError`) typically means the SDK is connecting to the wrong environment. When using Expo, the `env` property defaults to `prod` - if your credentials are for the sandbox environment but `env` is not explicitly set, initialization will fail.

    Verify that the `env` value is correctly nested under the `@getcello/cello-react-native` Expo plugin in your `app.json`:

    ```json theme={null}
    {
      "expo": {
        "plugins": [
          [
            "@getcello/cello-react-native",
            {
              "env": "sandbox"
            }
          ]
        ]
      }
    }
    ```

    After changing the plugin configuration, you must rebuild the native app:

    ```bash theme={null}
    npx expo prebuild --clean
    ```

    Also check:

    * **Credentials** - ensure `productId` and `token` match the environment you selected (`sandbox` vs `prod`)
    * **Not using Expo Go** - the Cello SDK requires a custom native build and will not work in Expo Go (you’ll see a `LINKING_ERROR` instead)

    **Related docs**

    * [React Native SDK](/sdk/mobile/react-native)
  </Accordion>

  <Accordion title="Our signup discount isn’t applied when the referee reaches payment stage. Why?">
    Referral discounts are applied by **your** subscription platform (Stripe, Chargebee, etc.) during subscription creation - Cello does not apply them automatically. If the discount isn’t showing up, check the following in order:

    1. **Is the `ucc` available at checkout?** - verify the referral code was preserved from signup to the payment flow. Check your Stripe/Chargebee customer metadata for `cello_ucc`, or call `getUcc()` from the Attribution Library. If it’s missing, the attribution cookie may have been lost (e.g., cookie consent blocked it, or the user is on a different domain).

    2. **Is the user eligible for a discount?** - use the [New User Reward API](/api-reference/new-users/get-reward) to validate eligibility, or check for `cello_ucc` in the customer object in your payment platform. Note that `eligible: false` can also be returned if the user signed up with **their own UCC** or the signup was flagged as a **self-referral** by Cello's [fraud detection](/guides/fraud-detection) - self-referrals do not qualify for new-user discounts.

    3. **Is the coupon applied during subscription creation?** - discounts must be passed at the time the subscription is created (e.g., via `discounts` array in Stripe or `coupon_ids` in Chargebee). They cannot be attached after the fact through the API.

    4. **Is the coupon valid?** - verify the coupon ID exists in your payment platform, hasn’t expired, and matches the plan type being purchased.

    **Related docs**

    * [Apply discounts guide](/attribution/apply-discounts)
    * [New User Reward API](/api-reference/new-users/get-reward)
    * [Web attribution](/attribution/for-web)
  </Accordion>

  <Accordion title="I added the CDN script in index.html and sometimes the page errors on load. Why?">
    This typically happens because the Cello script downloads and executes before the `<body>` element is available in the DOM. Cello appends its UI to `<body>`, so if `<body>` doesn’t exist yet, initialization fails.

    **Recommended fix:** Ensure the script tag includes `type="module"` and `async`, and is placed in the `<head>`:

    ```html theme={null}
    <script type="module" src="https://assets.cello.so/app/latest/cello.js" async></script>
    ```

    The `type="module"` attribute defers execution until after the DOM is parsed, which prevents the race condition. If you’re still seeing issues:

    * **Use the command queue pattern** - initialize Cello through the queue so commands are buffered until the script is ready:
      ```javascript theme={null}
      window.cello = window.cello || { cmd: [] };
      window.cello.cmd.push(async function (cello) {
        await cello.boot({ /* your config */ });
      });
      ```
    * **Move the script to the end of `<body>`** - as a fallback, placing the `<script>` tag just before `</body>` ensures the DOM is fully available
    * **Angular users** - avoid using `<body>` as your AppRoot element, as this creates a race condition with Cello’s DOM injection. See the [Angular notes](/referral-component/quickstart#do-you-support-angular)

    **Related docs**

    * [Quickstart - load the script](/referral-component/quickstart#step-1-load-the-script)
    * [Cello JS SDK](/sdk/client-side/cello-js-introduction)
  </Accordion>

  <Accordion title="await window.CelloAttribution('getUcc') can hang if the script fails to load. What should we do?">
    If the Attribution JS script fails to load (due to network issues, ad blockers, or CSP restrictions), the `getUcc()` promise will never resolve or reject - it waits indefinitely for the script to initialize.

    **Never place `getUcc()` on a critical path** that blocks your signup or checkout flow. Instead, race it against a timeout:

    ```javascript theme={null}
    async function getUccWithTimeout(timeoutMs = 3000) {
      try {
        const ucc = await Promise.race([
          window.CelloAttribution('getUcc'),
          new Promise((_, reject) =>
            setTimeout(() => reject(new Error('Attribution timeout')), timeoutMs)
          )
        ]);
        return ucc;
      } catch {
        return null;
      }
    }
    ```

    If the timeout wins, proceed without the UCC - the user likely didn’t arrive via a referral link, or you can fall back to reading the `ucc` directly from the URL query parameter as a backup.

    **Related docs**

    * [Attribution JS usage & API](/sdk/client-side/attribution-js-usage)
    * [Attribution JS introduction](/sdk/client-side/attribution-js-introduction)
  </Accordion>

  <Accordion title="The widget doesn't load and the console shows 'Refused to connect / Refused to execute script... Content Security Policy' errors. What do we do?">
    Console errors containing `violates the following Content Security Policy directive` or `violates the document's Content Security Policy` mean your site's CSP headers are blocking Cello resources. Typical examples:

    ```text theme={null}
    Refused to execute inline script because it violates the following Content Security Policy directive: "script-src ..."
    Refused to load the script 'https://assets.cello.so/app/latest/cello.js' because it violates the following Content Security Policy directive: "script-src ..."
    Fetch API cannot load https://share.cello.so/api/products/.../initialize/v2. Refused to connect because it violates the document's Content Security Policy.
    Refused to load the image because it violates the following Content Security Policy directive: "img-src ..."
    ```

    The fix is on your side: extend your CSP with the Cello sources. The directive named in the error (`script-src`, `connect-src`, `img-src`, `style-src`, `font-src`) tells you which one is missing.

    ```text theme={null}
    script-src  https://assets.cello.so
    connect-src https://share.cello.so
    img-src     https://cdn.cello.so https://p.typekit.net blob: data:
    style-src   https://use.typekit.net 'unsafe-inline'
    font-src    https://use.typekit.net https://p.typekit.net
    ```

    These directives extend your existing policy; if you use a restrictive `default-src`, keep all of the above explicit. Sandbox environments use the equivalent `*.sandbox.cello.so` domains (for example `https://assets.sandbox.cello.so` and `https://share.sandbox.cello.so`).

    **Related docs**

    * [Quickstart - Content Security Policy (CSP)](/referral-component/quickstart#content-security-policy-csp)
    * [Quickstart - load the script](/referral-component/quickstart#step-1-load-the-script)
  </Accordion>

  <Accordion title="Can we embed referral links in our own marketing channels (newsletters, emails, etc.)?">
    Yes. You can include a referral link in newsletters, email campaigns, blog posts, in-app messages, or any owned channel to attribute signups back to a specific referrer and offer new-user discounts. The link just needs to contain the `ucc` parameter so the Attribution Library captures it on the landing page.

    To get a user's referral link programmatically, use the Active Link API:

    ```
    GET /referral-codes/active-link/{productUserId}
    ```

    This returns the user's active `ucc` and invite link, which you can embed in your templates. When recipients click the link and land on your site, the Attribution Library captures the `ucc` and attribution proceeds as normal.

    **Tips for marketing-channel referral links:**

    * **Use a dedicated or internal account** as the referrer if you want to track campaign-driven signups separately from user-to-user referrals
    * **Ensure the landing page has the Attribution Library installed** so the `ucc` is captured and persisted
    * **Configure a new-user discount** in your [campaign settings](/guides/campaigns/setting-up-campaigns) if you want to offer discounts to readers who sign up

    **Related docs**

    * [Fetch active link API](/api-reference/referral-codes/fetch-active-link)
    * [Optimizing referral landing pages](/guides/user-experience/optimizing-landing-pages)
    * [Incentivized casual contact loop](/guides/best-practices/incentivized-casual-contact-loop)
  </Accordion>

  <Accordion title="How do we cancel or stop reward payments when a subscription is cancelled or refunded?">
    Yes - Cello supports automatic and manual cancellation of rewards depending on your integration:

    **Stripe / Chargebee webhooks (automatic)**
    When you connect Stripe or Chargebee webhooks, Cello automatically detects cancellation and refund events:

    * `subscription.deleted` - stops future recurring rewards for that referral
    * `charge.refunded` - automatically cancels any **pending** reward for that transaction

    No additional API calls are needed; Cello reacts to these webhook events as they arrive.

    **Cello API (manual)**
    If you use the Cello API instead of webhooks, send a `charge-refunded` event via `POST /events` to cancel pending rewards for a specific transaction:

    ```bash theme={null}
    POST https://api.cello.so/events

    {
      "eventName": "ReferralUpdated",
      "payload": {
        "ucc": "cello-ucc",
        "newUserId": "new-user-id",
        "price": 1000,
        "currency": "EUR"
      },
      "context": {
        "event": {
          "trigger": "charge-refunded",
          "timestamp": "2024-01-15 10:00:00"
        },
        "subscription": {
          "invoiceId": "invoice-id"
        }
      }
    }
    ```

    **Important nuances:**

    * **Pending rewards** are automatically cancelled when a refund event is received
    * **Already paid-out rewards** are not clawed back from referrers - Cello does not ask referrers to return money
    * To mitigate refund risk, many programs **spread rewards over time** (e.g. monthly over 12 months) so future payouts can be stopped if the deal falls through
    * Cello can also configure a **payout delay** (e.g. 14 days) matching your refund window - contact your CSM to set this up
    * You can review reward status (CREATED, CANCELED, REJECTED, PROCESSED) in the Cello Portal under the Purchases page

    **Related docs**

    * [Tracking purchases - charge-refunded event](/attribution/tracking-purchase#charge-refunded)
    * [Fraud detection and payout delays](/guides/fraud-detection)
    * [Stripe webhook setup](/integrations/webhooks/stripe-webhook)
    * [In-product rewards and reward status](/guides/in-product-rewards)
  </Accordion>

  <Accordion title="Does the productId need to match our domain?">
    No. The `productId` is simply an identifier for your Cello account - it does not need to match your application domain, staging URL, or any specific URL pattern. It may look like a domain, but that is just a naming convention; it has no functional connection to where you deploy Cello.

    What **does** matter is using the correct credentials for each environment:

    * **Sandbox credentials** (`productId` + `PRODUCT_SECRET` from the Sandbox environment) for development and staging
    * **Production credentials** (`productId` + `PRODUCT_SECRET` from the Production environment) for your live application

    You can find both sets of credentials on the [Access Keys page](https://portal.cello.so/integrations/accesskeys) in the Cello Portal.

    **Common errors from mismatched credentials:**

    * Using a Sandbox `productId` with a Production `PRODUCT_SECRET` (or vice versa)
    * Calling the wrong Cello API environment from your backend
    * Using the wrong webhook signing secret for the environment

    **Related docs**

    * [Referral Component quickstart - prerequisites](/referral-component/quickstart#prerequisites)
    * [Implementation testbook](/guides/integration/implementation-testbook)
  </Accordion>

  <Accordion title="Is there a headless API? Do we have to use the Referral Component (widget)?">
    Cello is designed as a **hybrid system** - some parts are API-driven and fully headless, while the Referral Component (widget) handles the referrer-facing experience.

    **What is fully headless (API-only):**

    * **Attribution** - capturing referral codes, tracking signups, and tracking purchases all happen via the Cello API or Stripe/Chargebee webhooks, with no widget required
    * **Referral code validation** - `GET /referral-codes/{code}` to verify a UCC
    * **Active link retrieval** - `GET /referral-codes/active-link/{productUserId}` to fetch a user’s referral link programmatically
    * **Event sending** - `POST /events` for signup, purchase, and refund events

    **What the Referral Component provides (and cannot be rebuilt independently):**
    The widget handles the **referrer experience** - the part where users share their link, see who signed up, track rewards, and manage payouts. This includes:

    * Link sharing (copy, social media, email, QR code)
    * Progress tracking (clicks, signups, earnings)
    * Reward payouts and payment details management (PayPal/Venmo)
    * In-app notifications, announcements, and onboarding
    * Multi-language support and dark mode

    Cello does not currently provide an SDK or API to rebuild these features (such as the rewards view or payment details management) as a fully custom UI. The Referral Component is the only way to deliver the complete referrer experience.

    **What you can do - extend with custom placements:**
    While the Referral Component is required for the full experience, you can - and are encouraged to - surface referral information in additional places throughout your product using the Cello JS SDK or API:

    * Use [`getActiveUcc()`](/sdk/client-side/cello-js-usage#getactiveucc) to retrieve a user’s referral link
    * Use [`getCampaignConfig()`](/sdk/client-side/cello-js-usage#getcampaignconfig) to fetch reward amounts and program details
    * Use [`getLabels()`](/sdk/client-side/cello-js-usage#getlabels) to get localized text for your custom elements

    This allows you to build mini-cards, banners, or menu items that display the referral link and campaign info at [moments of delight](/guides/best-practices/contextual-sharing) - for example, after a user completes a milestone or receives positive feedback. These custom placements complement the Referral Component and are a best practice for increasing sharing activity.

    The Referral Component itself can be [themed, repositioned](/guides/user-experience/configuring-referral-component), and launched from a [custom launcher](/referral-component/custom-launcher) (any button, menu item, or link) to feel native to your product.

    **Related docs**

    * [Cello API reference](/api-reference/introduction)
    * [Referral Component introduction](/referral-component/introduction)
    * [Custom launcher](/referral-component/custom-launcher)
    * [Contextual sharing - moments of delight](/guides/best-practices/contextual-sharing)
    * [Cello JS SDK - usage](/sdk/client-side/cello-js-usage)
  </Accordion>

  <Accordion title="How does Cello handle language and localization?">
    Cello supports 10+ languages: English, German, Spanish, French, Dutch, Italian, Portuguese, Japanese, Danish, Slovak, and Romanian. More can be added on request.

    **What is enabled by default**

    * **English is the only language enabled out of the box** for every product, and it also serves as the **fallback** whenever an unknown or unenabled language is requested.

    **Enabling additional languages**

    * Any language other than English (including the supported languages listed above) must be **enabled for your product by Cello** before it takes effect. Passing a `language` code via the SDK does not enable it - if the language is not enabled, the component silently falls back to your product's default language.
    * To enable additional languages, or to add a brand-new language not in the supported list, contact your CSM or [support@cello.so](mailto:support@cello.so).

    **Changing the default language**

    * You can request Cello to change your product's **default language** from English to one of the enabled languages (e.g., German for a DACH-focused product). This is also done via support / CSM.

    **Editing the translated text**

    * Translations for each enabled language are written and maintained by Cello to stay consistent across reward structures. Customers **cannot** edit translation strings themselves in the Portal or via API. To request wording changes in any language, contact support with the surface, current text, and proposed new text.

    **How language is selected at runtime**

    | Surface                         | How language is selected                                                                                                                                                                               | Fallback                                            |
    | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
    | **Referral Component (web)**    | Pass `language` (ISO 639-1) during [`cello.boot()`](/sdk/client-side/cello-js-usage#cellobootoptions), or call [`changeLanguage()`](/sdk/client-side/cello-js-usage#changelanguagelanguage) at runtime | Product default language (English unless changed)   |
    | **Referral Component (mobile)** | Pass `language` during SDK initialization ([iOS](/sdk/mobile/ios), [Android](/sdk/mobile/android), [React Native](/sdk/mobile/react-native), [Flutter](/sdk/mobile/flutter))                           | Device language, then product default, then English |
    | **Referee landing page**        | Detected from the visitor's browser settings                                                                                                                                                           | English                                             |
    | **Emails**                      | Last language used by the user in the widget                                                                                                                                                           | Product default language                            |

    **Changing language at runtime:**
    You can switch the language without re-initializing the component:

    * **Web:** `window.Cello("changeLanguage", "de")`
    * **Mobile:** `Cello.changeLanguage("de")` (iOS 14+ required on iOS)

    **Related docs**

    * [Texts and language overview](/guides/user-experience/overview#texts-and-language)
    * [Cello JS boot options](/sdk/client-side/cello-js-usage#cellobootoptions)
    * [Cello JS - changeLanguage](/sdk/client-side/cello-js-usage#changelanguagelanguage)
  </Accordion>

  <Accordion title="How do we retrieve campaign details (like reward percentage, new-user discount) programmatically?">
    Yes - campaign details are available through both the **Cello JS SDK** and the **Attribution JS SDK**. Use the JavaScript approach for displaying discount info in your UI. Use the REST API only for applying the discount on the backend or for server-side rendered apps.

    **Which method to use:**

    * `getCampaignConfig()` (JS) - best for **displaying** discount info client-side. Runs in the browser, no backend round-trip needed. This is the right choice for most apps.
    * [New User Reward API](/api-reference/new-users/get-reward) - use on the **backend** when applying the discount at checkout, or if your app is **server-side rendered** (e.g., PHP, Next.js SSR) and needs discount details before the page loads.

    **For logged-in users (Referral Component / Cello JS):**
    Use `getCampaignConfig()` to retrieve the current user’s campaign details:

    ```javascript theme={null}
    const config = await window.Cello("getCampaignConfig");
    ```

    Returns:

    * `primaryCurrency` - reward currency code
    * `revenuePercentage` - referrer reward as a percentage of revenue
    * `rewardCap` - maximum reward per referral
    * `newSignupBonus` - bonus reward for each signup
    * `newPurchaseBonus` - bonus reward for each purchase
    * `newUserDiscountPercentage` - discount for referred new users (decimal: `0.1` = 10%)
    * `newUserDiscountMonth` - how many months the discount lasts

    **For landing page visitors (Attribution JS):**
    Use `getCampaignConfig()` from the Attribution SDK to display discount info before signup:

    ```javascript theme={null}
    const config = await window.CelloAttribution("getCampaignConfig");
    const discountPercent = config.newUserDiscountPercentage * 100;
    const months = config.newUserDiscountMonth;
    // e.g. "10% off for 3 months"
    ```

    **Mobile SDKs** also expose `getCampaignConfig()` on [iOS](/sdk/mobile/ios), [Android](/sdk/mobile/android), [React Native](/sdk/mobile/react-native), and [Flutter](/sdk/mobile/flutter).

    **Note on `campaignId` in the referral-codes API:**
    When calling `GET /referral-codes/{code}`, the response includes a `campaignId` field. For the **default campaign**, this field returns an empty string - this is expected behavior, not an error. Non-default campaigns return their actual campaign ID.

    **Related docs**

    * [Cello JS - getCampaignConfig()](/sdk/client-side/cello-js-usage#getcampaignconfig)
    * [Attribution JS introduction](/sdk/client-side/attribution-js-introduction)
    * [Personalizing referral landing pages](/guides/user-experience/personalizing-referrals)
    * [Referral codes API](/api-reference/referral-codes/validate-referral-code)
  </Accordion>
</AccordionGroup>

## Authentication & tokens

<AccordionGroup>
  <Accordion title="Why is my JWT token being rejected? How does the iat timestamp validation work?">
    The `iat` (issued at) field in the JWT payload is a Unix timestamp that tells Cello when the token was created. Cello enforces a validation window on this value:

    * The `iat` **cannot be older than 24 hours** - tokens issued more than 24 hours ago are considered expired
    * The `iat` **cannot be set in the future** - tokens with a future timestamp are rejected as invalid

    If your server’s clock is out of sync (even by a few minutes), the `iat` value may fall outside these bounds and the token will be rejected, causing a boot failure with a token/authorization error.

    **How to fix:**

    1. **Verify your server’s system clock** - ensure it is synchronized using NTP (Network Time Protocol)
    2. **Use `Math.floor(Date.now() / 1000)`** (or equivalent in your language) to generate the `iat` value dynamically rather than hardcoding it
    3. **Check your environment** - staging and production servers may have different time configurations

    **Example token payload:**

    ```json theme={null}
    {
      "productId": "your-product-id",
      "productUserId": "user-123",
      "iat": 1662712365
    }
    ```

    **Related docs**

    * [User authentication and JWT generation](/sdk/client-side/user-authentication)
    * [Token update and expiry handling](/guides/token-update)
  </Accordion>

  <Accordion title="How does Cello API token authentication work? Does the refresh token expire?">
    The Cello REST API uses a two-token authentication model (separate from the widget JWT used for the Referral Component):

    1. **Authenticate** - call `POST /token` with your `accessKeyId` and `secretAccessKey` (from the [Access Keys page](https://portal.cello.so/integrations/accesskeys)). This returns:
       * `accessToken` - short-lived token used in the `Authorization` header for API requests
       * `refreshToken` - longer-lived token used to get new access tokens without re-authenticating
       * `expiresIn` - how long the access token is valid

    2. **Refresh** - when the access token expires, call `POST /token` with the `refreshToken` to get a new `accessToken`. This does **not** return a new refresh token.

    3. **Re-authenticate** - the refresh token expires after **5 days**. Once expired, you must perform a full authentication again with your `accessKeyId` and `secretAccessKey` to obtain both a new access token and a new refresh token.

    There is no separate endpoint to retrieve only a new refresh token - refresh tokens are only issued during full authentication.

    **Recommended pattern for long-running integrations:**

    * Store the refresh token securely after initial authentication
    * Use it to refresh the access token before it expires
    * Implement a fallback to full re-authentication when the refresh token itself expires (after 5 days)

    **Related docs**

    * [API authentication - get token](/api-reference/authentication/get-token)
    * [API introduction](/api-reference/introduction)
  </Accordion>
</AccordionGroup>


# Event Feed
Source: https://docs.cello.so/guides/support/portal/event-feed

Monitor and debug incoming signup and transaction events from Stripe, Chargebee, Cello API, and auto attribution. Inspect event payloads, understand field validation statuses (OK, Warning, Error), and troubleshoot missing or malformed fields.

The Event Feed gives you a real-time view of every signup and transaction event Cello receives - whether from a webhook, the Cello API, or auto attribution. Use it to verify your integration is working correctly and to quickly identify missing or malformed fields.

The Event Feed shows events from four sources: Auto Attribution, Stripe Webhook, Chargebee Webhook, and Cello API. Each event is validated and assigned a status of OK (all fields valid), Warning (non-critical issues like missing recommended fields), or Error (critical failures like missing required fields). You can filter by source, search by text, and expand any event to inspect its payload with per-field validation.

You can access the Event Feed at [Integrations → Events Feed](https://portal.cello.so/integrations/events-feed) in the Cello Portal.

<Tip>
  For a higher-level view of which integration components are connected, see [Integration Status](/guides/support/portal/integration-status).
</Tip>

## List View

The Event Feed displays your most recent events in a table with the following columns:

| Column         | Description                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------- |
| **Source**     | Where the event originated - Auto Attribution, Stripe Webhook, Chargebee Webhook, or Cello API |
| **Event Type** | The type of event, e.g. `new-signup`, `invoice-paid`, `customer_created`, `Attributed Signup`  |
| **Email**      | The email address associated with the event                                                    |
| **Status**     | Validation result - OK, Warning, or Error                                                      |
| **Time (UTC)** | When the event was received                                                                    |

<img alt="Event Feed list view showing events from multiple sources" />

### Filtering Events

* **Search bar** - free-text search across all columns
* **Tabs** - switch between **All**, **Attributions**, and **Events**
* **Filters button** - apply additional filters to narrow down results

### Event Statuses

Each event is validated and assigned one of three statuses:

| Status      | Meaning                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------- |
| **OK**      | The event passed all validations successfully                                            |
| **Warning** | The event was received but has non-critical issues (e.g. a recommended field is missing) |
| **Error**   | The event has critical validation failures that need to be resolved                      |

## Expanded Event View

Click the arrow on any row to expand it and inspect the event details.

<img alt="Expanded event view showing payload with per-field validation" />

The expanded view shows the parsed event payload with per-field validation indicators. Each field is marked as valid, warning, or error so you can immediately see which fields need attention.

## Field Validation Reference

The Event Feed validates each field in the event payload and shows a status indicator next to it. The required and recommended fields differ depending on the event source.

### Field Validation for Stripe / Chargebee Webhooks

For Stripe and Chargebee webhook events, the `ucc` (referral code) and `newUserId` fields are always required. The `email` field is recommended and improves attribution tracking, but becomes required if your product uses [auto attribution](/guides/attribution/auto-attribution).

#### Required fields

| Field       | Validation                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------ |
| `ucc`       | Must be a valid 11-character alphanumeric referral code. Shows **"Invalid"** if malformed. |
| `newUserId` | Must be present. Shows **"Required"** if missing.                                          |

#### Recommended fields

| Field   | Validation                                                                                                                                                   |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `email` | Recommended - improves attribution tracking and fraud detection. **Required** if your product uses [auto attribution](/guides/attribution/auto-attribution). |

#### Other validated fields

| Field            | Validation                                                          |
| ---------------- | ------------------------------------------------------------------- |
| `customerId`     | Validated when present                                              |
| `organizationId` | See [Organization ID validation](#organization-id-validation) below |

### Field Validation for Cello API Events

For Cello API events, the `ucc` (referral code) is always required, and at least one of `newUserId` or `productUserId` must be present. For `invoice-paid` events, the `invoiceId`, `interval`, and `currency` fields are also required.

#### Always required

| Field                          | Validation                                                              |
| ------------------------------ | ----------------------------------------------------------------------- |
| `ucc`                          | Must be a valid referral code. Shows **"Invalid"** if malformed.        |
| `newUserId` or `productUserId` | At least one must be present. Shows **"Required"** if both are missing. |

#### Additional fields for `invoice-paid` events

| Field       | Validation             |
| ----------- | ---------------------- |
| `invoiceId` | **Required**           |
| `interval`  | **Required**           |
| `currency`  | **Required**           |
| `price`     | Validated when present |

#### Timestamp

Must be a valid Unix timestamp. Shows **"Invalid"** if the format is incorrect.

## Organization ID Validation

How `organizationId` is validated depends on whether your product is configured for org-level attribution.

### Org-level attribution enabled

When org-level attribution is enabled, the `organizationId` field is required and must not equal `newUserId`. If `organizationId` is missing while `newUserId` is present, the event shows an Error. If `organizationId` is provided but `newUserId` is missing, the event shows a Warning.

| Scenario                              | Status  | Message                                                                      |
| ------------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `orgId` present and valid             | Valid   | -                                                                            |
| `orgId` equals `newUserId`            | Error   | "Must not equal newUserId"                                                   |
| `orgId` missing, `newUserId` present  | Error   | "Required"                                                                   |
| Both `orgId` and `newUserId` missing  | Error   | Both show "Required"                                                         |
| `orgId` provided, `newUserId` missing | Warning | newUserId: "Recommended - improves attribution tracking and fraud detection" |

### Org-level attribution disabled

When org-level attribution is disabled, any provided `organizationId` is ignored and the field is not shown if omitted.

| Scenario             | Status  | Message                                                      |
| -------------------- | ------- | ------------------------------------------------------------ |
| `orgId` provided     | Warning | "Ignored - product not configured for org-level attribution" |
| `orgId` not provided | -       | Field not shown                                              |

## Field Status Icons

| Icon                           | Meaning                                                        |
| ------------------------------ | -------------------------------------------------------------- |
| Green check                    | Field is valid                                                 |
| Red "Required"                 | A required field is missing                                    |
| Red "Invalid"                  | Field is present but malformed (e.g. invalid referral code)    |
| Red "Must not equal newUserId" | `orgId` is the same as `newUserId`                             |
| Yellow "Recommended..."        | An optional field that improves tracking is missing            |
| Yellow "Ignored..."            | Field is provided but your product is not configured to use it |

## Troubleshooting

| Problem                                                        | Cause                                                             | Solution                                                                                                                                                                  |
| -------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event shows "Error" with "Required" on `ucc`                   | The referral code is missing from the event payload               | Ensure you pass the `ucc` parameter when sending the event. See [Track Signups](/attribution/tracking-signups) or your [webhook setup guide](/integrations/introduction). |
| Event shows "Error" with "Invalid" on `ucc`                    | The referral code is not a valid 11-character alphanumeric string | Verify you are passing the correct `ucc` value captured during attribution.                                                                                               |
| Event shows "Warning" on `email`                               | Email is recommended but not strictly required                    | Add the `email` field to improve attribution tracking and fraud detection. If you use auto attribution, `email` becomes required.                                         |
| Event shows "Ignored" on `organizationId`                      | Your product is not configured for org-level attribution          | You can safely ignore this warning, or remove the `organizationId` field from your payload.                                                                               |
| Event shows "Error" with "Must not equal newUserId" on `orgId` | The `organizationId` and `newUserId` have the same value          | These must be different - `organizationId` identifies the company, `newUserId` identifies the individual user.                                                            |
| I don't see my events                                          | Events can take a few minutes to appear                           | Click the **Refresh** button to reload the feed.                                                                                                                          |
| I only see some of my events                                   | Only events that include a referral code (`ucc`) are shown        | Events without a `ucc` are not displayed in the Event Feed.                                                                                                               |

You can inspect events from your AI client using [`cello_get_events`](/mcp/tools#cello_get_events) via the [Cello MCP](/mcp/developers/use-cases).


# Integration Status
Source: https://docs.cello.so/guides/support/portal/integration-status

Get a real-time health overview of your Cello integration across the Referral Component, Attribution Library, Signups, and Purchases. See whether each piece is connected, when the last event was received, and what to do when something goes wrong. The signup and purchase source must be confirmed with Cello - do not self-select a source if you are unsure.

The Integration Status page gives you a single health view of your Cello integration. It tracks four core components - the Referral component, the Attribution library, Signups tracking, and Purchases tracking - and tells you at a glance whether each one is sending events as expected.

Use Integration Status to confirm a new integration is wired up correctly, monitor an existing integration in production, and quickly spot when an upstream change has broken a webhook or script.

You can access it at [Integrations → Integration Status](https://portal.cello.so/integrations/integration-status) in the Cello Portal. It's available in both **sandbox** and **production**.

## How it relates to Event Feed

Integration Status and the [Event Feed](/guides/support/portal/event-feed) work hand-in-hand:

* **Integration Status** - high-level health per component. Use it to answer "is everything working?"
* **Event Feed** - individual event log with per-field validation. Use it to answer "why did this specific event fail?"

When a component on Integration Status shows a warning or error, the Event Feed is where you drill in to see the exact payload and field-level issue.

## Page header

The page header gives you an at-a-glance summary of your integration before you scroll into the individual component cards.

<img alt="Integration Status header showing Environment, Status, Health Window, and Last Update" />

| Field                    | What it shows                                                                                                                                                                                              |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Environment**          | Which environment you're viewing - **Sandbox** or **Production**.                                                                                                                                          |
| **Status**               | Aggregate health across all four components (e.g. `4/4 connected`, `2/4 need attention`).                                                                                                                  |
| **Health window**        | The time range Cello checks for successful events. If none arrive within this window, the integration is flagged as needing attention. The window is **1 hour** in production and **24 hours** in sandbox. |
| **Last update**          | Time since the page last refreshed its data. Use the refresh icon to re-check all components on demand - otherwise, statuses refresh automatically within \~10 minutes of an event arriving.               |
| **Update configuration** | Opens the modal where you can change the signup and purchase sources. See [Changing the configured source](#changing-the-configured-source-confirm-with-cello-first).                                      |

## Status definitions

Every component reports one of three statuses, calculated against the **health window** shown in the page header (1 hour in production, 24 hours in sandbox):

| Status                      | Meaning                                                                                                                                                                                                                                                                                                                     |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connected**               | At least one successful event received within the health window. Even if some events had errors, a single success is enough to count as Connected.                                                                                                                                                                          |
| **Connected with warnings** | The component **is** receiving events, but something needs attention. Either events arrived recently (within the last 30 days) but **none in the current health window**, or events arrived in the window but couldn't be attributed (no referral code) or failed validation.                                               |
| **Not connected**           | The component is **not** receiving events. This covers three distinct situations: (1) **no source is configured**, (2) a source is selected but its **credentials are missing** (Cello API key or webhook signing secret), or (3) the source and credentials are set up correctly but **no events have been received yet**. |

Statuses can move in any direction - a component can go from Connected to Warnings if recent events have errors, or to Not connected if you change the source.

<Note>
  **Connected with warnings is not the same as Not connected.** Connected with warnings means events are arriving and the integration is fundamentally wired up - the fix is usually about the referral code (`ucc`) or field validation, **not** about setting up or changing a source. Always match troubleshooting to the **already-configured source** shown on the card.
</Note>

## Status and warning reference

This is the authoritative mapping of what each Signups and Purchases tracking state means and what to do about it. Whatever the state, **troubleshoot the source that is already configured** - do not switch sources or set up a webhook for a different source. If you think a different source fits your setup, [confirm it with Cello first](#changing-the-configured-source-confirm-with-cello-first).

### Signups tracking

| Scenario                                                             | Status                  | What to do                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No source configured                                                 | Not connected           | Set the source (sandbox: Update configuration modal; production: Cello Support). Confirm the right source with Cello.                                                                                                                                                                                                                     |
| Source selected but credentials missing                              | Not connected           | Add the prerequisite for that source: Cello API -> generate an API key; Stripe/Chargebee -> install the webhook and signing secret.                                                                                                                                                                                                       |
| Configured correctly, but no signups received yet                    | Not connected           | Confirm the **configured** source is actually sending. Cello API -> your backend calls `POST /events` with `trigger: "new-signup"`; Stripe/Chargebee -> the webhook is forwarding `customer.created` / `customer.updated` (or Chargebee equivalents); Auto Attribution -> a referred signup has actually happened. Do not switch sources. |
| Auto Attribution: signups seen before, but none in the health window | Connected with warnings | Usually low recent activity, not a break. Confirm referred signups are still occurring. (This recent-activity warning applies to Auto Attribution.)                                                                                                                                                                                       |
| Events arriving, but none attributed                                 | Connected with warnings | Events lack a referral code (`ucc`), so they can't be attributed. Open the [Event Feed](/guides/support/portal/event-feed) and check recent events for a missing or malformed `ucc`. Applies to event-sending sources (Cello API, Stripe, Chargebee), not Auto Attribution.                                                               |
| Attributed events arriving, but all fail validation                  | Connected with warnings | Open the [Event Feed](/guides/support/portal/event-feed) to see which required fields are failing for your source.                                                                                                                                                                                                                        |
| Everything healthy                                                   | Connected               | Nothing - signups are being attributed.                                                                                                                                                                                                                                                                                                   |

### Purchases tracking

Purchases have no Auto Attribution path and no recent-activity warning - a configured purchase source that has never received events shows **Not connected** until the first event arrives.

| Scenario                                            | Status                  | What to do                                                                                                                                                                                                      |
| --------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No source configured                                | Not connected           | Set the source (sandbox: Update configuration modal; production: Cello Support). Confirm the right source with Cello.                                                                                           |
| Source selected but credentials missing             | Not connected           | Add the prerequisite for that source: Cello API -> generate an API key; Stripe/Chargebee -> install the webhook and signing secret.                                                                             |
| Configured correctly, but no purchases received yet | Not connected           | Confirm the **configured** source is actually sending. Cello API -> your backend sends `invoice-paid` via `POST /events`; Stripe/Chargebee -> the webhook is forwarding purchase events. Do not switch sources. |
| Events arriving, but none attributed                | Connected with warnings | Events lack a referral code (`ucc`). Open the [Event Feed](/guides/support/portal/event-feed) and check recent events for a missing or malformed `ucc`.                                                         |
| Attributed events arriving, but all fail validation | Connected with warnings | Open the [Event Feed](/guides/support/portal/event-feed) to see which required fields are failing for your source.                                                                                              |
| Everything healthy                                  | Connected               | Nothing - purchases are being attributed.                                                                                                                                                                       |

## The four components

### 1. Referral component

Tracks `booted` events from `cello.js` - the script that renders the Referral Component widget in your app.

<img alt="Integration Status card for the Referral component showing a Connected with warnings state with a JWT token error" />

The card shows when the **last event** and **last error** were received. When errors are present, the alert summarizes the most recent error and a **View all errors** link opens the last 10 widget events so you can see what went wrong.

| Status                                   | What it means                                                                                                   | What to check                                                                                                                         |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Connected                                | The Referral Component booted successfully within the health window.                                            | Nothing - everything is working as expected.                                                                                          |
| Connected with warnings                  | No successful boots in the health window, but no errors either.                                                 | Confirm the Referral Component is still being loaded for users. Check whether traffic to pages embedding the widget has dropped.      |
| Connected with warnings (errors present) | Recent boots produced errors. The card shows the **last error** message and links to the last 10 widget events. | See [Widget errors reference](#widget-errors-reference) below to interpret the message.                                               |
| Not connected                            | No boots in 30 days.                                                                                            | Verify `cello.js` is loaded and `cello("boot", ...)` is called. See [Embed the Referral Component](/referral-component/introduction). |

#### Widget errors reference

The error messages shown in the portal are deliberately written to be human-readable, and they're worded differently from what you'll see in the browser **Console** or in the **Network** tab. Use this table to map between the portal wording and the underlying error.

| Error type          | Console (browser)                                                       | API (network tab)               | Portal                                                                          |
| ------------------- | ----------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------- |
| **JWT token issue** | `401 (Unauthorized) [Cello]: User is not authorized to load the widget` | `Error 1100: Invalid JWT token` | **JWT token is missing, malformed, or expired** (code: `Invalid token payload`) |
| **Internal error**  | `Internal server error`                                                 | `Internal server error`         | **An internal error occurred - contact support**                                |

##### Token issue (`InvalidJwt`)

The portal collapses several underlying token failures into a single message: **"JWT token is missing, malformed, or expired"**. The actual underlying cause is one of:

* `token verification failed` - `decodeWidgetToken` could not verify the signature.
* `token schema not validated` - the token payload is invalid (e.g. wrong shape).
* `token missing iat field` - the token has no `iat` claim and `allowMissingTokenIat = false`.
* `token creation time in future` - the `iat` is in the future.
* `No referrer found for productUserId` - the token references a `productUserId` that doesn't exist.
* `No auth token found` - no token was sent with the boot request.

If the portal shows this error, regenerate the widget token on your backend and confirm it's signed with the right secret, contains a valid `productUserId`, and has a current `iat` timestamp. See [User Authentication](/sdk/client-side/user-authentication) for details.

### 2. Attribution library

Tracks referral link visits picked up by `cello-attribution.js` - the script you embed on your landing pages to capture referral codes.

<img alt="Integration Status card for the Attribution library" />

| Status                             | What it means                                                  | What to check                                                                                                                                          |
| ---------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Connected                          | A referral link was visited within the health window.          | Nothing - attribution is being captured.                                                                                                               |
| Connected with warnings            | No referral link visits in the last few hours.                 | Likely just low traffic. Check sharing activity in the portal.                                                                                         |
| Not connected (no signup URL)      | No signup URL is set in your Cello configuration.              | Set the signup URL in **User Experience → Settings**.                                                                                                  |
| Not connected (URL set, no events) | The signup URL is configured but no visits have been recorded. | Confirm `cello-attribution.js` is embedded on the landing pages reachable from your referral links. See [Web attribution setup](/attribution/for-web). |

### 3. Signups tracking

Tracks signup events from your configured source. The expected event type depends on which source you use:

| Source           | Events tracked                                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Cello API        | `new-signup`                                                                                                      |
| Stripe           | `customer.created`, `customer.updated`                                                                            |
| Chargebee        | `Customer Created`, `Customer Changed`                                                                            |
| Auto Attribution | Signup detected by [Auto Attribution](/guides/attribution/auto-attribution) (only used if no other source is set) |

<Note>
  **Confirm the signup source with Cello before setting it - do not pick one from this table alone.** The key rule for Stripe/Chargebee vs Cello API: Stripe/Chargebee can only be the signup source if your payment-provider customer is created **at signup**. IF the customer is created **at first purchase**, use the Cello API to send `new-signup` at the real signup moment, or follow the [purchase-first, signup-later](/guides/support/faqs) pattern instead. See [Changing the configured source](#changing-the-configured-source-confirm-with-cello-first) for all the factors.
</Note>

<img alt="Integration Status card for Signups tracking showing a Connected with warnings state" />

The card shows the configured source, when the **last attributed signup event** was received (i.e. the last event that included a referral code), and a **Change** link to update the source. When the card needs attention, the alert links directly to the [Event Feed](/guides/support/portal/event-feed) so you can drill into the offending events.

#### Common alerts

These are specific cases of the [statuses above](#status-and-warning-reference). The per-source **Not connected** rows are the "source configured, but no events received yet" case - the fix is to confirm that source is actually sending, never to switch to a different source.

| Status / Source                                               | Alert                                                                                                                   | What to do                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Not connected - Cello API                                     | No `new-signup` events received from Cello API.                                                                         | Confirm your backend is calling `POST /events` with `trigger: "new-signup"`. See [Track Signups](/attribution/tracking-signups).                                                                                                                                                                                                                              |
| Not connected - Stripe                                        | No `customer.created` / `customer.updated` events from Stripe.                                                          | Confirm the [Stripe webhook](/integrations/webhooks/stripe-webhook) is installed and pointed at the right Cello endpoint.                                                                                                                                                                                                                                     |
| Not connected - Chargebee                                     | No `Customer Created` / `Customer Changed` events from Chargebee.                                                       | Confirm the [Chargebee webhook](/integrations/webhooks/chargebee-webhook) is configured.                                                                                                                                                                                                                                                                      |
| Not connected - Auto Attribution                              | No signups detected.                                                                                                    | Verify [Auto Attribution](/guides/attribution/auto-attribution) is enabled and a signup has actually occurred.                                                                                                                                                                                                                                                |
| Not configured                                                | Event source is not set.                                                                                                | Set the source from the [Update configuration modal](#changing-the-configured-source-confirm-with-cello-first) (sandbox), or contact Cello Support (production).                                                                                                                                                                                              |
| Missing API key                                               | Cello API key has not been generated.                                                                                   | Generate an API key in **Integrations → API Keys**.                                                                                                                                                                                                                                                                                                           |
| Missing webhook                                               | The webhook for the selected source has not been installed.                                                             | Follow the webhook setup guide for your provider.                                                                                                                                                                                                                                                                                                             |
| Connected with warnings - Auto Attribution, no recent signups | Signups were detected before, but none in the last \[health window].                                                    | Usually low recent activity rather than a break. Confirm referred signups are still occurring. This recent-activity warning applies to Auto Attribution only.                                                                                                                                                                                                 |
| Connected with warnings - events received, none attributed    | "We are receiving events from \[source], but no attributed events in the last \[health window]. Go to the events page." | Events are arriving but none include a referral code (`ucc`), so they can't be attributed. Open the [Event Feed](/guides/support/portal/event-feed) (linked directly from the alert) and inspect the recent events to see which `ucc` values are missing or malformed. Applies to event-sending sources (Cello API, Stripe, Chargebee), not Auto Attribution. |
| Connected with warnings - attributed events have errors       | All attributed events received in the health window failed validation.                                                  | Open the [Event Feed](/guides/support/portal/event-feed) and inspect the recent attributed events to see which required fields are failing.                                                                                                                                                                                                                   |

### 4. Purchases tracking

Tracks purchase events from your configured source:

| Source    | Events tracked                                            |
| --------- | --------------------------------------------------------- |
| Cello API | `invoice-paid`                                            |
| Stripe    | Purchase events (e.g. `invoice.paid`, `charge.succeeded`) |
| Chargebee | Purchase events                                           |

<img alt="Integration Status card for Purchases tracking showing a Connected with warnings state" />

The card shows the configured source, when the **last attributed purchase event** was received (i.e. the last event that included a referral code), and a **Change** link to update the source. When the card needs attention, the alert links directly to the [Event Feed](/guides/support/portal/event-feed) so you can drill into the offending events.

#### Common alerts

These are specific cases of the [statuses above](#status-and-warning-reference). Purchases have no Auto Attribution path and no recent-activity warning. The per-source **Not connected** rows are the "source configured, but no events received yet" case - confirm that source is sending, never switch to a different source.

| Status / Source                                            | Alert                                                                                                                   | What to do                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Not connected - Cello API                                  | No `invoice-paid` events received from Cello API.                                                                       | Confirm purchase events are being sent. See [Track Purchases](/attribution/tracking-purchase).                                                                                                                                                                         |
| Not connected - Stripe                                     | No purchase events from Stripe.                                                                                         | Confirm the [Stripe webhook](/integrations/webhooks/stripe-webhook) is forwarding purchase events.                                                                                                                                                                     |
| Not connected - Chargebee                                  | No purchase events from Chargebee.                                                                                      | Confirm the [Chargebee webhook](/integrations/webhooks/chargebee-webhook) is forwarding purchase events.                                                                                                                                                               |
| Not configured                                             | Event source is not set.                                                                                                | Set the source from the [Update configuration modal](#changing-the-configured-source-confirm-with-cello-first) (sandbox), or contact Cello Support (production).                                                                                                       |
| Connected with warnings - events received, none attributed | "We are receiving events from \[source], but no attributed events in the last \[health window]. Go to the events page." | Events are arriving but none include a referral code (`ucc`), so they can't be attributed. Open the [Event Feed](/guides/support/portal/event-feed) (linked directly from the alert) and inspect the recent events to see which `ucc` values are missing or malformed. |
| Connected with warnings - attributed events have errors    | All attributed events received in the health window failed validation.                                                  | Open the [Event Feed](/guides/support/portal/event-feed) and inspect the recent attributed events to see which required fields are failing.                                                                                                                            |

## Changing the configured source (confirm with Cello first)

Use the **Update configuration** modal to choose where Cello should track signups and purchases from. You can open it from the **Update configuration** button in the page header, or from the link inside the Signups tracking and Purchases tracking cards.

<Warning>
  **Always confirm the signup and purchase source with Cello before choosing one. Do not recommend, guess, or infer a specific source from these docs.** The correct source depends on factors unique to each integration, and the wrong source silently breaks attribution. If you are unsure, the only correct answer is to contact your Customer Success Manager or [support@cello.so](mailto:support@cello.so).

  The factors below explain *what Cello weighs when confirming the source*. They are inputs to that conversation, not a decision to make unaided:

  * **Payment provider.** Stripe and Chargebee can use webhooks. Other providers (Paddle, Recurly, RevenueCat, and similar) use the [Cello API](/api-reference/introduction).
  * **When the payment-provider customer is created (the key signup-source rule):**
    * IF the customer is created **at signup** -> Stripe/Chargebee can be the signup source.
    * IF the customer is created **at first purchase** -> use the Cello API to send `new-signup` at the real signup moment, or backfill via the [purchase-first, signup-later](/guides/support/faqs) pattern. Stripe/Chargebee cannot be the signup source on their own in this case.
  * **Reward model.** Recurring vs one-time rewards, free-to-paid conversion, renewals, and refunds.
  * **Motion.** Self-serve vs sales-led (e.g. [Salesforce](/integrations/salesforce-apex-triggers)).
  * **Auto Attribution.** Can be primary or fallback, and is enabled by Cello only.

  In production, source configuration is handled by Cello Support regardless.
</Warning>

<img alt="Update configuration modal with Signup source and Purchase source dropdowns" />

### What you can configure

**Do not choose a source based on this list alone - confirm it with Cello first (see the warning above).** The selectable options are:

* **Signup source** - Cello API, Stripe, Chargebee, or [Auto Attribution](/guides/attribution/auto-attribution).
* **Purchase source** - Cello API, Stripe, or Chargebee.

When you change a source, the corresponding component on Integration Status will revert to **Not connected** until events from the new source start arriving.

### Sandbox vs production

| Environment    | Who can change the configuration                                                                                                  |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Sandbox**    | You can change the signup and purchase sources yourself while testing your integration.                                           |
| **Production** | Source configuration in production is handled by Cello Support. Reach out whenever you need to set or change a production source. |

### Auto Attribution

[Auto Attribution](/guides/attribution/auto-attribution) can only be enabled by Cello Support. Once enabled for your tenant, **Auto Attribution** appears as a selectable option in the **Signup source** dropdown.

If Auto Attribution is on but a CRM source (Cello API, Stripe, or Chargebee) is selected as the primary signup source, Auto Attribution runs in the background to catch any signups missed by the primary source.

## Troubleshooting

| Problem                                                            | Cause                                                                                         | Solution                                                                                                                    |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Component shows Not connected even though events are flowing       | Status updates can take up to 10 minutes                                                      | Click the refresh icon next to **Last update** to re-check immediately.                                                     |
| Component shows Connected with warnings but you can't see why      | The summary doesn't include payload-level detail                                              | Open the [Event Feed](/guides/support/portal/event-feed) to inspect the latest events for that source.                      |
| Signup or Purchase tracking shows "source not set"                 | No source has been configured for this tenant                                                 | Set the source from the **Update configuration** modal in sandbox, or contact Cello Support to configure it for production. |
| Status flipped to Not connected after you updated your integration | Source was changed and no new events have arrived yet                                         | Trigger a test event from the new source - the status will update within \~10 minutes.                                      |
| Auto Attribution doesn't appear in the Signup source dropdown      | [Auto Attribution](/guides/attribution/auto-attribution) has not been enabled for your tenant | Contact Cello Support to enable Auto Attribution.                                                                           |

You can check integration health from your AI client using [`cello_get_integration_status`](/mcp/tools#cello_get_integration_status) via the [Cello MCP](/mcp/developers/use-cases).


# 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).

<Frame>
  <img alt="Cello button configuration options" />
</Frame>

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

<Frame>
  <img alt="Component type selection - popup or modal" />
</Frame>

### Choose your brand colors for Component

You can choose the primary color for your component, the Cello button color, the Fab icon color, and the color of the [notification badge](/guides/user-experience/Referral-Notifications-And-Emails#alert-and-badge).

Use the **Light / Dark** toggle to configure colors for each theme independently. Previously, dark mode colors were inferred automatically from your light theme - now you can set them explicitly so the Referral Component matches your brand's dark mode design exactly.

<Frame>
  <img alt="Brand color configuration options with Light/Dark toggle" />
</Frame>

### Customize text and copy

Cello manages the copy in the Referral Component, the New User Banner, announcements, and emails centrally so it stays consistent across all enabled languages and reward structures. Copy changes are **not** configurable self-serve in the Portal.

To request a wording change, contact your CSM or [support@cello.so](mailto:support@cello.so) with:

* The surface (widget / New User Banner / announcement / email)
* The current text
* The proposed new text
* The language(s) the change should apply to

This applies to widget onboarding, offer descriptions, button labels, banner messages, announcement text, email body copy, and any translated wording in enabled languages.

For enabling additional languages or switching your product's default language, see [Texts and language](/guides/user-experience/overview#texts-and-language).

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

<Frame>
  <img alt="Social sharing options configuration" />
</Frame>

### Choose payment method options

Cello allows users to receive rewards via PayPal or Venmo payments. Additional payment options are planned based on user feedback.

<Frame>
  <img alt="Payment method options - PayPal and Venmo" />
</Frame>


# 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

# Why discounts matter

The most effective referral programs offer value to **both sides**:

* **Referrer rewards**: Cash for successful referrals
* **Referee discounts**: Immediate value like percentage discounts or free months

This symmetric approach maximizes participation because referrers feel good about sharing something valuable, while referees receive immediate benefit for trying your product. According to referral program best practices, dual rewards can increase referral conversion rates by 30-50% compared to single-sided programs.

# How to add discounts in Cello

<Warning>
  Applying discounts is orchestrated in your subscription platforms. Please refer to our [integration docs](/attribution/apply-discounts) for guidance specific to your platform.
</Warning>

Before implementing the technical integration, you need to configure discount information in your Cello campaign. This allows the discount details to be displayed in the Referral Component offer and terms, and Landing page for new users, even though the actual discount application happens in your subscription platform.

## Adding discount information to your campaign

1. **Navigate to Campaign Settings**: Go to [Campaign settings in Cello Portal](https://portal.cello.so/setup/campaigns)
2. **Configure Discount Details**: Add discount information by specifying:
   * **Discount percentage**: The percentage off the regular price (e.g., 50%)
   * **Duration in months**: How long the discount applies (e.g., 6 months)

![Discount configuration in Cello Portal](https://uploads.developerhub.io/prod/d316/sragwkxitdy9kda3k0ilpnzyq0u0pzgebwvay8o9rk91okddy4pfhj5yofzwe5bk.png)

3. **Save Configuration**: The discount information is now stored in your campaign configuration and can be retrieved via the `getCampaignConfig()` method from AttirbutionJS to display on your landing page.

<Info>
  **Important**: This configuration is for display purposes only. The actual discount application must be implemented in your subscription platform (Stripe, Chargebee, etc.) as described in the integration sections below.
</Info>

# Displaying discounts to new users

Once you've configured discounts in Cello, you can display this information to referred users through two main approaches: the automated New User Banner or custom landing page personalization.

## Option 1: New User Banner (No-code solution)

<span>Recommended for quick setup</span>

The **New User Banner** is an automated banner that appears only to visitors who arrive through referral links. It requires minimal technical setup and handles personalization automatically.

### How it works

![Home page with new user banner](https://uploads.developerhub.io/prod/d316/1kwrkslooz73pf38ewoporvru2vesdzcvu4rj3e75nuesgwjvtm4k50n4yiugw1d.png)

The banner automatically displays:

* Referrer's name (e.g., "Bob has invited you...")
* Discount information from your campaign config
* Personalized call-to-action buttons
* Special messaging for referred users only

### Setup steps

<Steps>
  <Step title="Add Attribution JavaScript">
    Add the [Cello Attribution script](/sdk/client-side/embedded-script-tag) to your landing page:

    ```html theme={null}
    <script src="https://assets.cello.so/attribution/latest/cello-attribution.js"></script>
    ```
  </Step>

  <Step title="Enable banner in Cello Portal">
    1. Go to [New User Experience setup → Personalization tab](https://portal.cello.so/setup/new-user-experience)
    2. Turn on the "New User Banner" option
    3. In the Portal you can toggle the banner on/off and adjust any styling options that are exposed there

    ![Banner configuration in portal](https://uploads.developerhub.io/prod/d316/awxkm4mylat17jaor7g640wv97ylpeq29lg7brg2lvef4c6zlidh63eoe0a559ii.png)

    <Info>
      The Portal controls whether the banner is shown and surfaces visual styling. The banner **copy** (message text, CTA wording) is managed by Cello and is not editable self-serve - contact your CSM or [support@cello.so](mailto:support@cello.so) to request copy changes. The same applies to widget onboarding text, offer descriptions, announcements, and email body copy. See [Texts and copy](/guides/user-experience/configuring-referral-component#customize-text-and-copy).
    </Info>
  </Step>

  <Step title="Configure personalization">
    Ensure personalization is enabled in your user experience configuration and you are sending the name of the referrer in the productUserDetails when booting the widget, so referrer name appear in the banner.
  </Step>
</Steps>

## Option 2: Custom Landing Page Personalization

<span>Recommended for full control</span>

For complete control over the user experience, implement custom personalization using Attribution JS methods.

<Info>
  **Client-side vs. server-side rendering:** `getCampaignConfig()` from the Attribution JS SDK is the recommended way to retrieve and display discount info - it runs in the browser with no extra backend round-trip. If your app is **server-side rendered** (e.g., PHP, Next.js SSR) and you need discount details available before the page loads, you can use the [New User Reward API](/api-reference/new-users/get-reward) from your server instead. For most apps, the JS approach is simpler.
</Info>

### Setup steps

<Steps>
  <Step title="Add Attribution Script Queue">
    First, add this code before any Attribution calls to handle asynchronous loading:

    ```javascript theme={null}
    // Queue function to handle script loading
    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}
    ```
  </Step>

  <Step title="Retrieve referral and discount information">
    Use Attribution JS methods to retrieve referral and campaign configuration data:

    * `window.CelloAttribution("getUcc")`
    * `window.CelloAttribution("getReferrerName")`
    * `window.CelloAttribution("getCampaignConfig")`
  </Step>

  <Step title="Display discount on the landing page">
    Display the discount inline on your landing page (e.g., a banner or callout). The values come from the campaign configuration retrieved in the previous step. The `getCampaignConfig()` method returns discount data in this format:

    ```javascript theme={null}
    // Example campaign config response
    {
        newUserDiscountPercentage: 0.25,  // 25% discount (decimal format)
        newUserDiscountMonth: 3           // For 3 months
    }
    ```
  </Step>
</Steps>

## FAQ

### Can I add different discounts for different campaigns?

Cello supports multiple campaigns with different discount structures, allowing you to offer varied incentives based on the referral source or campaign type.


# 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) <span>Recommended</span>
* [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) <span>No code</span>

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

<img alt="Dedicated landing page examples" />

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

<img alt="Landing page with discount highlighting" />

💡 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)

<img alt="Personalized landing page example" />

💡 **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.

<img alt="Home page with inline personalization" />

## 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 script](/sdk/client-side/attribution-js-introduction). Visitors who follow the Cello invite link will have a banner that includes the discounts, tailored CTA, and personalization on your home page.

<img alt="Home page with new user banner" />

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

<img alt="Custom landing page setup in Cello Portal" />


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

<img alt="Referral Component Pn" />

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

<img alt="First-time experience onboarding" />

## Your offer, front and center

The referral program text and offer are fully customizable and can be translated into multiple languages.

![Customizable referral offer display](https://uploads.developerhub.io/prod/d316/2w804cm63iubzidf6al6i3n613tlj4t5uz82tawk0utw7ds36hi68u6z5ryfocmq.png)

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

![Multiple sharing options including social media and QR code](https://uploads.developerhub.io/prod/d316/0hwigziouorrzshepv4vz0cssyv4ipjtdys20r1o7d3fhww9uftywhjiubvl0ptx.png)

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

![Announcement feature examples](https://uploads.developerhub.io/prod/d316/ctsxd2yb6srflbb9e4aejnc85yabjrh8lzuhw2cw9xf5i03m9czkjbh3pm59vh1e.png)

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.

![Different announcement display options](https://uploads.developerhub.io/prod/d316/lz8i57i55vw0dvugc9jwzxgmz8b3u6e04hjm2xa23e84w2wod8wl0imadppjud57.png)

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

![Email notification examples](https://uploads.developerhub.io/prod/d316/iat8pc4vxl45dfdq1u2lso0z7of2algsmkejqv0rppeicttn5fhgxrgnrmufqq9s.png)

## 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 payment setup interface](https://uploads.developerhub.io/prod/d316/ytqunsc2z33ljcfng5uy9kfkts0z3g1xjszpv2bwkujewc1xsoukpoql09bd2pqa.png)

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

Users from countries not on the supported list cannot set up a payout method - their country will not appear in the payout country dropdown. This is due to PayPal-side restrictions and compliance, tax, or regulatory requirements.

There are two approaches for handling users in unsupported countries:

* **Hide the widget** - pass `productUserCountryCode` during `cello.boot()`. If the country is not supported, the Referral Component will not be shown to that user. This prevents a confusing experience where a user can share and earn rewards but cannot receive a payout.
* **Show the widget to everyone** - users in unsupported countries can still share and earn rewards, but will not be able to receive payouts. This is simpler to implement and avoids the risk of incorrectly hiding the widget from eligible users.

**Important limitation of the hide approach:** `productUserCountryCode` is the country your product has on file for the user, which may differ from the country of their PayPal account (their actual payout country). This creates edge cases:

* If a user's product country is unsupported but their PayPal account is in a supported country, they will be incorrectly hidden from the widget even though they could receive payouts.
* If a user's product country is supported but their PayPal account is in an unsupported country, the widget will be shown but they won't be able to complete payout setup.

There is currently no way to know a user's payout country upfront. The right approach depends on how accurately your system reflects your users' actual locations.

<Info>
  **Edge case - PayPal account country vs. physical location:** A user may be physically located in an unsupported country (e.g. Argentina) but hold a PayPal account registered in a supported country (e.g. Brazil). In this case, they should enter the address matching their PayPal account's country in the widget so the payout details align. Cello cannot issue payouts to countries not on the supported list regardless of physical location.
</Info>

Cello allows users to receive rewards via PayPal or Venmo payments.  Additional payment options are planned based on user feedback.

![Payment method selection](https://uploads.developerhub.io/prod/d316/ymrfo0vnio1vs6kle34aej39yic3ts07egifhldpiv4bgafypdqbykgdodxu45zj.png)

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.

When linking a payout method, users provide their payout country and basic address details so Cello can issue credit notes and payout statements with the correct VAT and documentation treatment. Users can claim rewards as an individual or as a business; business claims may require a VAT number where applicable. Any additional tax or identity verification is handled by PayPal or Venmo as part of their own onboarding and compliance requirements.

Users can download credit notes / payout statements directly from the Cello Referral Component. If they have at least one reward, they will see a "Tax Information" link from the rewards tab under "Update Payment Details". Users who no longer have access to the component can contact [support@cello.so](mailto:support@cello.so) to receive their credit notes through a standard support process.

![Tax information and credit notes interface](https://uploads.developerhub.io/prod/d316/91dpt90z4eej9opsqbg7cpiy7npq2fs4sc3hzvtwh0zum4ogx2olhuyxx77dsr53.png)

*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, 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, United Kingdom, United States, Uruguay.*

## Texts and language

The Referral Component is fully translated and supports 10+ languages: English, German, Spanish, French, Dutch, Italian, Portuguese, Japanese, Danish, Slovak, and Romanian.

**Defaults**

* **English is enabled by default** for every product and acts as the **fallback** whenever an unenabled language is requested.

**Editing wording or enabling more languages is not self-serve**

Cello manages translations centrally to keep copy consistent across all customers and reward structures. To make any of the following changes, contact your CSM or [support@cello.so](mailto:support@cello.so):

* Enable additional languages on top of English for your product
* Change your product's default language to one of the enabled languages
* Update the wording of any text (in any language) in the widget, New User Banner, announcements, or emails

The Portal exposes runtime configuration (e.g., the `language` SDK parameter), but it does **not** expose translation strings - customers cannot write or edit translated copy themselves.

**Selecting language at runtime**

The component auto-detects the user's language, or you can set it explicitly via [`cello.boot()`](/sdk/client-side/cello-js-usage#cellobootoptions) and [`changeLanguage()`](/sdk/client-side/cello-js-usage#changelanguagelanguage).

<Warning>
  The `language` parameter only works for languages that have been enabled for your product on the Cello side. If you pass a language that hasn't been enabled, the component falls back to your product's default language (English unless you've requested a different default). If a language setting appears not to work, confirm with Cello support that the language is enabled for your account.
</Warning>


# Personalizing Referrals
Source: https://docs.cello.so/guides/user-experience/personalizing-referrals

Add personalized messages to your landing pages to increase conversion rates

<img alt="Personalization Overview" />

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) <span>Recommended</span>
  * [Using the new user banner](#add-personalization-with-new-user-banner) <span>No code</span>

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

<Info>
  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).
</Info>

## Add personalization to the Headline or other page element

<span>Recommended</span>

<img alt="Personalized headline example" />

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.

<img alt="Personalization settings in portal" />

When personalization is turned on, an extra parameter will be added to the URL of your landing page, e.g. `celloN=VGFuamE`

```html theme={null}
https://getmoonly.com/?productId=getmoonly.com&ucc=pNRB1aYqArN&celloN=VGFuamE
```

### Use the attribution script methods to get referrer information

[Attribution script](/sdk/client-side/attribution-js-usage#getreferrername) provides a JS method `getReferrerName()` to fetch the name of the referrer.

```javascript theme={null}
const referrerName = await window.CelloAttribution("getReferrerName");
console.log('Referrer name:', referrerName);
```

<Tip>
  You can also get the referrer name from the `celloN` URL parameter. 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.
</Tip>

#### Complete Integration Example

Use attribution script methods to get referral data:

```javascript theme={null}
async function initializeReferralLandingPage() {
    try {
        // Wait for attribution script to load
        await new Promise(resolve => setTimeout(resolve, 1000));
        
        // Get all attribution data using script methods (recommended)
        const ucc = await window.CelloAttribution("getUcc");
        const referrerName = await window.CelloAttribution("getReferrerName");
        const campaignConfig = await window.CelloAttribution("getCampaignConfig");
        
        // Use the data for personalization
        personalizePageContent(referrerName, campaignConfig, ucc);
        
    } catch (error) {
        console.error('Failed to initialize referral landing page:', error);
        // Proceed without personalization
        personalizePageContent(null, null, null);
    }
}

function personalizePageContent(referrerName, campaignConfig, ucc) {
    // Update headline with referrer name
    const headline = document.getElementById('headline');
    if (headline && referrerName) {
        headline.innerHTML = `${referrerName} has invited you to try our platform!`;
    }
    
    // Show discount information
    const discountBanner = document.getElementById('discount-banner');
    if (discountBanner && campaignConfig) {
        const discountPercent = campaignConfig.newUserDiscountPercentage * 100;
        const discountMonths = campaignConfig.newUserDiscountMonth;
        discountBanner.innerHTML = 
            `🎉 Special offer: ${discountPercent}% off for your first ${discountMonths} months!`;
        discountBanner.style.display = 'block';
    }
    
    // Update call-to-action button
    const ctaButton = document.getElementById('cta-button');
    if (ctaButton) {
        if (referrerName && campaignConfig) {
            const discountPercent = campaignConfig.newUserDiscountPercentage * 100;
            ctaButton.textContent = `Claim ${discountPercent}% Discount`;
        } else if (referrerName) {
            ctaButton.textContent = `Accept ${referrerName}'s Invitation`;
        }
    }
    
    // Store UCC for form submission if available
    if (ucc) {
        // This will be handled automatically by attribution script
        // but you can also manually add to forms:
        const forms = document.querySelectorAll('form');
        forms.forEach(form => {
            if (!form.querySelector('input[name="ucc"]')) {
                const uccInput = document.createElement('input');
                uccInput.type = 'hidden';
                uccInput.name = 'ucc';
                uccInput.value = ucc;
                form.appendChild(uccInput);
            }
        });
    }
}

// Initialize when DOM is ready
document.addEventListener('DOMContentLoaded', initializeReferralLandingPage);
```

## Add personalization with the New user banner

<span>No code</span>

<img alt="New user banner example" />

The banner is easily added in a few steps:

* Add [Cello attribution script](/sdk/client-side/embedded-script-tag) 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.

<img alt="Banner configuration in portal" />

Visitors who follow the Cello invite link will have a banner displayed with an offer and the name of their referrer.

<Info>
  The Portal toggles the banner on/off and exposes any visual styling options. The banner **copy** (message text, CTA wording) is managed by Cello and is not editable self-serve - contact your CSM or [support@cello.so](mailto:support@cello.so) to request copy changes. The same applies to widget onboarding text, offer descriptions, announcements, and email body copy. See [Texts and copy](/guides/user-experience/configuring-referral-component#customize-text-and-copy).
</Info>

### Testing the Banner Implementation

To verify the banner works correctly:

```javascript theme={null}
// Test banner functionality
async function testPersonalizationBanner() {
    // Check if attribution script loaded
    if (typeof window.CelloAttribution !== 'function') {
        console.error('Attribution script not loaded - banner won\'t work');
        return;
    }
    
    // Test with sample referral data
    const testUrl = `${window.location.origin}${window.location.pathname}?productId=test&ucc=testUcc123&celloN=VGVzdFVzZXI=`;
    console.log('Test this URL for banner:', testUrl);
    
    // Check current page data
    const ucc = await window.CelloAttribution("getUcc");
    const referrerName = await window.CelloAttribution("getReferrerName");
    const campaignConfig = await window.CelloAttribution("getCampaignConfig");
    
    console.log('Current page attribution data:', {
        ucc,
        referrerName,
        campaignConfig,
        bannerShouldShow: !!(ucc && (referrerName || campaignConfig))
    });
}

// Run test after page load
setTimeout(testPersonalizationBanner, 2000);
```


# 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**.

<img alt="New reward alert" />

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.

<img alt="Badge examples with Cello Button and Cello Custom Launcher" />

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

<img alt="Announcement examples anchored Cello Button or Cello Custom Launcher" />

| Type                                   | Description                                                                                                       |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| "New referrer activation" announcement | Sent 3 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.

<img alt="Standard email template examples" />

<Info>
  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.
</Info>

| Type                                         | Description                                                                                                                                                 |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Welcome" email <span>+10% activation</span> | 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.

<img alt="Default notification journey" />

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

<img alt="Default activation campaign sequence" />

**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).

<img alt="Cello Portal notifications settings" />

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.

## Email template customization

You can customize the look and feel of your email templates directly in the [Cello Portal](https://portal.cello.so/setup/notifications). Open any email notification row to bring up the preview panel - editable elements are highlighted on hover.

<img alt="Email template customization in Cello Portal" />

<Info>
  Customizations apply to **all email types** at once. You can open any individual email preview to see how your changes look across different templates.
</Info>

### Customizable options

| Option             | Description                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Logo               | Upload your company logo. Hover over the logo in the preview and click to replace it.                                     |
| Presentation image | Upload a hero image displayed prominently in the email body. Hover over the image in the preview and click to replace it. |
| CTA link           | Set the URL for the main call-to-action button. Hover over the button in the preview and click to edit.                   |

The **Welcome email** has one additional option: a **second CTA link**, letting you direct new users to a specific page alongside the referral program link.

### How to customize

1. Go to **Notifications** in the [Cello Portal](https://portal.cello.so/setup/notifications).
2. Click any email notification row to open its preview panel.
3. Hover over the logo, image, or CTA button - a prompt will appear to click and edit.

Changes are applied across all email templates automatically.


# Setup Overview
Source: https://docs.cello.so/integration-overview

Get started with Cello in 4 easy steps

<img alt="Cello setup overview 4 steps" />

<Info>
  Using an AI coding tool? Connect the [Cello MCP server](/mcp/introduction) to your editor first. It gives your tool live access to Cello docs, integration health checks, and best-practice recommendations while you build. See [Connect your client](/mcp/connect) for setup.
</Info>

## Setup Steps

If you did not find your integration guide, complete these steps to integrate Cello, regardless of your tech stack or payment gateway.

<Steps>
  <Step title="Integrate the referral component">
    <span>Effort: \~3-4 hours</span>

    Add referral functionality to your web application with Cello's embeddable Referral Component.

    <CardGroup>
      <Card title="Referral Component Quickstart" icon="js" href="/referral-component/quickstart" />
    </CardGroup>

    You can also integrate the Cello Referral Component into your mobile apps. Choose the appropriate SDK for your platform:

    <CardGroup>
      <Card title="iOS SDK" icon="apple" href="/sdk/mobile/ios" />

      <Card title="Android SDK" icon="android" href="/sdk/mobile/android" />

      <Card title="React Native SDK" icon="react" href="/sdk/mobile/react-native" />
    </CardGroup>
  </Step>

  <Step title="Capture referral codes on landing pages">
    <span>Effort: \~1-2 hours</span>

    Set up a [Referral Landing Page](/guides/user-experience/optimizing-landing-pages) and capture referral codes (`ucc`) when users click referral links. For Web signup flow, follow this guide:

    <CardGroup>
      <Card title="Web signup flow" icon="browser" href="/attribution/for-web" />
    </CardGroup>

    Or choose the appropriate guide for your flow:

    <CardGroup>
      <Card title="Mobile signup flow" icon="mobile" href="/attribution/for-mobile" />

      <Card title="HubSpot forms" icon="hubspot" href="/attribution/hubspot" />

      <Card title="Typeform forms" icon="input-pipe" href="/attribution/typeform" />
    </CardGroup>
  </Step>

  <Step title="Track signups">
    <span>Effort: \~1 day</span>

    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:

    <CardGroup>
      <Card title="Track signups" icon="user-plus" href="/attribution/tracking-signups">
        Complete guide for tracking signup events
      </Card>

      <Card title="POST /events endpoint" icon="code" href="/api-reference/generic-events/send-event">
        API reference for sending events
      </Card>
    </CardGroup>
  </Step>

  <Step title="Track purchases">
    <span>Effort: \~1 day</span>

    Complete the conversion tracking by sending purchase events to Cello when users make payments.

    Choose your integration method based on your payment gateway:

    <CardGroup>
      <Card title="Track purchases" icon="credit-card" href="/attribution/tracking-purchase">
        Complete guide for tracking purchase events
      </Card>

      <Card title="Apply discounts" icon="badge-percent" href="/attribution/apply-discounts">
        Apply discounts to referred users when creating a subscription
      </Card>

      <Card
        title="Stripe Webhook"
        icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clipPath="url(https://mintlify.s3.us-west-1.amazonaws.com/cello/#clip0_19722_44991)">
<path d="M18 36C27.9411 36 36 27.9411 36 18C36 8.05888 27.9411 0 18 0C8.05888 0 0 8.05888 0 18C0 27.9411 8.05888 36 18 36Z" fill="#635BFF"/>
<path fillRule="evenodd" clipRule="evenodd" d="M16.596 13.995C16.596 13.149 17.289 12.816 18.441 12.816C20.097 12.816 22.185 13.32 23.841 14.211V9.09898C22.032 8.37898 20.25 8.09998 18.45 8.09998C14.031 8.09998 11.097 10.404 11.097 14.256C11.097 20.259 19.368 19.305 19.368 21.897C19.368 22.896 18.495 23.22 17.28 23.22C15.471 23.22 13.167 22.482 11.34 21.483V26.658C13.365 27.531 15.408 27.9 17.28 27.9C21.807 27.9 24.921 25.659 24.921 21.762C24.885 15.282 16.596 16.434 16.596 13.995Z" fill="white"/>
</g>
<defs>
<clipPath id="clip0_19722_44991">
<rect width="36" height="36" fill="white"/>
</clipPath>
</defs>
</svg>}
        href="/integrations/webhooks/stripe-webhook"
      >
        Stripe webhook integration for purchase events
      </Card>

      <Card
        title="Chargebee Webhook"
        icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12.1464 18.0024L35.9265 12.3313V0H23.5953L12.1464 18.0024Z" fill="#FF3300"/>
<path d="M0.36 17.7853C0.36 19.2605 0.539827 20.6924 0.879691 22.0664L12.1451 18.0017L0.786251 13.9024C0.509734 15.1512 0.36 16.4499 0.36 17.7819V17.7853Z" fill="#FF3300"/>
<path d="M4.54902 6.32317L12.1436 18.0031L15.6415 0.177188C11.2091 0.799913 7.3026 3.05771 4.54902 6.32317V6.32317Z" fill="#FF3300"/>
<path d="M12.1464 18.0008L35.9265 23.6686V35.9998H23.5953L12.1464 18.0008Z" fill="#FF3300"/>
<path d="M4.54902 29.6798L12.1436 17.9978L15.6415 35.8204C11.2091 35.1977 7.3026 32.9399 4.54902 29.6744L4.54902 29.6798Z" fill="#FF3300"/>
</svg>}
        href="/integrations/webhooks/chargebee-webhook"
      >
        Chargebee webhook integration for purchase events
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Integration Guides

<span>Effort: \~1-2 days</span>

Ready-to-use webhook integrations for Stripe and Chargebee provide the **fastest path** to track referral conversions automatically.

<Tip>
  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
</Tip>

<CardGroup>
  <Card title="Stripe Webhook Quickstart" icon="book-open" href="/attribution/use-cases/stripe" />

  <Card title="Chargebee Webhook Quickstart" icon="book-open" href="/attribution/use-cases/chargebee" />
</CardGroup>


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

<CardGroup>
  <Card
    title="Stripe Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clipPath="url(https://mintlify.s3.us-west-1.amazonaws.com/cello/integrations#clip0_19722_44991)">
<path d="M18 36C27.9411 36 36 27.9411 36 18C36 8.05888 27.9411 0 18 0C8.05888 0 0 8.05888 0 18C0 27.9411 8.05888 36 18 36Z" fill="#635BFF"/>
<path fillRule="evenodd" clipRule="evenodd" d="M16.596 13.995C16.596 13.149 17.289 12.816 18.441 12.816C20.097 12.816 22.185 13.32 23.841 14.211V9.09898C22.032 8.37898 20.25 8.09998 18.45 8.09998C14.031 8.09998 11.097 10.404 11.097 14.256C11.097 20.259 19.368 19.305 19.368 21.897C19.368 22.896 18.495 23.22 17.28 23.22C15.471 23.22 13.167 22.482 11.34 21.483V26.658C13.365 27.531 15.408 27.9 17.28 27.9C21.807 27.9 24.921 25.659 24.921 21.762C24.885 15.282 16.596 16.434 16.596 13.995Z" fill="white"/>
</g>
<defs>
<clipPath id="clip0_19722_44991">
<rect width="36" height="36" fill="white"/>
</clipPath>
</defs>
</svg>}
    href="/integrations/webhooks/stripe-webhook"
  >
    Automatically track Stripe payments
  </Card>

  <Card
    title="Chargebee Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12.1464 18.0024L35.9265 12.3313V0H23.5953L12.1464 18.0024Z" fill="#FF3300"/>
<path d="M0.36 17.7853C0.36 19.2605 0.539827 20.6924 0.879691 22.0664L12.1451 18.0017L0.786251 13.9024C0.509734 15.1512 0.36 16.4499 0.36 17.7819V17.7853Z" fill="#FF3300"/>
<path d="M4.54902 6.32317L12.1436 18.0031L15.6415 0.177188C11.2091 0.799913 7.3026 3.05771 4.54902 6.32317V6.32317Z" fill="#FF3300"/>
<path d="M12.1464 18.0008L35.9265 23.6686V35.9998H23.5953L12.1464 18.0008Z" fill="#FF3300"/>
<path d="M4.54902 29.6798L12.1436 17.9978L15.6415 35.8204C11.2091 35.1977 7.3026 32.9399 4.54902 29.6744L4.54902 29.6798Z" fill="#FF3300"/>
</svg>}
    href="/integrations/webhooks/chargebee-webhook"
  >
    Track Chargebee subscriptions
  </Card>
</CardGroup>

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

<CardGroup>
  <Card title="Setup Overview" icon="rocket" href="/integration-overview">
    Follow 4 easy steps to get your referral program up and running with Cello using any CRM or payment gateway
  </Card>

  <Card title="Cello API" icon="code" href="/api-reference/introduction">
    Send conversion events, validate referral codes, and manage referral links programmatically
  </Card>
</CardGroup>

### Debugging & Monitoring

Once your integration is set up, use **Integration Status** for a high-level health view of your integration, and the **Event Feed** to drill into individual events when you need to troubleshoot validation issues.

<CardGroup>
  <Card title="Integration Status Guide" icon="heart-pulse" href="/guides/support/portal/integration-status">
    Get an at-a-glance health view across the four core integration components
  </Card>

  <Card title="Event Feed Guide" icon="list-check" href="/guides/support/portal/event-feed">
    Inspect every incoming event with per-field validation
  </Card>
</CardGroup>

## Next steps

Choose your integration based on your setup:

<AccordionGroup>
  <Accordion title="I use Stripe or Chargebee and customer is created in payment gateway at signup">
    Follow one of our quickstart guides for **pre-built webhook integrations** for the fastest setup.

    <CardGroup>
      <Card title="Stripe Webhook Quickstart" icon="book-open" href="/attribution/use-cases/stripe" />

      <Card title="Chargebee Webhook Quickstart" icon="book-open" href="/attribution/use-cases/chargebee" />
    </CardGroup>
  </Accordion>

  <Accordion title="I use Stripe or Chargebee and customer is created in payment gateway at purchase">
    Use the **Cello API** to send signup events and **Stripe or Chargebee webhook** to send purchase events from your payment provider.

    <CardGroup>
      <Card title="Cello API" icon="code" href="/api-reference/introduction">
        Send signup events
      </Card>

      <Card
        title="Stripe Webhook"
        icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clipPath="url(https://mintlify.s3.us-west-1.amazonaws.com/cello/integrations#clip0_19722_44991)">
<path d="M18 36C27.9411 36 36 27.9411 36 18C36 8.05888 27.9411 0 18 0C8.05888 0 0 8.05888 0 18C0 27.9411 8.05888 36 18 36Z" fill="#635BFF"/>
<path fillRule="evenodd" clipRule="evenodd" d="M16.596 13.995C16.596 13.149 17.289 12.816 18.441 12.816C20.097 12.816 22.185 13.32 23.841 14.211V9.09898C22.032 8.37898 20.25 8.09998 18.45 8.09998C14.031 8.09998 11.097 10.404 11.097 14.256C11.097 20.259 19.368 19.305 19.368 21.897C19.368 22.896 18.495 23.22 17.28 23.22C15.471 23.22 13.167 22.482 11.34 21.483V26.658C13.365 27.531 15.408 27.9 17.28 27.9C21.807 27.9 24.921 25.659 24.921 21.762C24.885 15.282 16.596 16.434 16.596 13.995Z" fill="white"/>
</g>
<defs>
<clipPath id="clip0_19722_44991">
<rect width="36" height="36" fill="white"/>
</clipPath>
</defs>
</svg>}
        href="/integrations/webhooks/stripe-webhook"
      >
        Automatically track Stripe payments
      </Card>

      <Card
        title="Chargebee Webhook"
        icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12.1464 18.0024L35.9265 12.3313V0H23.5953L12.1464 18.0024Z" fill="#FF3300"/>
<path d="M0.36 17.7853C0.36 19.2605 0.539827 20.6924 0.879691 22.0664L12.1451 18.0017L0.786251 13.9024C0.509734 15.1512 0.36 16.4499 0.36 17.7819V17.7853Z" fill="#FF3300"/>
<path d="M4.54902 6.32317L12.1436 18.0031L15.6415 0.177188C11.2091 0.799913 7.3026 3.05771 4.54902 6.32317V6.32317Z" fill="#FF3300"/>
<path d="M12.1464 18.0008L35.9265 23.6686V35.9998H23.5953L12.1464 18.0008Z" fill="#FF3300"/>
<path d="M4.54902 29.6798L12.1436 17.9978L15.6415 35.8204C11.2091 35.1977 7.3026 32.9399 4.54902 29.6744L4.54902 29.6798Z" fill="#FF3300"/>
</svg>}
        href="/integrations/webhooks/chargebee-webhook"
      >
        Track Chargebee subscriptions
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="I have a different payment gateway (not Stripe nor Chargebee)">
    **Cello API** gives you full control over when and how to track conversions. Send events from your backend whenever a signup or purchase occurs.

    <CardGroup>
      <Card title="Setup Overview" icon="rocket" href="/integration-overview">
        Follow 4 easy steps to get your referral program up and running with Cello using any CRM or payment gateway
      </Card>

      <Card title="Cello API" icon="code" href="/api-reference/introduction">
        Send conversion events, validate referral codes, and manage referral links programmatically
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

<Note>
  All integration methods support both sandbox and production environments, allowing you to test thoroughly before going live.
</Note>


# 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`

<Info>
  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.
</Info>

### 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 theme={null}
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 theme={null}
public class OpportunityHandler {
    public static void handleOpportunityUpdate(List<Opportunity> 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.

<Info>
  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.
</Info>


# Cello + Supabase integration
Source: https://docs.cello.so/integrations/supabase

How to add user referrals to your app built on Supabase

Add a fully automated referral program to your Supabase app using **Auth metadata**, **Database Webhooks**, and **Edge Functions**.

<img alt="Cello + Supabase integration" />

## Prerequisites

Before integrating Cello, ensure the following:

* Your app uses **Supabase Auth** for user signup and authentication
* Your app has a **Stripe** subscription or payment flow (for purchase tracking)
* You have a **Cello account** with your **Product ID**, **Product Secret**, and **API access keys** from the [Access Keys page](https://portal.cello.so/integrations/accesskeys)

<Note>
  Use the Cello **Sandbox environment** when developing and testing your integration.
</Note>

## Optional: Connect the Cello MCP

Connect the [Cello MCP server](/mcp/introduction) to your AI coding tool - it gives your tool access to Cello's docs, health checks, and best practices so your AI can handle the implementation.

<Card title="Cello MCP Server" icon="plug" href="/mcp/connect">
  Setup instructions for Cursor, VS Code, and Lovable
</Card>

# Step 1: Capture referral codes on your landing page

Add the [Cello attribution script](/sdk/client-side/attribution-js-introduction) to your referral landing page to capture the referral code (`ucc`) when users click referral links:

1. Install the attribution script. Choose the option best suited for your setup:

   <CardGroup>
     <Card title="Embedded Script Tag" icon="code" href="/sdk/client-side/embedded-script-tag" />

     <Card title="Google Tag Manager" icon="google" href="/sdk/client-side/google-tag-manager" />
   </CardGroup>
2. Verify the installation

   <Check>
     To verify, follow these steps:

     1. Add `?productId=test` and `?ucc=test` to your website URL

        ```html theme={null}
         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 theme={null}
        window.CelloAttribution('getUcc')
        ```

        This method should return a promise with value `test`

        ```javascript theme={null}
        Promise {<fulfilled>: 'test'}
        ```

     **If this check passes, the script is installed correctly.**
   </Check>

# Step 2: Track signups with Supabase Auth + Edge Functions

This is the Supabase-specific step. You will pass the referral code through Supabase Auth, then use a Database Webhook and Edge Function to send the signup event to Cello.

## 2a. Pass the referral code through Supabase Auth signup

During signup, retrieve the `ucc` and store it in the user's `raw_user_meta_data`:

```js theme={null}
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)

const ucc = await window.CelloAttribution('getUcc')

const { data, error } = await supabase.auth.signUp({
  email: 'user@example.com',
  password: 'password',
  options: {
    data: {
      ucc: ucc ?? null,
    },
  },
})
```

## 2b. Deploy an Edge Function to send signup events to Cello

Create an Edge Function that receives the Database Webhook payload and sends a `new-signup` event to the Cello [`POST /events`](/api-reference/generic-events/send-event) API.

All Cello referral events use `eventName: 'ReferralUpdated'` - the `trigger` field inside `context.event` specifies the event type (`new-signup`, `invoice-paid`, etc.).

```bash theme={null}
supabase functions new cello-track-signup
```

<Accordion title="supabase/functions/cello-track-signup/index.ts">
  ```typescript theme={null}
  import { serve } from 'https://deno.land/std@0.177.0/http/server.ts'

  async function getCelloAccessToken(): Promise<string> {
    const response = await fetch('https://api.cello.so/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        accessKeyId: Deno.env.get('CELLO_ACCESS_KEY_ID'),
        secretAccessKey: Deno.env.get('CELLO_SECRET_ACCESS_KEY'),
      }),
    })

    if (!response.ok) {
      throw new Error(`Failed to get Cello token: ${await response.text()}`)
    }

    const { accessToken } = await response.json()
    return accessToken
  }

  serve(async (req: Request) => {
    const payload = await req.json()
    const record = payload.record

    const ucc = record.raw_user_meta_data?.ucc
    const userId = record.id
    const email = record.email

    if (!ucc) {
      return new Response('No referral code - skipping', { status: 200 })
    }

    const accessToken = await getCelloAccessToken()

    const response = await fetch('https://api.cello.so/events', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        eventName: 'ReferralUpdated',
        payload: {
          ucc,
          newUserId: userId,
        },
        context: {
          newUser: {
            id: userId,
            email,
          },
          event: {
            trigger: 'new-signup',
            timestamp: new Date().toISOString(),
          },
        },
      }),
    })

    if (!response.ok) {
      console.error('Cello signup tracking failed:', await response.text())
      return new Response('Error', { status: 500 })
    }

    return new Response('OK', { status: 200 })
  })
  ```
</Accordion>

Set your Cello API access keys. You can find these in your [Cello Portal](https://portal.cello.so/integrations/accesskeys):

```bash theme={null}
supabase secrets set CELLO_ACCESS_KEY_ID=your_access_key_id
supabase secrets set CELLO_SECRET_ACCESS_KEY=your_secret_access_key
```

Deploy the function:

```bash theme={null}
supabase functions deploy cello-track-signup --no-verify-jwt
```

<Note>
  The `--no-verify-jwt` flag is required because the function is called by a Database Webhook, not by an authenticated user.
</Note>

## 2c. Create a Database Webhook on auth.users

In your [Supabase Dashboard](https://supabase.com/dashboard), go to **Database → Webhooks** and create a new webhook:

| Setting       | Value                   |
| ------------- | ----------------------- |
| Name          | `cello-track-signup`    |
| Table         | `auth.users`            |
| Events        | `INSERT`                |
| Type          | Supabase Edge Functions |
| Edge Function | `cello-track-signup`    |

Click **Create webhook**.

<Check>
  Every time a new user signs up via Supabase Auth, the Edge Function fires automatically and sends the referral attribution to Cello.
</Check>

# Step 3: Connect Stripe Webhook for purchase tracking

To send Cello purchase events, connect your Stripe Webhook to Cello. When creating a Stripe Customer, pass the referral metadata so Cello can attribute conversions:

```js theme={null}
const customer = await stripe.customers.create({
  email: 'user@example.com',
  metadata: {
    cello_ucc: ucc,                       // referral code stored during signup
    new_user_id: supabaseUserId,           // must match the productUserId used to boot the widget
    new_user_organization_id: orgId,       // optional - for organization-level referrals
  },
})
```

<Check>
  Cello uses the `customer.created` event to link the Stripe customer to the referral attribution captured in Step 2. Subsequent `invoice.paid` events trigger purchase tracking and reward calculation.
</Check>

Follow this guide to connect the webhook:

<CardGroup>
  <Card title="Stripe Webhook" icon="credit-card" href="/integrations/webhooks/stripe-webhook">
    Send events using Stripe Webhook
  </Card>
</CardGroup>

# Step 4: Integrate the Referral Component

Integrate the Cello Referral Component into your web app so your users can share their referral link. The component is installed using Cello JS - our client-side SDK. You can install it by:

1. Adding a script tag to the `<head>` of your application
2. Generating a JWT token for user authentication
3. Booting the component with the provided token and user details

Follow this installation guide:

<CardGroup>
  <Card title="Referral Component Quickstart" icon="js" href="/referral-component/quickstart" />
</CardGroup>

<Warning>
  Cello requires a **server-side JWT token** signed with your `PRODUCT_SECRET` - this is **not** the Supabase session token (`session.access_token`). You must generate a separate token on your backend. See [User Authentication](/sdk/client-side/user-authentication) for details.
</Warning>

## Verify your integration

Use the [Event Feed](https://portal.cello.so/integrations/events-feed) in the Cello Portal to confirm that signup and purchase events are arriving correctly and all required fields pass validation.

See the [Event Feed guide](/guides/support/portal/event-feed) for details on what to check.

## Next steps

<CardGroup>
  <Card title="Referral Component" icon="puzzle-piece" href="/referral-component/introduction">
    Customise how the referral widget looks and behaves in your app
  </Card>

  <Card title="Track Purchases" icon="credit-card" href="/attribution/tracking-purchase">
    Set up purchase conversion tracking via Stripe webhooks
  </Card>

  <Card title="Apply Discounts" icon="tag" href="/attribution/apply-discounts">
    Offer new user discounts as part of your referral program
  </Card>

  <Card title="Cello MCP Server" icon="plug" href="/mcp/introduction">
    Connect Cursor or Lovable to Cello for AI-assisted integration
  </Card>
</CardGroup>


# 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

<Warning>
  If the automation of Cello detects unclear cases the automation will be paused and Cello will reach out to you to clarify the case.
</Warning>

<Tip>
  After setting up the webhook, check [Integration Status](/guides/support/portal/integration-status) in the Cello Portal to confirm Cello is receiving events from Chargebee. If a component shows a warning or error, open the [Event Feed](https://portal.cello.so/integrations/events-feed) to drill into individual events and see which fields are failing validation.
</Tip>

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

<Note>
  **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
</Note>

### Required Chargebee Customer attribution fields

<Note>
  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)
</Note>

Pass the following fields during checkout in the [Customer Object](https://apidocs.chargebee.com/docs/api/customers) to `meta_data` 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 `meta_data` 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 `meta_data` 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 `meta_data` attribute or as a `cf_` custom field |
| `coupon`                   | New user discount code. Learn how to apply discounts in this [guide](/attribution/apply-discounts).                                       | [Customer Object](https://apidocs.chargebee.com/docs/api/customers) to `meta_data` 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.

<img alt="Chargebee webhook configuration in Cello Portal" />

<Steps>
  <Step title="Log into your Chargebee Dashboard" />

  <Step title="Add a new Webhook">
    From the sidebar, select Settings > Configure Chargebee and click on "Webhooks". Next Click on "+ Add Webhook".
  </Step>

  <Step title="Enter the Endpoint URL">
    Choose the Endpoint URL corresponding to the environment you are setting up: **Sandbox** or **Production**.
  </Step>

  <Step title="Select the events to send">
    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`
  </Step>

  <Step title="Secure the webhook">
    Select "Protect webhook URL with basic authentication" and add the `product_id` and `secret` provided in the Cello Portal.

    <Warning>
      Be sure to select **Exclude card Information from webhook call**
    </Warning>
  </Step>

  <Step title="Click &#x22;Create&#x22; to enable the webhook">
    <Icon icon="check" />  Webhook created!
  </Step>
</Steps>


# 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

<Warning>
  If the automation of Cello detects unclear cases the automation will be paused and Cello will reach out to you to clarify the case.
</Warning>

<Tip>
  After setting up the webhook, check [Integration Status](/guides/support/portal/integration-status) in the Cello Portal to confirm Cello is receiving events from Stripe. If a component shows a warning or error, open the [Event Feed](https://portal.cello.so/integrations/events-feed) to drill into individual events and see which fields are failing validation.
</Tip>

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

<Note>
  **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
</Note>

### 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. Learn how to apply discounts in this [guide](/attribution/apply-discounts).                                       | 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.

<Steps>
  <Step title="Log into your Stripe Dashboard" />

  <Step title="Go to Developer Mode">
    Select Developers from the upper right menu.

    <img alt="Stripe webhook endpoint configuration in Stripe Dashboard" />
  </Step>

  <Step title="Add a Webhook endpoint">
    You can find Webhooks at the left menu. Next click Add an endpoint. <img alt="Adding Cello webhook endpoint URL in Stripe Dashboard" />
  </Step>

  <Step title="Enter the Endpoint URL">
    Choose the Endpoint URL corresponding to the environment you are setting up: **Sandbox** or **Production**. <img alt="Stripe webhook event selection for customer.created events" />
  </Step>

  <Step title="Select the events to send">
    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`

       <img alt="Stripe webhook signing secret for authentication" />
  </Step>

  <Step title="Click &#x22;Add endpoint&#x22;">
    <Icon icon="check" />  Webhook created!
  </Step>

  <Step title="Secure the Webhook">
    To secure the connection, you need to add the “Signing secret” to [Stripe Webhook Configuration in Cello Portal](https://portal.cello.so/integrations/webhooks).

    <Note>
      Stripe Webhook Signing secret starts with `whsec_`
    </Note>

    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). <img alt="Cello Portal webhook configuration for Stripe integration" />
  </Step>
</Steps>


# Introduction
Source: https://docs.cello.so/introduction

Learn how to turn your users into your most valuable growth channel

<iframe title="Loom video player" />

[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:

<CardGroup>
  <Card title="Setup Overview" icon="rocket" href="/integration-overview">
    Follow 4 easy steps to get your referral program up and running with Cello
  </Card>

  <Card title="Cello SDKs" icon="display-code" href="/sdk/introduction">
    Referral component for your web and mobile applications
  </Card>

  <Card title="Referral Conversion" icon="chart-line" href="/attribution/introduction">
    Track signups and purchases back to the right referrer
  </Card>

  <Card title="Integration" icon="webhook" href="/integrations/introduction">
    Webhooks for payment gateways to send conversion events to Cello
  </Card>
</CardGroup>


# 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-js-introduction) 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.

<Warning>
  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.
</Warning>

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

<Note>
  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.
</Note>

## 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

<Note>
  Custom method only works if your account has been configured to use custom cookie handling. Contact Cello Support to enable it.
</Note>

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 theme={null}
window.CelloAttribution('allowCookies');
```

### deleteCookies

To halt the storage of the referral code cookie and clear it:

```javascript theme={null}
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 <span>New</span>
* CookieFirst <span>Coming Soon</span>
* CookieBot <span>Coming Soon</span>
* Civic Cookie Control <span>Coming Soon</span>

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.


# Introduction
Source: https://docs.cello.so/llm-quickstart

Let your AI code assistant learn from Cello documentation and automate your integration steps

Build with Cello faster using AI assistants that understand our entire documentation. This guide shows you how to give AI tools like **Cursor**, **Claude Code**, **Copilot**, etc complete context about Cello's APIs, SDKs, and integration patterns.

## See it in action: Cursor + Cello

Watch a walkthrough of adding user referrals to your app with Cursor - from referral widget and attribution to signup tracking and Stripe conversion.

<Accordion title="Watch the walkthrough">
  <iframe title="Cello + Cursor integration walkthrough" />
</Accordion>

For the full prompt, steps, and acceptance criteria, see the [Cursor integration guide](/coding-apps/cursor-integration).

## Recommended: Use a tool-specific guide

Start with the detailed guide for your tool:

<CardGroup>
  <Card title="Claude Code" icon={<img src="/coding-apps/logo_claude.svg" alt="Claude logo" width={32} height={32} />} href="/coding-apps/claude-integration" />

  <Card title="Cursor" icon={<img src="/coding-apps/logo_cursor.svg" alt="Cursor logo" width={32} height={32} />} href="/coding-apps/cursor-integration" />

  <Card title="Lovable" icon={<img src="/coding-apps/logo_lovable.svg" alt="Lovable logo" width={32} height={32} />} href="/coding-apps/lovable-integration" />

  <Card title="Replit" icon={<img src="/coding-apps/replit-color.svg" alt="Replit logo" width={32} height={32} />} href="/coding-apps/replit-integration" />
</CardGroup>

These guides are best when you want an end-to-end integration:

* Implement **referral widget** + **public attribution** + **signup tracking** + **Stripe conversion tracking**
* Follow **acceptance criteria** and known gotchas (JWT claims, script URLs, event payload shape, Stripe metadata)

After implementation, validate with the [Integration QA Checklist](/resources/integration-qa-checklist).

## Choose how to give your AI Cello context

### Option A (recommended): Cello MCP Server

Connect the **[Cello MCP Server](/mcp/introduction)** to your coding tool for the best experience. It gives your tool access to Cello's documentation, integration health checks, best-practice recommendations, and event inspection - no need to paste anything into every chat.

See [Connect your client](/mcp/connect) for setup instructions for Cursor, Lovable, VS Code, Claude Code, and other MCP clients.

### Option B: URL context

Provide this URL directly to your AI tool:

```
https://docs.cello.so/llms-full.txt
```

<Note>
  This file contains \~73,000 tokens of comprehensive Cello documentation optimized for LLM consumption.
</Note>

Copy/paste starter message:

```
Use the Cello documentation from this URL as the source of truth: https://docs.cello.so/llms-full.txt
Follow the docs exactly and avoid guessing common patterns.
If something is ambiguous, ask clarifying questions before coding.
```

### Option C: 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

<Warning>
  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).
</Warning>

## 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                             |
| MCP not being used   | Verify MCP is enabled in the tool, confirm the server is added, and restart the tool if needed |
| 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).


# Connect your client
Source: https://docs.cello.so/mcp/connect

Set up the Cello MCP server in Claude, Claude Code, Cursor, VS Code, Windsurf, Lovable, and other MCP clients

The Cello MCP server uses **OAuth**. When you connect, your client opens a browser window to sign in to Cello and authorize access. There's no token to generate or paste, and your client refreshes the connection automatically.

```
https://mcp.cello.so/mcp
```

<Info>
  Make sure MCP is **enabled for your account** and grab your **MCP Server URL** first. The examples above use the Production URL; swap in your Sandbox URL (`https://mcp.sandbox.cello.so/mcp`) if connecting a test account.

  <img alt="Cello Portal MCP Server page showing the Enable MCP toggle, the MCP Server URL field, and quick-add cards for Cursor, Claude, VS Code, Lovable, Replit, and Other AI tools" />
</Info>

## Claude

Connect Cello to the **Claude desktop or web app** as a custom connector. (For the Claude Code CLI, see [Claude Code](#claude-code) below.)

1. Go to **Settings → Connectors**
2. Click **Add custom connector**
3. Enter the following:
   * **Name**: `Cello`
   * **Remote MCP server URL**: `https://mcp.cello.so/mcp`
4. Click **Add**, then **Connect**.

<video />

<Frame>
  <img alt="Claude Settings → Connectors showing Cello as a custom connector with a Connect button" />
</Frame>

A browser window opens to authorize access to your Cello account.

<Frame>
  <img alt="OAuth authorization dialog asking to allow Claude to access Cello" />
</Frame>

Once connected, the Cello tools appear in the chat and Claude uses them automatically.

<Info>
  On Team, Enterprise, and Edu plans, an admin may need to add Cello as an organization connector first via **Settings → Connectors → Organization plugins** before members can connect.
</Info>

## Claude Code

<Steps>
  <Step title="Add the server">
    Run the following in your terminal:

    ```bash theme={null}
    claude mcp add --transport http Cello https://mcp.cello.so/mcp
    ```

    Swap in the Sandbox URL (`https://mcp.sandbox.cello.so/mcp`) if you're connecting a test account.
  </Step>

  <Step title="Authenticate with Cello">
    Run `/mcp` inside Claude Code, select **Cello**, and choose **Authenticate**. A browser window opens for you to sign in to Cello and authorize access. Claude Code stores and refreshes the connection for you - there's no token to manage.
  </Step>

  <Step title="Verify the connection">
    Run `/mcp` again. **Cello** should show as **connected** with its tools listed. Try a prompt like *"Use Cello to check my integration status."*
  </Step>
</Steps>

## Cursor

The quickest way is to click **Cursor** directly from the MCP Server page in the Cello Portal — it adds the server to Cursor automatically.

Or add it manually: go to **Cursor Settings → Tools & Integrations → MCP Servers → Add Server** and enter the server URL. When Cursor connects, it opens a browser window to sign in to Cello and authorize access.

<Frame>
  <img alt="Cello Portal MCP Server page with the Cursor quick-add card highlighted" />
</Frame>

<Frame>
  <img alt="Cursor Install MCP Server dialog showing Name as Cello MCP, Type as streamableHttp, and the Cello server URL" />
</Frame>

Or configure manually by editing `~/.cursor/config/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\config\mcp.json` (Windows):

```json theme={null}
{
  "mcpServers": {
    "Cello": {
      "url": "https://mcp.cello.so/mcp"
    }
  }
}
```

After adding the server, Cursor prompts you to sign in. Once authorized, you should see the Cello MCP server listed with the Cello tools enabled.

<Frame>
  <img alt="Cursor Tools & MCP settings showing the Cello MCP connected with its tools enabled" />
</Frame>

## VS Code (Copilot)

Create or edit `.vscode/mcp.json` in your workspace (or use **MCP: Add Server** from the Command Palette):

```json theme={null}
{
  "servers": {
    "Cello": {
      "type": "http",
      "url": "https://mcp.cello.so/mcp"
    }
  }
}
```

When VS Code connects, it opens a browser window to sign in to Cello and authorize access.

## Windsurf

1. Go to **Settings → MCP**
2. Click **Add Server**
3. Enter the server URL: `https://mcp.cello.so/mcp`
4. Windsurf opens a browser window to sign in to Cello and authorize access.

## Lovable

Add the Cello MCP as a custom personal connector in Lovable:

1. In Lovable, go to **Settings → Connectors → Personal connectors**
2. Click **New MCP server**
3. Enter the following:
   * **Server name**: `Cello`
   * **Server URL**: `https://mcp.cello.so/mcp`
   * **Authentication**: Select **OAuth**
4. Click **Add & authorize**. A browser window opens for you to sign in to Cello and authorize access.

The Cello connector appears in your list of personal connectors.

<Frame>
  <img alt="Lovable Settings showing Cello as an enabled MCP personal connector" />
</Frame>

For a complete walkthrough of using the Cello MCP with Lovable to build a referral integration, see the [Cello + Lovable integration](/coding-apps/lovable-integration) guide. For more details on custom MCP servers in Lovable, see the [Lovable MCP documentation](https://docs.lovable.dev/integrations/mcp-servers).

## Other MCP clients

Any tool that supports MCP can connect to the Cello MCP server. Add the following to your client's MCP configuration:

* **Server URL**: `https://mcp.cello.so/mcp`
* **Authentication**: OAuth - sign in to Cello in the browser window your client opens

After adding the server, complete the browser sign-in to authorize access, then restart your application if your client requires it.

## Troubleshooting

| Issue                                               | Solution                                                                                                                                                                                |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connection fails                                    | Re-run the authorization flow from your client to sign in to Cello again. Make sure you're signing in to the account that matches the server URL's environment (Production vs Sandbox). |
| Tools return authentication errors                  | Disconnect and reconnect the server to refresh authorization. Check that MCP is enabled for your account in the portal (**Integrations → MCP**).                                        |
| You don't see the tools you expect                  | The available tools depend on your Cello role. If you expect developer or growth tools and don't see them, contact your Customer Success Manager.                                       |
| `cello_get_integration_status` shows `notConnected` | Follow the relevant integration guide for the disconnected component. Use `search_cello` to find the setup docs.                                                                        |
| Events show validation warnings                     | Use `cello_get_events` to inspect the payload and identify missing or malformed fields (ucc, productUserId, customerId).                                                                |
| Data or recommendations look out of date            | Most data is live; config-based recommendations reflect the current setup, while CRM-derived recommendations may have a slight delay.                                                   |

## Need help?

If you get stuck, reach out to your Customer Success Manager or contact support at [support@cello.so](mailto:support@cello.so).


# Prompts
Source: https://docs.cello.so/mcp/developers/prompts

Example prompts for building and debugging your Cello integration

Once connected, prompt your coding tool naturally. It picks the right Cello tool automatically.

## Setting up

| Prompt                                                                                                                     | What happens                                                           |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| *"I want to add user referrals to my app using Cello. Search the Cello docs for the integration guide and create a plan."* | Finds the right guide for your stack and builds an implementation plan |
| *"How do I set up Cello attribution on my landing page?"*                                                                  | Looks up the attribution setup docs and walks you through it           |
| *"What Stripe webhook events does Cello need?"*                                                                            | Searches the docs for the Stripe webhook configuration                 |

## Verifying your integration

| Prompt                                                                                 | What happens                                                              |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| *"Is my Cello integration working?"*                                                   | Checks all four components and reports which are connected or broken      |
| *"I just finished the Cello integration. Verify that everything is set up correctly."* | Runs a health check and flags any components that aren't receiving events |

## Debugging

| Prompt                                                          | What happens                                                                               |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| *"Why aren't my Cello referral rewards being triggered?"*       | Checks integration health, then inspects recent events to find missing or malformed fields |
| *"Are my Stripe webhook events being received by Cello?"*       | Shows the latest events feed with validation status for each field                         |
| *"Signups aren't being attributed to referrers. What's wrong?"* | Inspects recent signup events and checks whether the ucc field is present                  |

## Optimizing

| Prompt                                           | What happens                                                                             |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| *"How can I improve my Cello referral program?"* | Returns a prioritized list of recommendations across activation, sharing, and conversion |
| *"What referral best practices am I missing?"*   | Shows which recommendations are done and which still need action                         |


# Tools
Source: https://docs.cello.so/mcp/developers/tools

The Cello MCP tools available to developers

These are the tools your AI assistant uses when you connect from a coding tool. All Cello MCP tools are currently read-only.

| Tool                           | What it does                                                             |
| ------------------------------ | ------------------------------------------------------------------------ |
| `search_cello`                 | Search the Cello knowledge base for guides, API references, and examples |
| `cello_get_integration_status` | Check whether all four integration components are connected              |
| `cello_get_events`             | Inspect the latest events Cello received, with per-field validation      |
| `cello_get_recommendations`    | Surface prioritized best-practice recommendations                        |
| `query_docs_filesystem_cello`  | Read full documentation pages and OpenAPI specs on demand                |

See the complete [All tools](/mcp/tools) reference for full specs and the tools available to other roles.


# Use cases
Source: https://docs.cello.so/mcp/developers/use-cases

How to use the Cello MCP to set up, verify, and debug your Cello integration from any AI coding tool.

Start with the end-to-end integration guide for your tool, then use the MCP to verify and debug as you build.

<CardGroup>
  <Card title="Claude Code" icon={<img src="/coding-apps/logo_claude.svg" alt="Claude logo" width={32} height={32} />} href="/coding-apps/claude-integration" />

  <Card title="Cursor" icon={<img src="/coding-apps/logo_cursor.svg" alt="Cursor logo" width={32} height={32} />} href="/coding-apps/cursor-integration" />

  <Card title="Lovable" icon={<img src="/coding-apps/logo_lovable.svg" alt="Lovable logo" width={32} height={32} />} href="/coding-apps/lovable-integration" />

  <Card title="Replit" icon={<img src="/coding-apps/replit-color.svg" alt="Replit logo" width={32} height={32} />} href="/coding-apps/replit-integration" />
</CardGroup>

## Set up your integration

Find the right guide for your stack, scaffold the integration, and look up exactly which webhook events and fields Cello needs.

> *"I want to add user referrals to my app using Cello. Search the Cello docs for the integration guide and create a plan."*

## Verify it works

Run a health check across all four integration components (referral widget, attribution widget, signup tracking, and purchase tracking) and confirm Cello is receiving events. See [Integration Status](/guides/support/portal/integration-status) for what each component checks.

> *"Is my Cello integration working?"*

## Debug issues

Trace why rewards aren't triggering or signups aren't being attributed. The assistant inspects recent events and flags missing or malformed fields.

> *"Why aren't my Cello referral rewards being triggered?"*

## Optimize your program

Surface prioritized [best-practice recommendations](/guides/attribution/recommendations) across activation, sharing, and conversion.

> *"How can I improve my Cello referral program?"*

***

See [Prompts](/mcp/developers/prompts) for the full list and [Tools](/mcp/developers/tools) for the underlying capabilities.


# Prompts
Source: https://docs.cello.so/mcp/growth/prompts

Example prompts for understanding and improving your referral program

Once connected, just ask your AI assistant naturally. It picks the right Cello tool automatically.

## Program performance

| Prompt                                                                       | What happens                                                                   |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| *"How is my referral program performing this month?"*                        | Returns current funnel metrics, revenue, and how they've moved vs. last period |
| *"What's my activation and sharing rate, and are they trending up or down?"* | Reports the rates with their monthly and weekly trend direction                |
| *"How much ARR has my referral program generated?"*                          | Surfaces lifetime new-user revenue and recent changes                          |

## Industry benchmarks

| Prompt                                                                      | What happens                                                                                                           |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| *"How do my referral metrics compare to industry benchmarks?"*              | Compares your latest rates against the median and best-in-class for your GTM motion                                    |
| *"Am I above or below median for sharing rate?"*                            | Returns your sharing rate vs. the median for your peer group, using the banded benchmark adjusted for your active rate |
| *"How do I rank against best-in-class companies with the same GTM motion?"* | Shows your rates vs. the 75th percentile for Free Trial, Freemium, or Demo Only companies                              |
| *"Which of my metrics are below median?"*                                   | Surfaces the specific metrics where you're underperforming peers so you know where to focus                            |

## Referrers and top performers

| Prompt                                                  | What happens                                                                |
| ------------------------------------------------------- | --------------------------------------------------------------------------- |
| *"Who are my top referrers by revenue?"*                | Lists the highest-performing referrers, sorted by net new ARR               |
| *"Show me referrers sorted by signups they've driven."* | Returns referrers ranked by the metric you ask for, as a table              |
| *"Find the referrer with ucc ABC123."*                  | Looks up a specific referrer by ucc, email, product user id, or referrer id |
| *"Which referrers have been most active recently?"*     | Sorts referrers by engagement metrics                                       |

## Recommendations and optimization

| Prompt                                              | What happens                                                                   |
| --------------------------------------------------- | ------------------------------------------------------------------------------ |
| *"How can I improve my referral program?"*          | Returns prioritized recommendations across activation, sharing, and conversion |
| *"What's the highest-impact change I should make?"* | Surfaces the top-priority recommendation with its effort/impact label          |
| *"What best practices am I still missing?"*         | Shows which recommendations are done and which still need action               |

## Documentation and how-to

| Prompt                                                         | What happens                                             |
| -------------------------------------------------------------- | -------------------------------------------------------- |
| *"How do rewards get paid out in Cello?"*                      | Searches the Cello knowledge base and answers with links |
| *"What's the difference between activation and sharing rate?"* | Explains the metric using Cello documentation            |


# Tools
Source: https://docs.cello.so/mcp/growth/tools

The Cello MCP tools available to growth managers

These are the tools your AI assistant uses when you connect as a growth manager. All Cello MCP tools are currently read-only. To take action, the assistant points you to the relevant page in the [Cello Portal](https://portal.cello.so).

| Tool                        | What it does                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `cello_get_program_metrics` | Lifetime totals, weekly/monthly trends, and industry benchmarks for your program     |
| `cello_get_referrers`       | Find referrers, filtered and sorted by engagement or performance                     |
| `cello_get_top_referrers`   | Your highest-performing referrers by net new ARR                                     |
| `cello_get_recommendations` | Prioritized best-practice recommendations across activation, sharing, and conversion |
| `search_cello`              | Search the Cello knowledge base for how-to answers                                   |

See the complete [All tools](/mcp/tools) reference for full specs and the tools available to other roles.


# Use cases
Source: https://docs.cello.so/mcp/growth/use-cases

How to use the Cello MCP to track performance, benchmark against peers, and get program recommendations from your AI client.

<Info>
  Prefer not to set anything up? The same capabilities are available in the [AI Assistant](/guides/ai-assistant/overview) built directly into the Cello portal - no connection required. Use the MCP server when you'd rather work from your own AI client.
</Info>

## Track program performance

Get lifetime totals, weekly and monthly trends, and see how your funnel metrics and revenue have moved. See [Program Performance](/guides/attribution/program-performance) for how these metrics are calculated.

> *"How is my referral program performing this month?"*

## Compare against benchmarks

See how your key metrics stack up against the median and best-in-class for your GTM motion. Learn [how benchmarks work](/guides/attribution/benchmarks).

> *"How do my metrics compare to benchmarks?"*

## Find your top referrers

Surface your highest-performing referrers, or look up and rank referrers by engagement, signups, or revenue.

> *"Who are my top referrers by revenue?"*

## Get recommendations

See a prioritized list of what to improve next across activation, sharing, and conversion, with effort and impact labels. Learn how the [recommendations score](/guides/attribution/recommendations) works.

> *"What's the highest-impact change I should make?"*

## Look up how-to answers

Ask questions about how Cello works and get answers grounded in the documentation.

> *"How do rewards get paid out in Cello?"*

<Note>
  These tools are currently read-only. To take action, the assistant points you to the relevant page in the [Cello Portal](https://portal.cello.so).
</Note>

***

See [Prompts](/mcp/growth/prompts) for the full list and [Tools](/mcp/growth/tools) for the underlying capabilities.


# Cello MCP
Source: https://docs.cello.so/mcp/introduction

Connect Cello to your AI tools through the Model Context Protocol (MCP)

## Overview

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets AI tools securely connect to external data and tools. The Cello MCP server brings your referral program into AI clients like **Claude**, **Cursor**, **VS Code**, and **Lovable**. Developers can build and verify integrations without leaving their editor; growth managers can query program performance in natural language grounded in live Cello data.

It's a **single server** with tools covering both developer and growth use cases:

<CardGroup>
  <Card title="For developers" icon="code" href="/mcp/developers/use-cases">
    Search docs, verify integration health, inspect events, and surface best-practice recommendations while you build.
  </Card>

  <Card title="For growth managers" icon="chart-line" href="/mcp/growth/use-cases">
    Ask about program performance, find top referrers, review flagged referrals, and get recommendations.
  </Card>
</CardGroup>

## Enable MCP

An admin needs to turn on the MCP server for your account in the [Cello Portal](https://portal.cello.so) under **Integrations → MCP**. Once enabled, copy your **MCP Server URL** from that page — you'll need it to connect your client.

<Frame>
  <img alt="Cello Portal MCP Server page showing the Enable MCP toggle, the MCP Server URL field, and quick-add cards for Cursor, Claude, VS Code, Lovable, Replit, and Other AI tools" />
</Frame>

## Environments

The Cello MCP server has a **separate URL for each environment**. Use the URL that matches the environment of the Cello account you sign in to:

* **Production**: `https://mcp.cello.so/mcp`
* **Sandbox**: `https://mcp.sandbox.cello.so/mcp`

Examples throughout these docs use the Production URL. Swap in the Sandbox URL if you're connecting to a Sandbox tenant.

## How authentication works

The Cello MCP server uses **OAuth**. When you connect, your client opens a browser window where you sign in to Cello and authorize access. There's no token to generate, copy, or paste. Your client manages the connection and refreshes it automatically.

## Next steps

<CardGroup>
  <Card title="Connect your client" icon="plug" href="/mcp/connect">
    Step-by-step setup for Claude, Claude Code, Cursor, VS Code, Lovable, and more.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/connect#troubleshooting">
    Fix connection and authentication issues.
  </Card>
</CardGroup>


# All tools
Source: https://docs.cello.so/mcp/tools

The complete list of tools the Cello MCP server exposes

The Cello MCP server exposes the tools below. Which ones are available depends on your Cello role. See the [Developers](/mcp/developers/use-cases) and [Growth Managers](/mcp/growth/use-cases) sections for use cases and example prompts.

<Note>
  All Cello MCP tools are currently read-only. To make changes, the assistant points you to the relevant page in the [Cello Portal](https://portal.cello.so).
</Note>

## Overview

| Tool                                                            | Purpose                                              | Typically used by |
| --------------------------------------------------------------- | ---------------------------------------------------- | ----------------- |
| [`cello_get_program_metrics`](#cello_get_program_metrics)       | Program metrics, trends, and benchmarks in one call  | Growth            |
| [`cello_get_referrers`](#cello_get_referrers)                   | Find and sort referrers by engagement or performance | Growth            |
| [`cello_get_top_referrers`](#cello_get_top_referrers)           | Top referrers by net new ARR                         | Growth            |
| [`cello_get_integration_status`](#cello_get_integration_status) | Health of the four integration components            | Developer         |
| [`cello_get_events`](#cello_get_events)                         | Latest events feed with per-field validation         | Developer         |
| [`cello_get_recommendations`](#cello_get_recommendations)       | Prioritized best-practice recommendations            | Both              |
| [`search_cello`](#search_cello)                                 | Search the Cello knowledge base                      | Both              |
| [`query_docs_filesystem_cello`](#query_docs_filesystem_cello)   | Read full doc pages and OpenAPI specs                | Both              |

## Program & analytics

### cello\_get\_program\_metrics

Complete referral program metrics in a single call.

* **Returns**: lifetime cumulative totals (referrer funnel and new-user funnel, plus ARR) with pre-calculated monthly and weekly trends; weekly and monthly history time series; and industry benchmarks segmented by GTM motion (Free Trial, Freemium, Demo Only, or Overall). Benchmarks cover Active Rate, Sharing Rate, Signup Rate, and Unique Views per Share, each with a median (50th pct) and best-in-class (75th pct) line. Sharing rate uses a banded benchmark adjusted for your active rate so you're compared against true peers.
* **Use for**: questions about program performance, stats, trends, revenue, funnel metrics, or industry comparisons.

See also: [Program Performance](/guides/attribution/program-performance), [Benchmarks](/guides/attribution/benchmarks)

### cello\_get\_referrers

Find referrers, optionally filtered and sorted by engagement or performance metrics.

* **Parameters**: `filter` (matches ucc, email, product user id, or referrer id), `page` (1-indexed, 10 per page), `sort` (defaults to net new ARR; also revenue, signups, purchases, unique views, and recent activity).
* **Returns**: up to 10 referrers per page with their metrics, plus the total match count. Best presented as a table.

### cello\_get\_top\_referrers

The top-performing referrers, sorted by net new ARR (descending).

* **Parameters**: `page` (1-indexed, 10 per page).
* **Returns**: up to 10 referrers per page with their metrics, plus the total count.

## Integration health

### cello\_get\_integration\_status

Checks whether all four integration components are working: the referral widget, the attribution widget, signup tracking, and purchase tracking.

* **Returns**: per-component `connectionStatus` (`connected`, `connectedWithWarnings`, or `notConnected`), an optional `warningType`, and a `lastEventReceived` timestamp. Includes signup source, purchase source, and any widget errors.

See also: [Integration Status](/guides/support/portal/integration-status)

### cello\_get\_events

Recent webhook and API events Cello received from your payment provider or direct API integration.

* **Returns**: recent events (newest first) with source, overall validation status, timestamp, and a payload breakdown of key fields (ucc, productUserId, email, customerId), each with its own validation status.
* **Use for**: verifying events are received and diagnosing missing or malformed fields that block attribution.

See also: [Event Feed](/guides/support/portal/event-feed)

## Optimization & documentation

### cello\_get\_recommendations

A prioritized list of best-practice recommendations for improving your referral program, grouped by activation, sharing, and conversion.

* **Returns**: recommendations with completed/pending status, effort and impact labels, actionable links, and a top-priority callout.

See also: [Performance Recommendations](/guides/attribution/recommendations)

### search\_cello

Search the Cello knowledge base for documentation, code examples, API references, and guides.

* **Returns**: contextual content with titles and direct links to the relevant documentation pages.

### query\_docs\_filesystem\_cello

A read-only query interface over an in-memory filesystem containing the Cello documentation pages and OpenAPI specs.

* **Use for**: reading the full content of a specific doc page by path, exact keyword or regex search, and exploring the docs structure. Complements `search_cello`, which is better for broad or conceptual queries.


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

<img alt="Custom launcher integration showing referral component embedded in application menu" />

<Warning>
  **Critical Requirements for Custom Launchers:**

  * The custom launcher element **MUST exist in the DOM before Cello initializes**
  * The element **MUST have `position: relative` styling**
  * You **MUST configure the selector in Cello Portal** to match your element
  * Cello does **NOT automatically rescan the DOM** for new elements after initialization
</Warning>

## Implementation Guide

### Step 1: Create your launcher element

Create an HTML element that will trigger the Referral Component. The element must:

1. Exist in the DOM **before** `cello.boot()` is called
2. Have `position: relative` CSS styling
3. Use a unique identifier (ID, class, or attribute)

<Tabs>
  <Tab title="React">
    ```jsx theme={null}
    // ❌ WRONG: Element created after Cello initialization
    function MyComponent() {
      const [celloReady, setCelloReady] = useState(false);
      
      useEffect(() => {
        initializeCello(); // Initializes Cello
        setCelloReady(true);
      }, []);
      
      return (
        <>
          {celloReady && (
            <button id="cello-launcher">Invite</button> // Too late!
          )}
        </>
      );
    }

    // ✅ CORRECT: Element exists before Cello initialization
    function MyComponent() {
      const [celloReady, setCelloReady] = useState(false);
      
      useEffect(() => {
        // Element already exists in DOM
        initializeCello(); // Now initialize Cello
        setCelloReady(true);
      }, []);
      
      return (
        <>
          <button 
            id="cello-launcher"
            style={{ 
              position: 'relative',
              display: celloReady ? 'block' : 'none' 
            }}
          >
            Invite Friends
          </button>
        </>
      );
    }
    ```
  </Tab>

  <Tab title="HTML">
    ```html theme={null}
    <!-- Element with ID selector -->
    <button id="cello-launcher" style="position: relative;">
      Invite Friends
    </button>

    <!-- Element with class selector -->
    <button class="cello-custom-launcher" style="position: relative;">
      Share & Earn
    </button>

    <!-- Element with attribute selector -->
    <button data-cello-launcher="true" style="position: relative;">
      Refer Now
    </button>
    ```
  </Tab>

  <Tab title="Vue">
    ```vue theme={null}
    <template>
      <!-- Element always rendered, visibility controlled by CSS -->
      <button 
        id="cello-launcher"
        :style="{ 
          position: 'relative',
          display: celloInitialized ? 'block' : 'none' 
        }"
      >
        Invite Friends
      </button>
    </template>

    <script>
    export default {
      data() {
        return {
          celloInitialized: false
        }
      },
      mounted() {
        // Element already exists in DOM
        this.initializeCello().then(() => {
          this.celloInitialized = true;
        });
      }
    }
    </script>
    ```
  </Tab>

  <Tab title="Angular">
    ```typescript theme={null}
    // ❌ WRONG: Element created after Cello initialization
    @Component({
      selector: 'app-my-component',
      template: `
        <button *ngIf="celloReady" id="cello-launcher">
          Invite
        </button> <!-- Too late! -->
      `
    })
    export class MyComponent implements OnInit {
      celloReady = false;
      
      ngOnInit() {
        this.initializeCello();
        this.celloReady = true; // Button appears after Cello init
      }
    }

    // ✅ CORRECT: Element exists before Cello initialization
    @Component({
      selector: 'app-my-component',
      template: `
        <button 
          id="cello-launcher"
          [style.position]="'relative'"
          [style.display]="celloReady ? 'block' : 'none'"
        >
          Invite Friends
        </button>
      `
    })
    export class MyComponent implements OnInit {
      celloReady = false;
      
      async ngOnInit() {
        // Element already exists in DOM (hidden)
        await this.initializeCello();
        this.celloReady = true; // Now show the button
      }
      
      async initializeCello() {
        // Initialize Cello here
        window.cello = window.cello || { cmd: [] };
        
        window.cello.cmd.push(async (cello) => {
          try {
            await cello.boot({
              productId: "YOUR_PRODUCT_ID",
              token: "YOUR_JWT_TOKEN",
              // ... other configuration
            });
            console.log('Cello initialized successfully');
          } catch (error) {
            console.error('Failed to initialize Cello:', error);
          }
        });
      }
    }
    ```
  </Tab>
</Tabs>

### Step 2: Configure Cello Portal

1. Navigate to [Referrer Experience in Cello Portal](https://portal.cello.so/setup/referrer-experience)
2. Set the **Custom Launcher Selector** to match your element:
   * For ID: `#cello-launcher`
   * For class: `.cello-launcher`
   * For attribute: `[cello-launcher]`

<img alt="Cello Portal configuration for custom launcher selector settings" />

### Step 3: Initialize Cello

After the custom launcher element exists in the DOM, initialize Cello:

```javascript theme={null}
window.cello = window.cello || { cmd: [] };

window.cello.cmd.push(async (cello) => {
  try {
    await cello.boot({
      productId: "YOUR_PRODUCT_ID",
      token: "USER_JWT_TOKEN",
      // ... other configuration
    });
    
    console.log("Cello initialized successfully");
    // Custom launcher is now active
  } catch (error) {
    console.error("Failed to initialize Cello:", error);
  }
});
```

## Common Issues and Solutions

### Custom launcher not working

<AccordionGroup>
  <Accordion title="Element doesn't exist when Cello initializes">
    **Problem:** The custom launcher element is created after Cello has already initialized.

    **Solution:** Ensure the element exists in the DOM before calling `cello.boot()`. In React/Vue, render the element with `display: none` initially, then show it after initialization.
  </Accordion>

  <Accordion title="Missing position: relative">
    **Problem:** The element doesn't have `position: relative` styling.

    **Solution:** Add `style="position: relative"` to your launcher element. This is required for Cello to properly attach event handlers.
  </Accordion>

  <Accordion title="Selector mismatch or selector matches multiple elements">
    **Problem:** The selector in Cello Portal doesn't match your element, or matches several elements where only one is visible.

    **Solution:** Verify the exact selector format:

    * ID selectors need `#` prefix: `#my-launcher`
    * Class selectors need `.` prefix: `.my-launcher`
    * Attribute selectors need brackets: `[my-attribute]`

    Also verify uniqueness - Cello uses `document.querySelector` and picks the **first match** in DOM order. Run `document.querySelectorAll("<your selector>")` in the browser console: it should return exactly one visible element with a non-zero bounding box. If multiple elements match (for example, a wrapper `<li>` and an inner `<span>` share the same class), Cello will use the first one, which may be invisible. Either narrow the selector with a parent prefix or use an `id`. See [Troubleshooting: announcement not showing](#troubleshooting-announcement-not-showing) for the same diagnostic flow applied to announcements.
  </Accordion>

  <Accordion title="Dynamic elements in SPAs">
    **Problem:** In single-page applications, elements are dynamically added/removed.

    **Solution:** Keep the launcher element persistent in the DOM, use CSS to control visibility instead of conditional rendering.
  </Accordion>
</AccordionGroup>

## Add reward in launcher

<span>1.5x activation rate</span>

<span>3.5x sharing rate</span>

Increase the sharing activity of your users by highlighting the reward directly in the referral launcher inside your menu item.

<img alt="Custom launcher displaying reward amount directly in 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 theme={null}
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.

<img alt="Default Cello floating action button 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".

<img alt="Configuration to disable default Cello button and use custom launcher" />

## Configure notification badge

<img alt="Notification badge attached to custom launcher showing unread updates" />

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:

<AccordionGroup>
  <Accordion title="Default behavior (clickable with badge)">
    This is the default behavior - the element opens the Referral Component on click and shows notification badges.

    ```html theme={null}
    <!-- Any of these work the same - default behavior -->
    <button id="cello-launcher" style="position: relative;">
      Invite
    </button>

    <button class="my-launcher" style="position: relative;">
      Share & Earn
    </button>
    ```
  </Accordion>

  <Accordion title="Clickable without badge">
    Add `data-cello-badge="false"` to hide the notification badge while keeping the element clickable.
    Use this when you have multiple launchers but only want badges on some of them.

    ```html theme={null}
    <button 
      id="cello-launcher" 
      data-cello-badge="false"
      style="position: relative;"
    >
      Invite (no badge)
    </button>
    ```
  </Accordion>

  <Accordion title="Badge only, non-clickable">
    Add `data-cello-click="false"` to show the notification badge but prevent clicks from opening the panel.
    Use this to show badge notifications on parent menu items for better visibility.

    ```html theme={null}
    <div 
      class="menu-section"
      data-cello-click="false"
      style="position: relative;"
    >
      <!-- Shows badge but doesn't open panel on click -->
      Settings Menu
    </div>
    ```
  </Accordion>
</AccordionGroup>

<Note>
  The `data-cello-badge` and `data-cello-click` attributes are **optional modifiers**. If you want the default behavior (clickable with badge), you don't need these attributes at all.
</Note>

<Check>
  **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.
</Check>

## Add announcement selector

<img alt="Announcement callout anchored to custom launcher element" />

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.

<Note>
  If the Cello button is disabled, the announcement needs to be anchored to one of your Custom Launchers.
</Note>

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

<Warning>
  **Critical requirements for Announcement Selector:**

  * The selector **MUST resolve to exactly one element** when passed to `document.querySelector`. Cello uses the **first match** in DOM order and does not fall back to siblings.
  * The matched element **MUST be visible and have a non-zero bounding box** at announcement time. `display: none`, `visibility: hidden`, or `width: 0 / height: 0` will cause the announcement to render against an invisible anchor.
  * If multiple elements share the same class or attribute (e.g. a wrapper `<li>` and an inner `<span>` both have `.my-launcher`), narrow the selector with a parent prefix or use an `id`.
  * Verify in the browser console: `document.querySelectorAll("<your selector>")` should return exactly one element with non-zero size. See [Troubleshooting: announcement not showing](#troubleshooting-announcement-not-showing).
</Warning>

<img alt="Cello Portal configuration for announcement selector and positioning" />

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

<Check>
  **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 theme={null}
  window.Cello("showAnnouncement", { "type": "welcome-announcement-1" })
  ```

  A fulfilled promise from `showAnnouncement` only means the SDK accepted the request. It does **not** mean the announcement is visible. If you see `Promise {<fulfilled>: undefined}` in the console but no announcement on the page, see [Troubleshooting: announcement not showing](#troubleshooting-announcement-not-showing).
</Check>

## Troubleshooting: announcement not showing

**Short answer:** The most common cause is that your **Announcement Selector** matches more than one element, and the first match in DOM order is invisible (zero-sized, hidden, or off-screen). Cello uses `document.querySelector`, which always picks the first match. Narrow the selector until `document.querySelectorAll(<your selector>)` returns exactly one visible element.

### How announcement positioning works

* Cello calls `document.querySelector(<your Announcement Selector>)` once when an announcement is rendered.
* `document.querySelector` returns the **first matching element in DOM order**, not the most visible one.
* The matched element must be present in the DOM, have non-zero width and height, and not be `display: none` or `visibility: hidden` at the moment the announcement renders.
* A fulfilled `showAnnouncement` promise means the SDK accepted the request. It does **not** mean the announcement is visible to the user.
* Cello does not retry, fall back to siblings, or rescan the DOM if the matched element is invisible.

### Symptom: `showAnnouncement` returns a fulfilled promise but nothing appears

If your browser console shows:

```
> window.Cello("showAnnouncement", { "type": "welcome-announcement-1" })
< Promise {<pending>}
    [[PromiseState]]: "fulfilled"
    [[PromiseResult]]: undefined
```

...this only means the SDK accepted the call. The announcement may still be invisible because of the selector resolving to a hidden or zero-sized element.

### Symptom map

| Symptom                                                                              | What to run in DevTools                                             | What it means                                                                                  | Fix                                                                                                                                                                              |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showAnnouncement` returns fulfilled promise but no announcement appears             | `document.querySelectorAll("<your selector>").length`               | If `> 1`, your selector is too broad. Cello picked the first match, which is likely invisible. | Use a more specific selector (add a parent class, or use an `id`). Update **Announcement Selector** in [Referrer Experience](https://portal.cello.so/setup/referrer-experience). |
| Announcement renders at the top-left of the viewport (0,0)                           | `document.querySelector("<your selector>").getBoundingClientRect()` | If width/height is `0`, the matched element has no layout box.                                 | Move the class/attribute to the visible element (icon/button), not a wrapper `<li>` or `<span>`.                                                                                 |
| Announcement renders but is cut off or off-screen                                    | Same as above; check `top` / `left` values                          | The matched element is off-screen or inside a scrolled container.                              | Anchor to an in-viewport element, or adjust **Announcement position offset** in the Portal.                                                                                      |
| `querySelectorAll` returns `0` matches                                               | n/a                                                                 | Element does not exist when the announcement renders, or the selector has a typo.              | Confirm the element exists before `cello.boot()`; check `#`, `.`, `[]` prefixes match your element.                                                                              |
| `querySelectorAll` returns `1` and the element is visible, but still no announcement | Inspect computed styles                                             | The matched element may be missing `position: relative`.                                       | Add `position: relative` to the matched element.                                                                                                                                 |

### Related questions this section answers

* Why does `showAnnouncement` resolve but no announcement appears?
* Why is my Cello announcement invisible?
* Why does my Cello announcement render at the top-left of the screen?
* How do I fix "announcement selector matches multiple elements"?
* Why does Cello pick the wrong element for my announcement?
* Cello announcement not working / not showing / not appearing


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

<img alt="Cello Referral Component interface showing sharing options and rewards tracking" />

## 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)
* **Dark mode** - Support for light and dark theme to match your app’s interface

## Installation Options

<CardGroup>
  <Card title="Cello JS" icon="js" href="/referral-component/quickstart">
    JavaScript library for React, Vue, Angular, and vanilla JS applications
  </Card>

  <Card title="iOS SDK" icon="apple" href="/sdk/mobile/ios">
    Native Swift/Objective-C SDK with CocoaPods and SPM support
  </Card>

  <Card title="Android SDK" icon="android" href="/sdk/mobile/android">
    Native Kotlin/Java SDK with Gradle integration
  </Card>

  <Card title="React Native" icon="react" href="/sdk/mobile/react-native">
    Cross-platform mobile SDK for React Native apps
  </Card>
</CardGroup>

## 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 theme={null}
// 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

<Tip>
  This guide follows basic steps to **integrate Referral Component into your web application** using [Cello JS SDK](/sdk/client-side/cello-js-introduction).
</Tip>

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

<Note>
  For server-side rendering frameworks like Next.js, Cello interactions must occur client-side, not server-side.
</Note>

## 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)

<img alt="Portal Credentials Access Keys productId and PRODUCT_SECRET for Referral Component Cello JS" />

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

Add this script to the `head` tag of your HTML:

<Tabs>
  <Tab title="Sandbox URL">
    ```javascript theme={null}
    <script
      type="module"
      src="https://assets.sandbox.cello.so/app/latest/cello.js"
      async>
    </script>
    ```
  </Tab>

  <Tab title="Production URL">
    ```javascript theme={null}
    <script
      type="module"
      src="https://assets.cello.so/app/latest/cello.js"
      async
    ></script>
    ```
  </Tab>
</Tabs>

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

### Content Security Policy (CSP)

Most applications don't need any changes here. This section only applies if your site enforces a Content Security Policy - if you don't set CSP headers, or your policy is permissive, you can skip it.

The Cello widget loads its script and assets from Cello domains at runtime. If your policy is restrictive, extend it with the following sources so the widget can load and run:

```text theme={null}
script-src  https://assets.cello.so
connect-src https://share.cello.so
img-src     https://cdn.cello.so https://p.typekit.net blob: data:
style-src   https://use.typekit.net 'unsafe-inline'
font-src    https://use.typekit.net https://p.typekit.net
```

<Note>
  * These directives extend your existing policy; if you use a restrictive `default-src`, keep all of the above explicit.
  * Sandbox environments use the equivalent `*.sandbox.cello.so` domains (for example `https://assets.sandbox.cello.so` and `https://share.sandbox.cello.so`).
</Note>

If the widget fails to load and your browser console shows errors like `Refused to connect because it violates the document's Content Security Policy`, see [Troubleshooting](#the-widget-doesnt-load-and-the-console-shows-content-security-policy-errors) below.

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

<Danger>
  Generate JWT tokens server-side only. Never create tokens in the browser.
</Danger>

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.

<Warning>
  User details (email, first name) are required for fraud detection and features like email notifications and personalized messaging.
</Warning>

<CodeGroup>
  ```javascript JavaScript theme={null}
  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
    }
  });
  ```
</CodeGroup>

This implementation works with asynchronous script loading. For complete configuration options, see [SDK Reference](/sdk/client-side/cello-js-usage#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

<Check>
  **Congratulations!** You have successfully integrated Cello Referral Component!
</Check>

Next, you can integrate Referral Component into your mobile applications:

<CardGroup>
  <Card title="iOS SDK" icon="apple" href="/sdk/mobile/ios" />

  <Card title="Android SDK" icon="android" href="/sdk/mobile/android" />

  <Card title="React Native SDK" icon="react" href="/sdk/mobile/react-native" />
</CardGroup>

***

## 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:

<AccordionGroup>
  <Accordion title="Option 1: Named user whitelist">
    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.
  </Accordion>

  <Accordion title="Option 2: Show/Hide Referral Component conditionally">
    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.
  </Accordion>
</AccordionGroup>

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

<Tip>
  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.
</Tip>

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 theme={null}
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`.

### The widget doesn't load and the console shows `Content Security Policy` errors

If your browser console shows errors like these, your site's Content Security Policy (CSP) is blocking Cello resources:

```text theme={null}
Refused to execute inline script because it violates the following Content Security Policy directive: "script-src ..."
Refused to load the script 'https://assets.cello.so/app/latest/cello.js' because it violates the following Content Security Policy directive: "script-src ..."
Fetch API cannot load https://share.cello.so/api/products/.../initialize/v2. Refused to connect because it violates the document's Content Security Policy.
Refused to load the image because it violates the following Content Security Policy directive: "img-src ..."
Refused to apply inline style because it violates the following Content Security Policy directive: "style-src ..."
Refused to load the font because it violates the following Content Security Policy directive: "font-src ..."
```

Any error containing `violates the following Content Security Policy directive` or `violates the document's Content Security Policy` means your CSP headers need to be updated: add the Cello domains to your policy. The directive named in the error (`script-src`, `connect-src`, `img-src`, `style-src`, `font-src`) tells you which one is missing. See [Content Security Policy (CSP)](#content-security-policy-csp) above for the full list of required sources. Remember that sandbox environments use `*.sandbox.cello.so` domains.

## 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 `<body>` 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 `<body>` as your AppRoot element as it would create a race condition.

```typescript theme={null}
@Component({
  selector: 'app-root',
  ...
})
```

```html theme={null}
<body>
    <app-root></app-root>
</body>
```

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 theme={null}
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<void>(resolve => setTimeout(() => resolve(), timeout));
  }

  async loadScript(src: string): Promise<void> {
     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:

<CardGroup>
  <Card title="Embedded Script Tag" icon="code" href="/sdk/client-side/embedded-script-tag">
    Add directly to your HTML pages with a script tag
  </Card>

  <Card title="Google Tag Manager" icon="google" href="/sdk/client-side/google-tag-manager">
    Deploy through GTM without code changes
  </Card>
</CardGroup>

## Key Capabilities

Attribution JS enables you to:

### Referral Tracking

* **Capture referral codes** - Automatically detect and store `ucc` parameters from referral links
* **Retrieve referral data** - Access referral codes programmatically with `getUcc()`. Returns data from URL parameters or stored cookies (persisted for 3 months)
* **Form integration** - Auto-inject hidden referral fields into signup forms for seamless attribution

### Personalization & Campaigns

* **Get referrer names** - Display personalized messages using `getReferrerName()` to retrieve the name of the person who sent the referral
* **Access campaign config** - Use `getCampaignConfig()` to retrieve discount percentages (in decimal format: 0.1 = 10%) and duration in months for referred users
* **Dynamic discount display** - Show referral incentives based on campaign parameters with proper percentage conversion for user display

### 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 `window.CelloAttribution("getUcc")` method
3. **Code persists** - Stored as first-party cookie for 3 months to handle return visits and cross-session attribution
4. **Methods available** - All attribution methods (`getUcc`, `getReferrerName`, `getCampaignConfig`) become available asynchronously after script initialization
5. **Signup attribution** - Referral code (`ucc`) is automatically attached to forms or retrieved programmatically for user registration
6. **Referral conversion tracking** - Pass the referral code (`ucc`) to Cello when tracking signups and purchases for complete attribution

## Next Steps

<Steps>
  <Step title="Install the Library">
    Choose between [embedded script](/sdk/client-side/embedded-script-tag) or [GTM installation](/sdk/client-side/google-tag-manager)
  </Step>

  <Step title="Verify Installation">
    Test that referral codes are being captured correctly
  </Step>

  <Step title="Explore the API">
    Review all [available methods](/sdk/client-side/attribution-js-usage) for advanced functionality
  </Step>
</Steps>

## API Method Calls

All Cello Attribution methods use the unified `CelloAttribution` function syntax:

```javascript theme={null}
const ucc = await window.CelloAttribution("getUcc");
const referrerName = await window.CelloAttribution("getReferrerName");
const campaignConfig = await window.CelloAttribution("getCampaignConfig");
```

<Note>
  Attribution JS works alongside [Cello JS](/sdk/client-side/cello-js-introduction) for complete referral program functionality. While Attribution JS handles tracking and data retrieval, Cello JS provides the referral component interface.
</Note>


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

## Script Initialization and Timing

The attribution script loads asynchronously. To avoid race conditions between script loading and your application calls, you have two options:

### Option 1: Queue Function (Recommended)

Add this JavaScript code before any calls to the library to queue commands until the script loads:

```javascript expandable theme={null}
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}
```

### Option 2: Wait for Script Initialization

Alternatively, wait for the script to load before making calls:

```javascript theme={null}
document.addEventListener('DOMContentLoaded', async function() {
    // Wait for script initialization
    await new Promise(resolve => setTimeout(resolve, 1000));
    
    if (typeof window.CelloAttribution === 'function') {
        // Now safe to call methods
        const ucc = await window.CelloAttribution("getUcc");
        console.log('UCC:', ucc);
    } else {
        console.error('Cello Attribution script failed to load');
    }
});
```

## `attachTo(formElement)`

Attaches hidden input to the passed `HTMLFormElement` node, or array of nodes.

```javascript theme={null}
window.CelloAttribution("attachTo", formElement);
```

### Accepts

<ParamField type="HTMLFormElement | HTMLFormElement[]">
  Form(s) to attach the hidden input to
</ParamField>

### Example

```javascript theme={null}
window.CelloAttribution("attachTo", document.querySelector("form"));
```

***

## `getCampaignConfig()`

Returns campaign configuration for new users, including discount information.

```javascript theme={null}
const campaignConfig = await window.CelloAttribution("getCampaignConfig");
```

### Returns

<ResponseField name="campaignConfig" type="object">
  The campaign config object:

  <Expandable title="properties">
    <ResponseField name="newUserDiscountMonth" type="number">
      Duration of discount in months (e.g., 12 for 12 months)
    </ResponseField>

    <ResponseField name="newUserDiscountPercentage" type="number">
      Discount as decimal format (0.1 = 10%, 0.25 = 25%)
    </ResponseField>
  </Expandable>
</ResponseField>

### Complete Example

```javascript theme={null}
const config = await window.CelloAttribution("getCampaignConfig");
console.log(config);
// Output:
// {
//   newUserDiscountPercentage: 0.1,    // 10% discount
//   newUserDiscountMonth: 12           // For 12 months
// }

// Convert to display format:
const displayPercentage = config.newUserDiscountPercentage * 100; // 10
const message = `${displayPercentage}% off for ${config.newUserDiscountMonth} months`;
console.log(message); // "10% off for 12 months"

// Use in your UI:
document.getElementById('discount-banner').innerHTML = 
  `🎉 Special offer: ${displayPercentage}% off your first ${config.newUserDiscountMonth} months!`;
```

## `getReferrerName()`

Returns the referrer's name, if provided in the referral link.

```javascript theme={null}
const name = await window.CelloAttribution("getReferrerName");
```

### Returns

<ResponseField name="name" type="string | undefined">
  Referrer's name or `undefined`
</ResponseField>

## `getUcc()`

Retrieves the referral code `ucc` from the URL or the cookie (if cookies are enabled).

```javascript theme={null}
const ucc = await window.CelloAttribution("getUcc");
```

### Returns

<ResponseField name="ucc" type="string">
  Unique campaign code/referral code
</ResponseField>

## ~~`attachAll()`~~

> ⚠️ **Deprecated**: forms are now auto-detected and the hidden `ucc` input is injected automatically.
> Use [`attachTo(formElement)`](#attachto-formelement) for targeted cases instead.

<Expandable title="more">
  ```javascript theme={null}
  window.CelloAttribution("attachAll");
  ```
</Expandable>

***

## Troubleshooting

### Attribution Script Not Loading

```javascript theme={null}
// Check if script loaded correctly
if (typeof window.CelloAttribution !== 'function') {
    console.error('Cello Attribution script failed to load');
    // Implement fallback logic
    // For example, proceed without attribution or show error message
}
```

### Methods Returning undefined or null

**Common causes:**

* Script not fully initialized - wait for DOM load or use the queue function
* Incorrect method syntax - ensure you use `window.CelloAttribution("methodName")`
* No referral data available - user didn't come from a referral link

**Solutions:**

```javascript theme={null}
// Always check return values
const ucc = await window.CelloAttribution("getUcc");
if (ucc) {
    console.log('Referral code found:', ucc);
} else {
    console.log('No referral code - user came directly');
}

// Handle missing referrer names gracefully
const referrerName = await window.CelloAttribution("getReferrerName");
const greeting = referrerName 
    ? `Welcome! ${referrerName} referred you` 
    : 'Welcome to our platform';
```

### Testing Attribution Methods

Test all methods in your browser console:

```javascript theme={null}
// Test UCC retrieval
await window.CelloAttribution("getUcc");
// Returns: string (referral code) or null

// Test referrer name
await window.CelloAttribution("getReferrerName");
// Returns: string (referrer name) or undefined

// Test campaign config
await window.CelloAttribution("getCampaignConfig");
// Returns: { newUserDiscountPercentage: number, newUserDiscountMonth: number }
```

### Network and Loading Issues

```javascript theme={null}
// Check if attribution script is blocked
fetch('https://assets.cello.so/attribution/latest/cello-attribution.js')
  .then(response => {
    if (!response.ok) {
      console.error('Attribution script blocked or unavailable');
    }
  })
  .catch(error => {
    console.error('Network error loading attribution script:', error);
  });
```

### Common Integration Patterns

```javascript theme={null}
// Safe attribution check with fallbacks
async function initializeWithAttribution() {
    try {
        // Wait for script if needed
        let retries = 0;
        while (typeof window.CelloAttribution !== 'function' && retries < 10) {
            await new Promise(resolve => setTimeout(resolve, 500));
            retries++;
        }
        
        if (typeof window.CelloAttribution === 'function') {
            const ucc = await window.CelloAttribution("getUcc");
            const referrerName = await window.CelloAttribution("getReferrerName");
            const campaignConfig = await window.CelloAttribution("getCampaignConfig");
            
            return { ucc, referrerName, campaignConfig };
        } else {
            throw new Error('Attribution script not available');
        }
    } catch (error) {
        console.warn('Attribution initialization failed:', error);
        return { ucc: null, referrerName: null, campaignConfig: null };
    }
}

// Use in your application
initializeWithAttribution().then(({ ucc, referrerName, campaignConfig }) => {
    // Proceed with or without attribution data
    if (ucc) {
        console.log('Referral detected:', { ucc, referrerName, campaignConfig });
    }
});
```

***

## ~~`getReferral()`~~

> ⚠️ **Deprecated**: use [`getUcc()`](#getucc) instead.

<Expandable title="more">
  ```javascript theme={null}
  const ucc = window.CelloAttribution("getReferral");
  ```

  ### Returns

  <ResponseField name="ucc" type="string">
    Unique campaign code/referral code
  </ResponseField>
</Expandable>


# Introduction
Source: https://docs.cello.so/sdk/client-side/cello-js-introduction

JavaScript SDK for embedding the Cello Referral Component in web applications

<img alt="Referral Component Pn" />

## 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:

<CardGroup>
  <Card title="Quickstart Guide" icon="rocket" href="/referral-component/quickstart">
    Step-by-step instructions to add the Referral Component to your web app
  </Card>
</CardGroup>

## 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:

<CardGroup>
  <Card title="iOS SDK" icon="apple" href="/sdk/mobile/ios">
    Swift/Objective-C SDK for iOS apps
  </Card>

  <Card title="Android SDK" icon="android" href="/sdk/mobile/android">
    Kotlin/Java SDK for Android apps
  </Card>

  <Card title="React Native" icon="react" href="/sdk/mobile/react-native">
    Cross-platform mobile SDK
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Install the SDK">
    [Follow the quickstart](/referral-component/quickstart) to add Cello JS to your application
  </Step>

  <Step title="Authenticate Users">
    [Set up JWT authentication](/sdk/client-side/user-authentication) for secure user sessions
  </Step>

  <Step title="Explore the API">
    [View all available methods](/sdk/client-side/cello-js-usage) in the usage documentation
  </Step>
</Steps>


# 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 theme={null}
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 theme={null}
await window.Cello("boot", options);
```

### Accepts

<ParamField type="object">
  The initialization options object:

  <Expandable title="properties">
    <ParamField type="string">
      Identifier of the product your users will refer.
      You can obtain this in your Cello Portal.
    </ParamField>

    <ParamField type="string">
      Access token generated for the given user.
      More in [User Authentication](/referral-component/user-authentication).
    </ParamField>

    <ParamField type="object">
      Product user details object. Required for select features

      <Expandable title="properties">
        <ParamField type="string">
          Email of the product user. This data is used in the personalization of the referral
          experience, e.g. email notifications. Required for select features
        </ParamField>

        <ParamField type="string">
          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
        </ParamField>

        <ParamField type="string">
          Last name of the product user
        </ParamField>

        <ParamField type="string">
          Full name of the product user.
          Use this option if you do not have first name and last name separately.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Product user country, if known. ISO 3166 Alpha-2 standard e.g. `DE`.
      If the country is not on the [supported payout countries list](/guides/user-experience/overview#reward-countries-and-payout-methods), the Referral Component will not be booted for this user.
      If no country is passed, Cello will still be booted.
      Note: this uses the country your product has on file, which may differ from the user's actual PayPal payout country. See the [unsupported countries guidance](/guides/user-experience/overview#reward-countries-and-payout-methods) for tradeoffs before using this to gate visibility.
    </ParamField>

    <ParamField type="string">
      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.
      Note: the language must be enabled for your product by Cello - if the language is not enabled, this parameter has no effect and the component falls back to your product's default language. Contact Cello support to enable additional languages.
    </ParamField>

    <ParamField type="string">
      Set light or dark theme to match your app’s interface. Accepts `light` and `dark`.
      Default: `light`.
    </ParamField>

    <ParamField type="boolean">
      Hides the entire default Cello launcher button. Use this when you want to provide your own launcher element via `customLauncherSelector`.
      Default: `false`.
      Note: this hides the **button**, not just the notification badge. To hide only the badge on a custom launcher element, add `data-cello-badge="false"` to your HTML element instead - see [Configure notification badge](/referral-component/custom-launcher#configure-notification-badge). There is no `hideDefaultBadge` boot option.
    </ParamField>

    <ParamField type="function">
      Callback event for when Referral Component widget is opened.
    </ParamField>

    <ParamField type="function">
      Callback event for when Referral Component widget is closed.
    </ParamField>

    <ParamField type="function">
      Callback handler for user interactions within the Referral Component.
      Receives two parameters: `action` (string) and `payload` (any).
      Currently supports `linkCopied` action which provides the copied URL as payload.
    </ParamField>
  </Expandable>
</ParamField>

### Example

```javascript theme={null}
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",
      },
      onUserInteraction: (action, payload) => {
        console.log('user interaction', action, payload)
        if (action === 'linkCopied') {
          const urlThatWasCopied = payload
          // Handle the copied link (e.g., track analytics, show notification)
        }
      }
    };

    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 theme={null}
window.Cello("changeLanguage", "de");
```

### Accepts

<ParamField type="string">
  The language string in ISO 639-1
</ParamField>

## `setThemeMode(theme)`

Changes the Referral Component theme at runtime without re-initializing it.

```javascript theme={null}
window.Cello("setThemeMode", "dark");
```

### Accepts

<ParamField type="string"> The theme mode to apply. Accepted values are `light` or `dark`. </ParamField>

## `close()`

Closes Referral Component.

```javascript theme={null}
window.Cello.close();
```

***

## `getActiveUcc()`

Returns active `ucc` and invite `link` for the currently logged-in user.

```javascript theme={null}
const { ucc, link } = await window.Cello("getActiveUcc");
```

### Returns

<ResponseField name="activeUcc" type="object">
  The active ucc object:

  <Expandable title="properties">
    <ResponseField name="ucc" type="string">
      Active unique campaign code or referral code for the current logged-in user
    </ResponseField>

    <ResponseField name="link" type="string">
      Personal invite link for the current logged-in user
    </ResponseField>
  </Expandable>
</ResponseField>

## `getCampaignConfig()`

Returns campaign config values for the currently logged-in user.

```javascript theme={null}
const campaignConfig = await window.Cello("getCampaignConfig");
```

### Returns

<ResponseField name="campaignConfig" type="object">
  The campaign config object:

  <Expandable title="properties">
    <ResponseField name="primaryCurrency" type="string">
      Primary currency code
    </ResponseField>

    <ResponseField name="revenuePercentage" type="number">
      Percentage of attributed new revenue that will be paid as a reward
    </ResponseField>

    <ResponseField name="rewardCap" type="number">
      Maximum reward that can be earned per referral
    </ResponseField>

    <ResponseField name="newSignupBonus" type="number">
      Additional reward for signups to encourage more sharing
    </ResponseField>

    <ResponseField name="newPurchaseBonus" type="number">
      Additional reward for purchases to encourage more sharing
    </ResponseField>

    <ResponseField name="newUserDiscountMonth" type="number">
      How long new users get a discount
    </ResponseField>

    <ResponseField name="newUserDiscountPercentage" type="number">
      The discount new users get
    </ResponseField>
  </Expandable>
</ResponseField>

## `getLabels()`

Returns select labels used in our Referral Component.

```javascript theme={null}
const labels = await window.Cello("getLabels");
```

### Returns

<ResponseField name="labels" type="object">
  The labels object:

  <Expandable title="properties">
    <ResponseField name="customLauncher" type="string">
      A welcome text useful for building custom launchers
    </ResponseField>
  </Expandable>
</ResponseField>

## `hide()`

Hides the Cello button or bookmark that launches the Referral Component.

```javascript theme={null}
window.Cello("hide");
```

***

## `open(destination)`

Opens Referral Component.

```javascript theme={null}
window.Cello("open", destination);
```

### Accepts

<ParamField type="string">
  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
</ParamField>

## `show()`

Shows the Cello button or bookmark that launches the Referral Component.

```javascript theme={null}
window.Cello("show");
```

***

## `showAnnouncement(announcement)`

Triggers an [announcement](/docs/notifications#announcement).

```javascript theme={null}
window.Cello("showAnnouncement", announcement);
```

### Accepts

<ParamField type="string" />

### Example

Example below triggers a default welcome announcement:

```javascript theme={null}
const announcement = { type: "welcome-announcement-1" };
window.Cello("showAnnouncement", announcement);
```

<Warning>
  A fulfilled promise from `showAnnouncement` only means the SDK accepted the request. It does **not** mean the announcement is visible to the user.

  The announcement is anchored to the element matched by your **Announcement Selector** using `document.querySelector` (first match in DOM order). If that element is hidden, zero-sized, or off-screen, the announcement renders but is invisible. If you see `Promise {<fulfilled>: undefined}` but no announcement, run `document.querySelectorAll("<your selector>")` in the console - the result must be exactly one visible element.

  See [Troubleshooting: announcement not showing](/referral-component/custom-launcher#troubleshooting-announcement-not-showing) for the full diagnostic flow.
</Warning>

## `shutdown()`

Shuts down connection to Cello and unmounts the Referral Component.

```javascript theme={null}
window.Cello("shutdown");
```

***

## `updateProductUserDetails(productUserDetails)`

Updates user details at runtime without re-initializing the Referral Component.

```javascript theme={null}
window.Cello("updateProductUserDetails", productUserDetails);
```

### Accepts

<ParamField type="object">
  The product user details object

  <Expandable title="properties">
    <ParamField type="string">
      Email of the product user. This data is used in the personalization of the referral
      experience, e.g. email notifications. Required for select features
    </ParamField>

    <ParamField type="string">
      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
    </ParamField>

    <ParamField type="string">
      Last name of the product user
    </ParamField>

    <ParamField type="string">
      Full name of the product user.
      Use this option if you do not have first name and last name separately.
    </ParamField>
  </Expandable>
</ParamField>

### Example

```javascript theme={null}
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.

**Script Loading Context:** The attribution script loads asynchronously and methods become available shortly after page load. All attribution methods use the unified `window.CelloAttribution("methodName")` syntax.

# 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 `<head>` tag of **each page** on your website.

<Note>
  Make sure to use `type="module"` and `async` html params in the script tag
</Note>

<Tabs>
  <Tab title="Sandbox URL">
    ```javascript theme={null}
    <script type="module" src="https://assets.sandbox.cello.so/attribution/latest/cello-attribution.js" async></script>
    ```
  </Tab>

  <Tab title="Production URL">
    ```javascript theme={null}
    <script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>
    ```
  </Tab>
</Tabs>

# 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:

## Step 1: Test with URL parameters

Add `?productId=test` and `?ucc=test` to your website URL:

```html theme={null}
https://yourwebsite.com/?productId=test&ucc=test
```

## Step 2: Check cookie storage

Open browser developer tools (F12) and verify these values are saved in cookies:

* `cello-product-id` should contain `test`
* `cello-referral` should contain `test`

## Step 3: Test method access

Navigate to your signup page and test the attribution methods from the browser console:

```javascript theme={null}
// Wait for script to load if needed
setTimeout(async () => {
  try {
    const ucc = await window.CelloAttribution('getUcc');
    console.log('UCC test result:', ucc); // Should return 'test'
    
    // Test other methods
    const referrerName = await window.CelloAttribution('getReferrerName');
    const campaignConfig = await window.CelloAttribution('getCampaignConfig');
    
    console.log('Attribution methods working:', {
      ucc,
      referrerName,
      campaignConfig
    });
  } catch (error) {
    console.error('Attribution test failed:', error);
  }
}, 2000);
```

Expected result:

```javascript theme={null}
Promise {<fulfilled>: 'test'}
```

## Troubleshooting Installation Issues

### Script not loading

```javascript theme={null}
// Check if script loaded
if (typeof window.CelloAttribution !== 'function') {
  console.error('Attribution script failed to load');
  // Check network tab for loading errors
  // Verify script URL is accessible
}
```

### Methods return undefined

* Wait longer for script initialization (try 3-5 seconds)
* Check browser console for JavaScript errors
* Verify script tag has `type="module"` and `async` attributes
* Ensure no ad blockers are interfering

### Cookie issues

* Check if cookies are enabled in browser
* Verify no GDPR/cookie consent is blocking storage
* Test in incognito mode to rule out extensions

<Icon icon="check" /> **Installation successful** if methods return expected values and cookies are stored properly.

<Icon icon="warning" /> **Need help?** Check the [troubleshooting guide](/sdk/client-side/attribution-js-usage#troubleshooting) for common issues and solutions.


# 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 theme={null}
<!-- Cello Attribution Script -->
<script>
  (function () {
    var s = document.createElement('script');
    s.type = 'module';
    s.src = 'https://assets.cello.so/attribution/latest/cello-attribution.js';
    s.async = true;
    document.head.appendChild(s);
  })();
</script>
```

3. Name your tag (e.g., "Cello Attribution Script")

## Step 3: Configure Consent Settings

If your GTM container uses a Consent Management Platform (such as Cookiebot, OneTrust, or CookieFirst) with Google Consent Mode, you must configure the tag's consent settings to prevent the script from being blocked.

1. In the tag editor, expand **Advanced Settings**
2. Scroll down to **Consent Settings**
3. Select **"No additional consent required"**

<Warning>
  If you leave consent settings as **"Not set"** (the default), the tag inherits your container's consent behavior. When Consent Mode is active, this typically means the tag will be blocked until cookie consent is granted - causing the attribution script to **load inconsistently or not at all**.
</Warning>

Cello's attribution cookies are classified as [strictly necessary / essential cookies](/landing-pages/manage-cookies). They store only the referral campaign code (`ucc`) and do not track user identity. Many customers treat them as essential and load them independently of cookie consent banners. Consult your legal team to confirm this aligns with your compliance requirements.

## Step 4: 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 5: 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 6: 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 theme={null}
window.CelloAttribution('getUcc')
```

If the script is installed correctly, you should see a Promise response:

```javascript theme={null}
Promise {<pending>}
```

### 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 theme={null}
   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

<Check>
  **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
</Check>

## Troubleshooting

### Attribution script loads inconsistently

If the Cello attribution script only loads on some page views (works on one refresh but not the next), this is almost always caused by **Google Consent Mode** blocking the tag.

**Why it happens:** When your GTM container has Consent Mode configured, the default consent state is set to "denied." If the Cello tag's consent settings are left as "Not set," GTM may block the tag before the returning visitor's prior consent choice is restored from the cookie - creating a race condition where the script sometimes fires and sometimes doesn't.

**Fix:** Edit the Cello Attribution Script tag → **Advanced Settings** → **Consent Settings** → select **"No additional consent required"**. See [Step 3](#step-3-configure-consent-settings) above.

You can verify this is the cause by opening **GTM Preview** mode and checking whether the Cello tag shows as "Blocked" or displays a consent-related note next to it.


# 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

<Danger>
  Keep your credentials safe. **Never** generate a token or store your secret on the client side!
</Danger>

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):

<img alt="Portal Credentials Access Keys productId and PRODUCT_SECRET for Referral Component Cello JS" />

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

<Warning>
  It is important that this ID is **unique per user**, rather than organisation.
</Warning>

### JWT signing library

Regardless of the signing library you choose, make sure you use the `HS512` signing algorithm:

```json theme={null}
{
  "alg": "HS512",
  "typ": "JWT"
}
```

### Token generation

Token payload attributes:

<ParamField type="string">
  Identifier of the product your users will refer
</ParamField>

<ParamField type="string">
  Your logged-in user's unique identifier within your system
</ParamField>

<ParamField type="int">
  A token issuing Unix timestamp. Example: `1661876739`
</ParamField>

<ParamField type="string">
  Original signup date of the user. This helps to improve [accuracy](/guides/attribution/auto-attribution) for auto-attributions.
</ParamField>

<ParamField type="list">
  List of organizations the user is assigned to. This is required to enable automatic attribution when referrals are based on organizations. [More information](/guides/attribution/auto-attribution).
</ParamField>

<Note>
  Note that some libraries do not require you to pass `iat` in the payload and default to the current time if you don't.
</Note>

### Example

Example of token generation in a NodeJS backend with JavaScript:

```javascript theme={null}
import { sign } from 'jsonwebtoken';

const tokenPayload = {
  productId: 'REPLACE_WITH_PRODUCT_ID',
  productUserId: 'REPLACE_WITH_CURRENT_USER_ID',
  signupDate: '2022-10-05T14:14:34Z',
  orgIds: ['ORG_1, ORG_2']
};
const secret = 'REPLACE_WITH_PRODUCT_SECRET';

const token = sign(tokenPayload, secret, {
  algorithm: 'HS512',
});
```

<Danger>
  Creating a JWT token should **always** be done in your backend code and **not in the browser**!
</Danger>

Below is an example content of the generated JWT token.

```json theme={null}
{
  "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 theme={null}
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

<CardGroup>
  <Card title="Cello JS" icon="js" href="/sdk/client-side/cello-js-introduction">
    Referral component for your web app
  </Card>

  <Card title="Attribution JS" icon="js" href="/sdk/client-side/attribution-js-introduction">
    Script for tracking referrals on landing pages
  </Card>
</CardGroup>

# Mobile SDKs

<CardGroup>
  <Card title="iOS SDK" icon="apple" href="/sdk/mobile/ios">
    Referral component for your iOS app
  </Card>

  <Card title="Android SDK" icon="android" href="/sdk/mobile/android">
    Referral component for your Android app
  </Card>

  <Card title="ReactNative SDK" icon="react" href="/sdk/mobile/react-native">
    Referral component for iOS and Android
  </Card>
</CardGroup>


# 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 theme={null}
dependencies {
    implementation("so.cello.android:cello-sdk:0.9.1")
}
```

Also, ensure that Maven Central is added to your root `build.gradle`:

```gradle theme={null}
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 theme={null}
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="cello_env">prod</string>
</resources>
```

To change the environment, simply replace the value of `cello_env`. For instance, to set the environment to sandbox:

```xml theme={null}
<string name="cello_env">sandbox</string>
```

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 theme={null}
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 theme={null}
class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Cello.initialize(this, "YOUR_PRODUCT_ID", token)
    }
}
```

#### Java

```java theme={null}
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 theme={null}
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 theme={null}
Cello.client().openWidget()
```

Example using Compose:

```kotlin theme={null}
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      |
| productUserDetails | ProductUserDetails | Product user details                            | No       |
| language           | String             | Initial language of the widget                  | No       |
| themeMode          | String             | Initial theme mode: `"light"` or `"dark"`       | No       |

```kotlin theme={null}
import com.cello.cello_sdk.ProductUserDetails

val productUserDetails = ProductUserDetails(
    firstName = "John",
    lastName = "Doe",
    fullName = "John Doe",
    email = "john.doe@example.com"
)

Cello.initialize(this, "YOUR_PRODUCT_ID", token, productUserDetails = productUserDetails, language = 'de', themeMode = 'light')
```

### `Cello.showFab()`

Shows the Floating action button or bookmark that launches the Referral Component

```kotlin theme={null}
Cello.client().showFab()
```

### `Cello.hideFab()`

Hides the Floating action button or bookmark that launches the Referral Component

```kotlin theme={null}
Cello.client().hideFab()
```

### `Cello.openWidget()`

Opens the referral component.

```kotlin theme={null}
Cello.client().openWidget()
```

### `Cello.hideWidget()`

Hides the referral component.

```kotlin theme={null}
Cello.client().hideWidget()
```

### `Cello.getActiveUcc()`

A method to get an active `ucc` and invite link for the currently logged in user.

```kotlin theme={null}
val result = Cello.client().getActiveUcc()
```

## `getCampaignConfig()`

Returns campaign config values for the currently logged-in user.

```kotlin theme={null}
let result = Cello.client().getCampaignConfig()
```

### Returns

<ResponseField name="campaignConfig" type="object">
  The campaign config object:

  <Expandable title="properties">
    <ResponseField name="primaryCurrency" type="string">
      Primary currency code
    </ResponseField>

    <ResponseField name="revenuePercentage" type="number">
      Percentage of attributed new revenue that will be paid as a reward
    </ResponseField>

    <ResponseField name="rewardCap" type="number">
      Maximum reward that can be earned per referral
    </ResponseField>

    <ResponseField name="newSignupBonus" type="number">
      Additional reward for signups to encourage more sharing
    </ResponseField>

    <ResponseField name="newPurchaseBonus" type="number">
      Additional reward for purchases to encourage more sharing
    </ResponseField>

    <ResponseField name="newUserDiscountMonth" type="number">
      How long new users get a discount
    </ResponseField>

    <ResponseField name="newUserDiscountPercentage" type="number">
      The discount new users get
    </ResponseField>
  </Expandable>
</ResponseField>

### `Cello.changeLanguage()`

A method to change the language of the Referral component at runtime without re-initialising it.

```kotlin theme={null}
Cello.client().changeLanguage("de")
```

### `Cello.setThemeMode()`

A method to change the theme mode of the Referral component at runtime without re-initialising it.

```kotlin theme={null}
Cello.client().setThemeMode("dark")
```

**Parameters:**

* `themeMode` (*String*): The theme mode to set. Valid values are `"light"` or `"dark"`.

### `Cello.shutdown()`

Shuts down connection to Cello and unmounts the component

```kotlin theme={null}
Cello.client().shutdown()
```

***

## Error Handling

### Common Error Scenarios

#### 1. Invalid Parameters

**What it means:** The product ID or token provided during initialization is empty or blank.

**Error behavior:**

* SDK initialization is **silently skipped**
* Warning logged: `"Initialization skipped: productId and token must not be empty or blank"`
* No exception thrown

**Common causes:**

* Empty strings for productId or token
* Whitespace-only strings

***

#### 2. Network/API Errors

**What it means:** The network request to initialize the SDK or update token failed.

**Error type:** `RuntimeException("Response not successful")`

**Common causes:**

* No internet connection
* Server errors (5xx responses)
* HTTP errors (4xx responses)
* Timeout issues
* Firewall or proxy blocking requests

***

#### 3. Activity State Errors

**What it means:** The Activity is destroyed, finishing, or not available when trying to perform UI operations.

**Error type:** `IllegalStateException("Activity is not valid")`

**Error message:** `"Cannot perform UI operation - Activity is not available or destroyed"`

**Common causes:**

* Calling SDK methods after Activity is destroyed
* Activity finishing during async operations
* Attempting UI operations during Activity transitions

***

#### 4. Initialization Failures

**What it means:** The SDK failed to initialize due to an error in the initialization process.

**Error behavior:**

* Exception passed to callback
* Error logged: `"Error initializing widget: {exception message}"`
* Pending operations cleared

**Common causes:**

* Network connectivity issues
* Invalid credentials (product ID or token)
* Server-side configuration issues

***

### Error Handling Best Practices

**1. Always handle both success and error cases:**

```kotlin theme={null}
Cello.initialize(this, productId, token) { config, exception ->
    if (exception != null) {
        // Handle error
        Log.e("Cello", "Error: ${exception.message}")
        showErrorMessage("Unable to initialize referral system")
    } else {
        // Handle success
        Log.d("Cello", "Initialized successfully")
        setupReferralFeatures(config)
    }
}
```

**2. Validate parameters before SDK calls:**

```kotlin theme={null}
fun initializeCello(productId: String, token: String) {
    // Validate product ID
    if (productId.isBlank()) {
        Log.e("Cello", "Product ID cannot be empty")
        showError("Configuration error")
        return
    }

    // Validate token
    if (token.isBlank()) {
        Log.e("Cello", "Token cannot be empty")
        showError("Authentication error")
        return
    }

    // Check Activity state
    if (isFinishing || isDestroyed) {
        Log.e("Cello", "Cannot initialize - Activity is finishing")
        return
    }

    Cello.initialize(this, productId, token) { config, error ->
        // Handle result
    }
}
```

**3. Implement retry logic for network errors:**

```kotlin theme={null}
class CelloManager(private val activity: Activity) {
    private var retryCount = 0
    private val maxRetries = 3

    fun initializeWithRetry(productId: String, token: String) {
        Cello.initialize(activity, productId, token) { config, exception ->
            if (exception != null) {
                handleInitializationError(exception, productId, token)
            } else {
                retryCount = 0
                onInitializationSuccess(config)
            }
        }
    }

    private fun handleInitializationError(
        exception: Exception,
        productId: String,
        token: String
    ) {
        Log.e("Cello", "Initialization error: ${exception.message}")

        // Retry for network errors
        if (exception is RuntimeException && retryCount < maxRetries) {
            retryCount++
            val delay = (2000L * retryCount) // Linear backoff

            Handler(Looper.getMainLooper()).postDelayed({
                Log.d("Cello", "Retrying initialization (attempt $retryCount)")
                initializeWithRetry(productId, token)
            }, delay)
        } else {
            // Max retries reached or non-recoverable error
            retryCount = 0
            showFinalError("Failed to initialize after $maxRetries attempts")
        }
    }
}
```

**4. Track initialization state:**

```kotlin theme={null}
class CelloStateManager(private val activity: Activity) {
    private var initializationState = InitState.NOT_INITIALIZED

    enum class InitState {
        NOT_INITIALIZED,
        INITIALIZING,
        INITIALIZED,
        FAILED
    }

    fun initialize(productId: String, token: String) {
        if (initializationState == InitState.INITIALIZING) {
            Log.w("Cello", "Initialization already in progress")
            return
        }

        initializationState = InitState.INITIALIZING

        Cello.initialize(activity, productId, token) { config, exception ->
            if (exception != null) {
                initializationState = InitState.FAILED
                Log.e("Cello", "Initialization failed")
            } else {
                initializationState = InitState.INITIALIZED
                Log.d("Cello", "Initialization successful")
            }
        }
    }

    fun showWidget() {
        when (initializationState) {
            InitState.NOT_INITIALIZED -> {
                Log.w("Cello", "SDK not initialized")
            }
            InitState.INITIALIZING -> {
                Log.w("Cello", "SDK still initializing")
            }
            InitState.FAILED -> {
                Log.e("Cello", "Cannot show widget - initialization failed")
            }
            InitState.INITIALIZED -> {
                Cello.openWidget()
            }
        }
    }
}
```

**5. Handle Activity lifecycle properly:**

```kotlin theme={null}
class MainActivity : AppCompatActivity() {
    private var isCelloReady = false

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initializeCello()
    }

    private fun initializeCello() {
        Cello.initialize(this, productId, token) { config, error ->
            if (error == null && !isFinishing && !isDestroyed) {
                isCelloReady = true
            }
        }
    }

    fun performCelloAction() {
        // Always check Activity and SDK state
        if (isFinishing || isDestroyed) {
            Log.w("Cello", "Activity is finishing - cannot perform action")
            return
        }

        if (!isCelloReady) {
            Log.w("Cello", "SDK not ready")
            return
        }

        Cello.openWidget()
    }

    override fun onDestroy() {
        super.onDestroy()
        if (isFinishing) {
            isCelloReady = false
            Cello.shutdown()
        }
    }
}
```

### Getting Help

If you encounter an error you can't resolve:

1. Check the error scenario in the reference above
2. Verify your integration follows the code examples
3. Check logcat for detailed error messages: `adb logcat | grep cello-sdk`
4. Verify network connectivity and firewall settings
5. Ensure product ID and token are valid and not empty
6. Check Activity lifecycle (not finishing or destroyed)
7. Contact Cello support with:
   * Full error message and stack trace from logcat
   * Steps to reproduce
   * SDK version
   * Android OS version and device model
   * Network conditions when error occurred


# Cello for Flutter
Source: https://docs.cello.so/sdk/mobile/flutter



<span>Beta</span>

The Cello Flutter SDK allows you to use Cello for iOS and Cello for Android in your Flutter 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 Flutter SDK supports Flutter **3.3.0** and above (Dart 3+).
* Cello for iOS supports **iOS 15+**.
* Cello for Android supports **API 21+**.

### Install Cello

```bash theme={null}
flutter pub add cello_sdk
```

Or add to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  flutter:
    sdk: flutter
  cello_sdk: ^0.0.1
```

Then run:

```bash theme={null}
flutter pub get
```

### Android Setup

The Flutter plugin automatically handles linking for Android. Ensure your app's `android/app/build.gradle` has the correct configuration:

```gradle theme={null}
android {
  compileSdk 34

  defaultConfig {
    minSdk 21
    // ... other config
  }
}
```

Ensure your project's `android/build.gradle` (or app-level) includes:

```gradle theme={null}
repositories {
  google()
  mavenCentral()
}
```

#### Internet Permission

Add internet permission in `android/app/src/main/AndroidManifest.xml`:

```xml theme={null}
<uses-permission android:name="android.permission.INTERNET" />
```

### iOS Setup

The Flutter plugin automatically handles linking for iOS via CocoaPods.

From your `ios/` directory, run:

```bash theme={null}
cd ios
pod install
cd ..
```

Ensure your `ios/Podfile` specifies iOS 15.0+:

```ruby theme={null}
platform :ios, '15.0'
```

## 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:

* `production` or `prod` (Production) *(default)*
* `sandbox` (Sandbox)

You specify the environment when initializing Cello:

```dart theme={null}
await Cello.initialize(
  CelloInitializeOptions(
    productId: 'your-product-id',
    token: 'your-token',
    environment: 'sandbox', // or 'production'
  ),
);
```

## Customize the Cello Referral Component

The Cello Flutter 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

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.

```dart theme={null}
import 'package:cello_sdk/cello_sdk.dart';

await 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()`.

```dart theme={null}
import 'package:cello_sdk/cello_sdk.dart';

ElevatedButton(
  onPressed: () async {
    await Cello.openWidget();
  },
  child: Text('Open Referral'),
)
```

## Flutter API

### `Cello.initialize(CelloInitializeOptions): Future<CelloConfiguration>`

Initializes the Cello referral component.

### CelloInitializeOptions

| Property           | Type               | Required | Description                                            |
| ------------------ | ------------------ | -------- | ------------------------------------------------------ |
| productId          | String             | yes      | Your product ID from Cello Portal                      |
| token              | String             | yes      | User authentication token                              |
| environment        | String?            | no       | Environment: `"production"` or `"sandbox"`             |
| productUserDetails | ProductUserDetails | no       | User details object (see below)                        |
| language           | String?            | no       | Initial language of the widget                         |
| themeMode          | String?            | no       | Initial theme mode: `"light"`, `"dark"`, or `"system"` |

### ProductUserDetails

Optional object with user information:

| Property  | Type   | Description          |
| --------- | ------ | -------------------- |
| firstName | String | User's first name    |
| lastName  | String | User's last name     |
| fullName  | String | User's full name     |
| email     | String | User's email address |

```dart theme={null}
import 'package:cello_sdk/cello_sdk.dart';

final config = await Cello.initialize(
  CelloInitializeOptions(
    productId: 'your-product-id',
    token: 'your-token',
    environment: 'production',
    productUserDetails: ProductUserDetails(
      firstName: 'John',
      lastName: 'Doe',
      fullName: 'John Doe',
      email: 'john.doe@example.com',
    ),
    language: 'de',
    themeMode: 'system',
  ),
);
```

### `Cello.showFab(): Future<void>`

Shows the default Cello button that launches the Referral Component

```dart theme={null}
await Cello.showFab();
```

### `Cello.hideFab(): Future<void>`

Hides the default Cello button that launches the Referral Component

```dart theme={null}
await Cello.hideFab();
```

### `Cello.openWidget(): Future<void>`

Opens the referral component.

```dart theme={null}
await Cello.openWidget();
```

### `Cello.hideWidget(): Future<void>`

Hides the referral component.

```dart theme={null}
await Cello.hideWidget();
```

### `Cello.getActiveUcc(): Future<Map<String, String>>`

A method to get an active `ucc` and related data for the currently logged in user.

```dart theme={null}
final ucc = await Cello.getActiveUcc();
// Returns: { "ucc": "...", "inviteLink": "..." } or empty map
```

### `Cello.getCampaignConfig(): Future<Map<String, dynamic>>`

A method to get the campaign configuration.

```dart theme={null}
final config = await Cello.getCampaignConfig();
// Returns: Map with campaign settings
```

### `Cello.changeLanguage(String language): Future<void>`

A method to change the language of the Referral component at runtime without re-initialising it.

**Note**: Requires iOS 14+ on iOS platform.

```dart theme={null}
await Cello.changeLanguage('de');
```

### `Cello.setThemeMode(String themeMode): Future<void>`

A method to change the theme mode of the Referral component at runtime without re-initialising it.

**Note**: Requires iOS 14+ on iOS platform.

```dart theme={null}
await Cello.setThemeMode('dark');
```

**Parameters:**

* `themeMode` (*String*): The theme mode to set. Valid values are `"light"`, `"dark"`, or `"system"`.

### `Cello.updateToken(String token): Future<void>`

Updates the user authentication token without re-initializing.

**Note**: Requires iOS 14+ on iOS platform.

```dart theme={null}
await Cello.updateToken('new-token');
```

### `Cello.shutdown(): Future<void>`

Shuts down connection to Cello and unmounts the component

```dart theme={null}
await Cello.shutdown();
```

### `Cello.tokenEvents: Stream<CelloTokenEvent>`

A broadcast stream that emits token lifecycle events.

```dart theme={null}
Cello.tokenEvents.listen((event) {
  switch (event.type) {
    case CelloTokenEventType.tokenAboutToExpire:
      // Refresh your token
      refreshToken();
      break;
    case CelloTokenEventType.tokenHasExpired:
      // Handle expired token
      handleExpiredToken();
      break;
  }
});
```

***

## Error Handling

### Exception types

The Cello Flutter SDK throws `PlatformException` with specific error codes when operations fail:

| Code                      | Platform(s)   | Trigger                                          | Typical causes                                                          |
| ------------------------- | ------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
| `InitializationError`     | iOS & Android | `Cello.initialize` completes with native failure | Invalid/empty product ID or token, network issues, bad environment      |
| `InitializationException` | Android       | Unexpected exception inside `Cello.initialize`   | Activity finishing, SDK not linked correctly, runtime crash             |
| `ActivityUnavailable`     | Android       | `Cello.initialize` without an active Activity    | Initialization triggered too early (e.g. before app fully ready)        |
| `TokenUpdateError`        | iOS           | `Cello.updateToken` failure                      | Token expired/invalid, network errors                                   |
| `LanguageChangeError`     | iOS           | `Cello.changeLanguage` failure                   | Unsupported language code, network errors                               |
| `ThemeModeChangeError`    | iOS           | `Cello.setThemeMode` failure                     | Invalid theme mode value, network errors                                |
| `Unavailable`             | iOS           | Feature requires iOS 14+                         | Device running \< iOS 14 when calling token, language, or theme updates |
| `ClientUnavailable`       | Android       | Method called before initialization              | SDK not initialized before calling other methods                        |
| `CelloError`              | Android       | Generic SDK error                                | Various SDK-level errors                                                |
| `UccError`                | Android       | `Cello.getActiveUcc` threw                       | SDK not initialized, network or serialization errors                    |
| `CampaignConfigError`     | Android       | `Cello.getCampaignConfig` threw                  | SDK not initialized, configuration not ready                            |
| `InvalidArguments`        | iOS & Android | Missing or invalid method arguments              | Required parameters not provided or have invalid values                 |

> **Tip:** Catch `PlatformException` and inspect `error.code`, `error.message`, and `error.details` for extra context.

### Common error scenarios

#### 1. Initialization exception

**Symptoms:** `InitializationError` or `InitializationException` in the catch block.

**Fix:** Validate credentials, confirm network connectivity, and ensure you selected the right environment (`production` vs `sandbox`). Check native logs for additional details.

#### 2. Methods called before initialization

**Symptoms:** `ClientUnavailable` error on Android or native console warnings.

**Fix:** Ensure `Cello.initialize` completes successfully before calling other methods like `showFab()` or `openWidget()`. Track initialization state in your app.

#### 3. Platform feature limitations

`Cello.changeLanguage`, `Cello.setThemeMode`, and `Cello.updateToken` require iOS 14+ on iOS. On older devices these methods reject with `Unavailable` error. Guard these calls with a platform/version check if needed.

### Error handling best practices

**1. Wrap initialization in try/catch:**

```dart theme={null}
import 'package:flutter/services.dart';
import 'package:cello_sdk/cello_sdk.dart';

Future<void> bootstrapCello() async {
  try {
    if (productId.trim().isEmpty || token.trim().isEmpty) {
      throw Exception('Missing credentials');
    }

    final config = await Cello.initialize(
      CelloInitializeOptions(
        productId: productId,
        token: token,
        productUserDetails: productUserDetails,
      ),
    );

    setState(() {
      celloReady = true;
    });

    print('[Cello] Initialized: ${config.rawResponse}');
  } on PlatformException catch (e) {
    print('[Cello] Initialization failed: ${e.code} - ${e.message}');

    // Show user-friendly error
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('Referrals unavailable'),
        content: Text('Please check your connection and try again.'),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: Text('OK'),
          ),
        ],
      ),
    );
  } catch (e) {
    print('[Cello] Unexpected error: $e');
  }
}
```

**2. Delay UI interactions:** Only call `Cello.showFab()` or `Cello.openWidget()` after a successful initialization. Keep a dedicated `isCelloReady` state flag in your widgets.

```dart theme={null}
ElevatedButton(
  onPressed: celloReady ? () => Cello.openWidget() : null,
  child: Text('Open Referral'),
)
```

**3. Handle token lifecycle:** Listen to `Cello.tokenEvents` and refresh tokens proactively before they expire:

```dart theme={null}
StreamSubscription<CelloTokenEvent>? _tokenSubscription;

@override
void initState() {
  super.initState();

  _tokenSubscription = Cello.tokenEvents.listen((event) {
    if (event.type == CelloTokenEventType.tokenAboutToExpire) {
      // Refresh token from your backend
      _refreshCelloToken();
    }
  });
}

@override
void dispose() {
  _tokenSubscription?.cancel();
  super.dispose();
}

Future<void> _refreshCelloToken() async {
  try {
    // Get fresh token from your API
    final newToken = await fetchFreshToken();

    // Update Cello with new token
    await Cello.updateToken(newToken);

    print('[Cello] Token refreshed successfully');
  } on PlatformException catch (e) {
    print('[Cello] Token refresh failed: ${e.code} - ${e.message}');
  }
}
```

**4. Retry on transient errors:** For recoverable failures (network timeouts, `InitializationError`), schedule a retry with exponential backoff. Limit retries to avoid looping endlessly.

**5. Log error details:** Capture error codes, messages, and relevant details in your logging/monitoring solution to help support diagnose issues quickly.


# Introduction
Source: https://docs.cello.so/sdk/mobile/introduction

Native mobile SDKs for embedding referral functionality in iOS and Android applications

<img alt="Mobile referral component interface for iOS and Android native SDKs" />

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

<CardGroup>
  <Card title="iOS SDK" icon="apple" href="/sdk/mobile/ios">
    Native Swift/Objective-C SDK for iOS apps
  </Card>

  <Card title="Android SDK" icon="android" href="/sdk/mobile/android">
    Native Kotlin/Java SDK for Android apps
  </Card>

  <Card title="React Native" icon="react" href="/sdk/mobile/react-native">
    Cross-platform SDK for React Native apps
  </Card>

  <Card title="Flutter" icon="flutter" href="/sdk/mobile/flutter">
    Cross-platform SDK for Flutter apps
  </Card>
</CardGroup>

## 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.
* **Dark mode** - Support for light and dark theme, with configurable colors per theme in the [Cello Portal](https://portal.cello.so) to match your app’s interface.

## 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:

<CardGroup>
  <Card title="Mobile Attribution Guide" icon="mobile" href="/attribution/for-mobile">
    Learn how to capture referral codes through app store installs using Branch.io or similar services
  </Card>
</CardGroup>

### 2. Track Referral Conversions

Implement signup and purchase event tracking to reward referrers:

<CardGroup>
  <Card title="Track Signups" icon="user-plus" href="/attribution/tracking-signups">
    Send signup events when users create accounts
  </Card>

  <Card title="Track Purchases" icon="credit-card" href="/attribution/tracking-purchase">
    Send purchase events for subscription or one-time payments
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Choose Your Platform">
    Select the appropriate SDK for your mobile platform
  </Step>

  <Step title="Install & Configure">
    Follow the installation guide for your chosen SDK
  </Step>

  <Step title="Set Up Attribution">
    [Configure mobile attribution](/attribution/for-mobile) to capture referral codes from app installs
  </Step>

  <Step title="Track Referral Conversion Events">
    Implement referral events for [signups](/attribution/tracking-signups) and [purchases](/attribution/tracking-purchase) to complete the referral flow
  </Step>
</Steps>

<Note>
  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.
</Note>


# 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 theme={null}
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.

<img alt="iOS Swift Package Manager configuration for Cello SDK installation" />

#### 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 theme={null}
  <key>CELLO_ENV</key>
  <string>prod</string>
  ```
* 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 theme={null}
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 theme={null}
  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 theme={null}
  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 theme={null}
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      |
| productUserDetails | Cello.productUserDetails | Product User details                                                         | No       |
| language           | string                   | Initial language of the widget                                               | No       |
| themeMode          | string                   | Initial theme mode: `"light"` or `"dark"`                                    | No       |
| completion         | callback                 | Receives success or failure with configuration or error.                     |          |

```swift theme={null}
import CelloSDK

let productUserDetails = CelloSDK.ProductUserDetails(
    firstName: "John",
    lastName: "Doe",
    fullName: "John Doe",
    email: "john.doe@example.com"
)

Cello.initialize(for: "dev.cello.so", with: token, productUserDetails: productUserDetails, language: 'de', themeMode: 'light') { 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 theme={null}
import CelloSDK
Cello.showFab()
```

### Cello.hideFab()

Hides the Floating action button or bookmark that launches the Referral Component

```swift theme={null}
import CelloSDK
Cello.hideFab()
```

### Cello.openWidget()

Opens the referral component.

```swift theme={null}
import CelloSDK
Cello.openWidget()
```

### Cello.hideWidget()

Hides the referral component.

```swift theme={null}
import CelloSDK
Cello.hideWidget()
```

### Cello.getActiveUcc()

A method to get an active `ucc` and invite link for the currently logged in user.

```swift theme={null}
import CelloSDK
let result = Cello.getActiveUcc()
```

## `getCampaignConfig()`

Returns campaign config values for the currently logged-in user.

```swift theme={null}
import CelloSDK
let result = Cello.getCampaignConfig()
```

### Returns

<ResponseField name="campaignConfig" type="object">
  The campaign config object:

  <Expandable title="properties">
    <ResponseField name="primaryCurrency" type="string">
      Primary currency code
    </ResponseField>

    <ResponseField name="revenuePercentage" type="number">
      Percentage of attributed new revenue that will be paid as a reward
    </ResponseField>

    <ResponseField name="rewardCap" type="number">
      Maximum reward that can be earned per referral
    </ResponseField>

    <ResponseField name="newSignupBonus" type="number">
      Additional reward for signups to encourage more sharing
    </ResponseField>

    <ResponseField name="newPurchaseBonus" type="number">
      Additional reward for purchases to encourage more sharing
    </ResponseField>

    <ResponseField name="newUserDiscountMonth" type="number">
      How long new users get a discount
    </ResponseField>

    <ResponseField name="newUserDiscountPercentage" type="number">
      The discount new users get
    </ResponseField>
  </Expandable>
</ResponseField>

### Cello.changeLanguage()

A method to change the language of the Referral component at runtime without re-initialising it.

```swift theme={null}
import CelloSDK
Cello.changeLanguage(to: .de)
```

### Cello.setThemeMode()

A method to change the theme mode of the Referral component at runtime without re-initialising it.

```swift theme={null}
import CelloSDK
Cello.setThemeMode(to: "dark")
```

**Parameters:**

* `themeMode` (*String*): The theme mode to set. Valid values are `"light"` or `"dark"`.

**Availability:** iOS 14.0+

### Cello.shutdown()

Shuts down connection to Cello and unmounts the component

```swift theme={null}
import CelloSDK
Cello.shutdown()
```

## Error Handling

When using CelloSDK, you may encounter errors during initialization or other operations. Errors are returned in the format:

```
The operation couldn't be completed. (CelloSDK.APIError error N.)
```

Where `N` is a numeric error code (0-6) that identifies the specific error type.

### Error Codes Reference

#### Error 0: Invalid URL

**What it means:** The SDK attempted to create a request with an invalid or malformed URL.

**Common causes:**

* Missing or empty product ID
* Malformed base URL in SDK configuration
* Invalid characters in URL parameters

***

#### Error 1: Unauthorized

**What it means:** The authentication token is invalid, expired, or the user is not authorized to access the widget.

**Common causes:**

* Expired JWT token
* Invalid token signature
* Token generated for a different product ID
* User permissions revoked
* Initializing for wrong environment

***

#### Error 2: Request Failed

**What it means:** The network request failed due to connectivity issues or server errors.

**Error code meanings:**

* `-1`: Network connectivity error (no internet, timeout)
* `400-499`: Client errors (bad request, not found)
* `500-599`: Server errors

**Common causes:**

* No internet connection
* Slow or unstable network
* Server maintenance or downtime
* Firewall or proxy blocking requests

***

#### Error 3: Invalid Response Type

**What it means:** The server response was not in the expected HTTP format.

**Common causes:**

* Network proxy modifying responses
* Server misconfiguration
* Non-HTTP protocol response

***

#### Error 4: No Data Received

**What it means:** The server returned a successful response (HTTP 200-299) but with no data in the response body.

**Common causes:**

* Server returning empty response
* Network issue truncating the response
* Incorrect API endpoint or version

***

#### Error 5: JSON Parsing Error

**What it means:** The SDK received data from the server but couldn't parse it as valid JSON.

**Common causes:**

* Server returned HTML error page instead of JSON
* Malformed or incomplete response
* API version mismatch

***

#### Error 6: Invalid State

**What it means:** The SDK is in an invalid state or required parameters are missing.

**Specific messages:**

* "Product ID cannot be empty"
* "Token cannot be empty"
* "Product ID not set"
* "Configuration not initialized"

**Common causes:**

* Empty product ID or token during initialization
* Calling SDK methods before initialization completes

***

### Initialization State Errors

If you call SDK methods before initialization, you'll see console warnings:

* `"Error: showFab() called before initialization."`
* `"Error: hideFab() called before initialization."`
* `"Error: openWidget() called before initialization."`
* `"Error: hideWidget() called before initialization."`
* `"Error: shutdown() called before initialization."`
* `"Error: getActiveUcc() called before initialization."`
* `"Error: getCampaignConfig() called before initialization."`
* `"Error: changeLanguage() called before initialization."`
* `"Error: setThemeMode() called before initialization."`

**Solution:** Always wait for initialization to complete before calling other SDK methods.

***

### Error Handling Best Practices

**1. Validate parameters before initialization:**

```swift theme={null}
guard !productId.trimmingCharacters(in: .whitespaces).isEmpty else {
    print("Error: Product ID is required")
    return
}

guard !token.trimmingCharacters(in: .whitespaces).isEmpty else {
    print("Error: Token is required")
    return
}

Cello.initialize(for: productId, with: token) { result in
    // Handle result
}
```

**2. Track initialization state:**

```swift theme={null}
class CelloManager {
    private var isInitialized = false

    func initialize(productId: String, token: String) {
        Cello.initialize(for: productId, with: token) { [weak self] result in
            if case .success = result {
                self?.isInitialized = true
            }
        }
    }

    func showReferral() {
        guard isInitialized else {
            print("SDK not initialized yet")
            return
        }
        Cello.openWidget()
    }
}
```


# 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 theme={null}
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 theme={null}
react-native link @getcello/cello-react-native
```

#### React Native v0.59 (Manual Linking)

**`android/settings.gradle`**

```groovy theme={null}
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 theme={null}
dependencies {
  implementation project(':cello-react-native')
}
```

### Android Initialization

Update your `MainApplication.java`:

```java theme={null}
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 theme={null}
<uses-permission android:name="android.permission.INTERNET" />
```

### 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 theme={null}
#import "AppDelegate.h"
#import <React/RCTBridge.h>
#import <React/RCTBundleURLProvider.h>
#import <React/RCTRootView.h>
// ...
#import <CelloReactNative.h> // <-- 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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
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 theme={null}
import Cello from '@getcello/cello-react-native';

const MyButton = () => {
  return <Button onPress={() => Cello.openWidget()}>Open Referral</Button>;
};
```

## React Native API

### `Cello.initialize(InitializeOptions): Promise<Configuration>`

Initializes the Cello referral component.

### InitializeOptions

| Property           | Type               | Required | Description                               |
| ------------------ | ------------------ | -------- | ----------------------------------------- |
| productId          | string             | yes      | Your product ID from Cello Portal         |
| token              | string             | yes      | User authentication token                 |
| productUserDetails | ProductUserDetails | no       | User details object (see below)           |
| language           | string             | no       | Initial language of the widget            |
| themeMode          | string             | no       | Initial theme mode: `"light"` or `"dark"` |

### ProductUserDetails

Optional object with user information:

| Property  | Type   | Description          |
| --------- | ------ | -------------------- |
| firstName | string | User's first name    |
| lastName  | string | User's last name     |
| fullName  | string | User's full name     |
| email     | string | User's email address |

```ts theme={null}
Cello.initialize({
  productId: 'your-product-id',
  token: 'your-token',
  productUserDetails: {
    firstName: 'John',
    lastName: 'Doe',
    fullName: 'John Doe',
    email: 'john.doe@example.com',
  },
  language: 'de',
  themeMode: 'light',
});
```

### `Cello.showFab(): void`

Shows the default Cello button that launches the Referral Component

```ts theme={null}
Cello.showFab();
```

### `Cello.hideFab(): void`

Hides the default Cello button that launches the Referral Component

```ts theme={null}
Cello.hideFab();
```

### `Cello.openWidget(): void`

Opens the referral component.

```ts theme={null}
Cello.openWidget();
```

### `Cello.hideWidget(): void`

Hides the referral component.

```ts theme={null}
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 theme={null}
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 theme={null}
Cello.changeLanguage('de');
```

### `Cello.setThemeMode(themeMode: string): void`

A method to change the theme mode of the Referral component at runtime without re-initialising it.

```ts theme={null}
Cello.setThemeMode('dark');
```

**Parameters:**

* `themeMode` (*string*): The theme mode to set. Valid values are `"light"` or `"dark"`.

### `Cello.shutdown(): void`

Shuts down connection to Cello and unmounts the component

```ts theme={null}
Cello.shutdown();
```

***

## Error Handling

### Promise rejection codes

| Code                      | Platform(s)   | Trigger                                          | Typical causes                                                          |
| ------------------------- | ------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
| `InitializationError`     | iOS & Android | `Cello.initialize` completes with native failure | Invalid/empty product ID or token, network issues, bad environment      |
| `InitializationException` | Android       | Unexpected exception inside `Cello.initialize`   | Activity finishing, SDK not linked correctly, runtime crash             |
| `ActivityError`           | Android       | `Cello.initialize` without an active Activity    | Initialization triggered too early (e.g. before React root ready)       |
| `TokenUpdateError`        | iOS           | `Cello.updateToken` failure                      | Token expired/invalid, network errors                                   |
| `LanguageChangeError`     | iOS           | `Cello.changeLanguage` failure                   | Unsupported language code, network errors                               |
| `ThemeModeChangeError`    | iOS           | `Cello.setThemeMode` failure                     | Invalid theme mode value, network errors                                |
| `UnavailableError`        | iOS           | Feature requires iOS 14+                         | Device running \< iOS 14 when calling token, language, or theme updates |
| `NO_ACTIVE_UCC`           | iOS           | `Cello.getActiveUcc` with no active referral     | User has not generated an invite yet                                    |
| `UCC_ERROR`               | Android       | `Cello.getActiveUcc` threw                       | SDK not initialized, network or serialization errors                    |
| `CAMPAIGN_CONFIG_ERROR`   | Android       | `Cello.getCampaignConfig` threw                  | SDK not initialized, configuration not ready                            |
| `LINKING_ERROR`           | JavaScript    | Module not linked                                | Pod install missing, app not rebuilt, using Expo Go                     |

> **Tip:** The React Native bridge rejects promises with the objects above. Inspect `error.code`, `error.message`, and (on iOS) `error.nativeStackIOS` for extra context.

### Common error scenarios

#### 1. Initialization promise rejected

**Symptoms:** `InitializationError` or `InitializationException` in the catch block.

**Fix:** Validate credentials, confirm network connectivity, and ensure you selected the right environment (`prod` vs `sandbox`). Compare native logs with the [iOS](./ios.md#error-handling) and [Android](./android.md#error-handling) error references for detailed native codes.

#### 2. Module not linked (`LINKING_ERROR`)

**Symptoms:** Error thrown immediately when importing `@getcello/cello-react-native`.

**Fix:** Run `pod install` inside `ios`, rebuild the app, and ensure you are not running inside Expo Go. For older RN versions (`0.59`), double-check manual linking steps.

#### 3. UI calls before initialization finishes

Calling `Cello.showFab()`, `Cello.openWidget()`, or similar before the SDK is ready triggers native console warnings such as `"Error: showFab() called before initialization."`. Track initialization state in JavaScript and gate UI interactions until `Cello.initialize` resolves.

#### 4. Platform feature limitations

`Cello.changeLanguage` and `Cello.setThemeMode` require iOS 14+. On older devices the bridge rejects with `UnavailableError`. Guard these calls with a platform/version check.

### Error handling best practices

**`1. Wrap initialization in try/catch:`**

```ts theme={null}
import { Alert } from 'react-native';
import Cello from '@getcello/cello-react-native';

async function bootstrapCello() {
  try {
    if (!productId.trim() || !token.trim()) {
      throw new Error('Missing credentials');
    }

    const config = await Cello.initialize({
      productId,
      token,
      productUserDetails,
    });

    setCelloReady(true);
    console.log('[Cello] Initialized', config);
  } catch (error: any) {
    console.warn('[Cello] Initialization failed', error);
    Alert.alert(
      'Referrals unavailable',
      'Please check your connection and try again.'
    );
  }
}
```

**2. Delay UI interactions:** Only call `Cello.showFab()` or `Cello.openWidget()` after a successful initialization. Keep a dedicated `isCelloReady` state flag in your components.

**3. Retry on transient errors:** For recoverable failures (network timeouts, `InitializationError`), schedule a retry with exponential or linear backoff. Limit retries to avoid looping endlessly.

**4. Log error details:** Capture `error.code`, `error.message`, and relevant native stack traces in your logging/monitoring solution to help support diagnose issues quickly.