> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cello.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Track 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"
		}
}
}
```