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.

Prerequisites

Before you can send Cello signup events, you need to make sure that you are able to capture the referral code uccduring signup or demo booking:

When users signup in your web app
When users signup in your mobile app
When users book a demo using Hubspot or Typeform forms or scheduling

Attribution based on organization levelIf 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

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.

Options 1: Stripe - I create Stripe customer at signup

Use this option if your payment gateway is Stripe and you create a Stripe customer at signup

To track a signup, you can pass the following metadata to Stripe Customer Object on customer creation.

cello_ucc - ucc, a referral code identifying the referrer. You can retrieve this code using attribution script 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, 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:

const stripe = require('stripe')('sk_test_51KiCYYCSMQAUBF...');

const customer = await stripe.customers.create({
  description: 'New Stripe Customer',
    metadata: {
		cello_ucc: "hdz7afhs7",
		new_user_id: "xcsdad", // product user id of the new user
        new_user_organization_id: "123456" // organization id of the new user
			}
});

Now that the customer is created in Stripe with Cello metadata, a customer.created event will be sent with Stripe Webhook, which we will count as a signup event in Cello.

Option 2: Chargebee - I create Chargebee customer at signup

Use this option if your payment gateway is Chargebee and you create a Chargebee customer at signup

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

You can also choose to use Chargebee custom fields (CF_) to add referral data to the event. Learn more about custom fields in the Chargebee documentation

cello_ucc - ucc, a referral code identifying the referrer. You can retrieve this code using attribution script 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, 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:

var chargebee = require("chargebee");

chargebee.configure({site : "getmoonly-v3-test", api_key : "test_jqXGuQLkBHUSR2PM0qgUV21W1VqSFJIU"});
chargebee.customer.create({
   first_name : "Bob", 
   last_name : "Bobsky", 
   //...
   // other customer fields
   //...
   meta_data: {
		cello_ucc: "hdz7afhs7",
		new_user_id: "xcsdad", // product user id of the new user
        new_user_organization_id: "123456" // organization id of the new user
			}
//   ..
// })

Now that the customer is created in Chargebee with Cello metadata, a Customer Created event will be sent with Chargebee Webhook, which we will count as a signup event in Cello.

Option 3: Use Cello API POST /events API endpoint

Use this option for all other use cases. For example:

You use Stripe or Chargebee, but customer is created in the payment gateway at purchase.
Your payment gateway is Paddle, Recurly or other, including in-house built payment gateways

Send a new-signup event to the Cello API with the following values in the payload:

ucc - ucc, a referral code identifying the referrer. You can retrieve this code using attribution script getUcc () method, you have installed as a prerequisite to this guide.
newUserId - a unique ID in your system, identifying the new user who just signed up. Can also be organization ID, if your referrers can refer organizations and you want to reward them for organization account expansion.
user.id - unique ID of the new user (not the organization, if you are rewarding on organization level). This should be the same ID (productUserId) you will use to boot the Referral component, when this user logs into your app
user.email - new user email
user.name - new user name
user.organizationId(optional) - add organization ID, if your referrers can refer an organization and you want to reward them for organization account expansion.

Here is an example of the POST /events call to send a new-signup event:

POST https://api.cello.so/events

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

Option 4: Send a demo-attended event with Cello API for sales-led model

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

Send a demo-attended event to the Cello API with the following values in the payload:

ucc - ucc, a referral code identifying the referrer. You can retrieve this code using attribution script getUcc () method, you have installed as a prerequisite to this guide.
productUserId - a unique ID in your system, identifying the new user who just signed up. Can also be organization ID, if your referrers can refer organizations and you want to reward them for organization account expansion.
user.id - unique ID of the new user (not the organization, if you are rewarding on organization level). This should be the same ID (productUserId) you will use to boot the Referral component, when this user logs into your app
user.email - new user email
user.name - new user name
user.organizationId(optional) - add organization ID, if your referrers can refer an organization and you want to reward them for organization account expansion.

Here is an example of the POST /events call to send a new-signup event:

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"
		}
}
}

Getting Started

Referral Component

Referral Conversion

Integrations

Track Signups

Prerequisites

Getting Started

Referral Component

Referral Conversion

Integrations

​Prerequisites

​Tracking signup events

Prerequisites

Tracking signup events