> ## 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, check [Integration Status](/guides/support/portal/integration-status) to confirm Purchases tracking is **Connected**. For per-event detail and to troubleshoot any field validation errors, open the [Event Feed](https://portal.cello.so/integrations/events-feed) in the Cello Portal.
</Tip>

# 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)
* [Tracking signups](https://docs.cello.so/attribution/tracking-signups)

<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`
</Warning>

<Note>
  If you are providing discounts to new users, they need to be [applied at the point of creating a subscription](/attribution/apply-discounts) in your subscription platform
</Note>

# Track purchase events with Webhooks

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

<CardGroup cols={2}>
  <Card
    title="Stripe Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<g clipPath="url(https://mintlify.s3.us-west-1.amazonaws.com/cello/attribution#clip0_19722_44991)">
<path d="M18 36C27.9411 36 36 27.9411 36 18C36 8.05888 27.9411 0 18 0C8.05888 0 0 8.05888 0 18C0 27.9411 8.05888 36 18 36Z" fill="#635BFF"/>
<path fillRule="evenodd" clipRule="evenodd" d="M16.596 13.995C16.596 13.149 17.289 12.816 18.441 12.816C20.097 12.816 22.185 13.32 23.841 14.211V9.09898C22.032 8.37898 20.25 8.09998 18.45 8.09998C14.031 8.09998 11.097 10.404 11.097 14.256C11.097 20.259 19.368 19.305 19.368 21.897C19.368 22.896 18.495 23.22 17.28 23.22C15.471 23.22 13.167 22.482 11.34 21.483V26.658C13.365 27.531 15.408 27.9 17.28 27.9C21.807 27.9 24.921 25.659 24.921 21.762C24.885 15.282 16.596 16.434 16.596 13.995Z" fill="white"/>
</g>
<defs>
<clipPath id="clip0_19722_44991">
<rect width="36" height="36" fill="white"/>
</clipPath>
</defs>
</svg>}
    href="/integrations/webhooks/stripe-webhook"
  >
    Send events using Stripe Webhook
  </Card>

  <Card
    title="Chargebee Webhook"
    icon={<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12.1464 18.0024L35.9265 12.3313V0H23.5953L12.1464 18.0024Z" fill="#FF3300"/>
<path d="M0.36 17.7853C0.36 19.2605 0.539827 20.6924 0.879691 22.0664L12.1451 18.0017L0.786251 13.9024C0.509734 15.1512 0.36 16.4499 0.36 17.7819V17.7853Z" fill="#FF3300"/>
<path d="M4.54902 6.32317L12.1436 18.0031L15.6415 0.177188C11.2091 0.799913 7.3026 3.05771 4.54902 6.32317V6.32317Z" fill="#FF3300"/>
<path d="M12.1464 18.0008L35.9265 23.6686V35.9998H23.5953L12.1464 18.0008Z" fill="#FF3300"/>
<path d="M4.54902 29.6798L12.1436 17.9978L15.6415 35.8204C11.2091 35.1977 7.3026 32.9399 4.54902 29.6744L4.54902 29.6798Z" fill="#FF3300"/>
</svg>}
    href="/integrations/webhooks/chargebee-webhook"
  >
    Send events using Chargebee Webhook
  </Card>
</CardGroup>

# 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](/sdk/client-side/attribution-js-introduction) `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](/referral-component/introduction), 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](/api-reference/generic-events/send-event).

## `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](/sdk/client-side/attribution-js-introduction) `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](/referral-component/introduction), 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](/api-reference/generic-events/send-event).