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.
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
Track purchase events with Webhooks
Depending on which payment gateway you’re using, we offer webhooks for the following:
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"
}
}
}
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, monthly, quarterly, yearly, biennial, triennial, lifetime, bi-weekly, semi-annual |
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.
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"
}
}
}
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. 
