Skip to main content
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:
Attribution based on organization levelIf the buying persona is the organization and you want to attribute purchases at the organization level, always provide the ID of the organization in the parameter payload.newUserId

​
Tracking signup events

For a SaaS application signup flow, you will track a signup event or equivalent. Depending on how you create a new user and which payment gateway you are using, you can choose from the following options to send Cello signup events.

​
Option 1: Using Stripe - I create Stripe Customer at Signup

Use this option if your payment gateway is Stripe and you create a Stripe customer at signup
To track a signup, you can pass the following metadata to Stripe Customer Object 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: Using Chargebee - I create Chargebee customer at signup

Use this option if your payment gateway is Chargebee and you create a Chargebee customer at signup
You can pass the following metadata to Chargebee on customer creation.
You can also choose to use Chargebee custom fields (CF_) to add referral data to the event. Learn more about custom fields in the Chargebee documentation
  • 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: Using Cello API POST /events API endpoint

Use this option for all other use cases. For example:
  • You use Stripe or Chargebee, but customer is created in the payment gateway at purchase.
  • Your payment gateway is Paddle, Recurly or other, including in-house built payment gateways
Send a new-signup event to the Cello API with the following values in the payload:
  • ucc - ucc, a referral code identifying the referrer. You can retrieve this code using attribution script 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, 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: 
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

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.
  • 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, 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: 
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"
		}
}
}
⌘I