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, check Integration Status to confirm Purchases tracking is Connected. For per-event detail and to troubleshoot any field validation errors, open the Event Feed in the Cello Portal.

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:

Property	Required	Description
`ucc`	yes	A 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
`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, 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.

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

Property	Required	Description
`ucc`	yes	A 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
`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, 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.

Getting Started

Integrate Cello with AI

Referral Component

Referral Conversion

Integrations

Track Purchases

Prerequisites

Track purchase events with Webhooks

Stripe Webhook

Chargebee Webhook

Track purchase events with Cello API

`invoice-paid`

`charge-refunded`

​Prerequisites

​Track purchase events with Webhooks

Stripe Webhook

Chargebee Webhook

​Track purchase events with Cello API

​invoice-paid

​charge-refunded

Prerequisites

Track purchase events with Webhooks

Track purchase events with Cello API

`invoice-paid`

`charge-refunded`