> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cello.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Purchases

> Learn how to track purchase events with Cello

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.

> [!TIP]
>
> After sending purchase events, ask your coding tool for a Cello [integration health check](https://docs.cello.so/mcp/developers/integration-status.md) to confirm Purchases tracking is **Connected**. For per-event detail and to troubleshoot any field validation errors, open [Developers → Events](https://app.cello.so/developers/events) in the Cello Portal.

# Prerequisites

Before you can send Cello purchase events, make sure you are already:

* [Capturing referral code on your landing page](https://docs.cello.so/attribution/for-web.md)
* [Tracking signups](https://docs.cello.so/attribution/tracking-signups.md)

> [!WARNING]
>
> **Attribution based on organization level**
>
> If 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`

> [!NOTE]
>
> If you are providing discounts to new users, they need to be [applied at the point of creating a subscription](https://docs.cello.so/attribution/apply-discounts.md) in your subscription platform

# Track purchase events with Webhooks

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

> [card] [Stripe Webhook](https://docs.cello.so/integrations/webhooks/stripe-webhook.md)
>
> Send events using Stripe Webhook

> [card] [Chargebee Webhook](https://docs.cello.so/integrations/webhooks/chargebee-webhook.md)
>
> 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.

```bash theme={null}
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](https://docs.cello.so/sdk/client-side/attribution-js-introduction.md) `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](https://docs.cello.so/referral-component/introduction.md), 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](https://docs.cello.so/api-reference/generic-events/send-event.md).

## `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.

```bash theme={null}
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](https://docs.cello.so/sdk/client-side/attribution-js-introduction.md) `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](https://docs.cello.so/referral-component/introduction.md), 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](https://docs.cello.so/api-reference/generic-events/send-event.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.