Skip to main content
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.
After sending purchase events, use the Event Feed to verify they are arriving correctly and all required fields pass validation. See the Event Feed guide for details.

​
Prerequisites

Before you can send Cello purchase events, make sure you are already:
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
If you are providing discounts to new users, they need to be applied at the point of creating a subscription in your subscription platform

​
Track purchase events with Webhooks

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

Stripe Webhook

Send events using Stripe Webhook

Chargebee Webhook

Send events using Chargebee Webhook

​
Track purchase events with Cello API

If you’re not using any of the gateways listed above, you can also send purchase events using Cello API POST /events API endpoint. Here are the 2 events you will need to send:

​
invoice-paid

This event is sent every time a transaction based on the provided subscription is successful or a new user buys a one-time plan, a license or something similar. 
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:
PropertyRequiredDescription
uccyesA referral code (ucc) identifying the referrer. You can retrieve this code using attribution script getUcc () method, you have installed as a prerequisite to this guide
newUserIdyesA 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
priceyesAmount on the invoice
currencyyesCurrency of the amount
newUser.idyesA 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.emailyesNew user email
newUser.organizationIdnoOrganization ID. Add this field if your referrers can refer an organization and you want to reward them for organization account expansion
event.triggeryesinvoice-paid
event.timestampyesEvent timestamp in ISO8601 format
subscription.invoiceIdyesID of the invoice that was paid or refunded
subscription.intervalyesInterval of the payment. Available options: one-time, monthly, quarterly, yearly, biennial, triennial, lifetime, bi-weekly, semi-annual
subscription.productKeyyesName of the product or plan purchased
Full API referrence for POST /events API endpoint can be found here.

​
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. 
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:
PropertyRequiredDescription
uccyesA referral code (ucc) identifying the referrer. You can retrieve this code using attribution script getUcc () method, you have installed as a prerequisite to this guide
newUserIdyesA 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
priceyesAmount refunded
currencyyesCurrency of the amount
newUser.idyesA 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.emailyesNew user email
newUser.organizationIdnoOrganization ID. Add this field if your referrers can refer an organization and you want to reward them for organization account expansion
event.triggeryescharge-refunded
event.timestampyesEvent timestamp in ISO8601 format
subscription.invoiceIdyesID of the invoice that was paid or refunded
Full API referrence for POST /events API endpoint can be found here.