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

# Chargebee integration

> Connect Chargebee and turn referred payments, renewals and refunds into commissions automatically.

Browsertolt.js + Chargebee.jsChargebeebillingToltattribution*1*?ref=sam*2*cf\_tolt\_referral: clk\_3nVb…*3*payment\_succeeded*4*comm\_2nV8… 1470

## Set up

**1. Connect Chargebee**

In the dashboard, go to **Settings → Integrations → Chargebee**. Enter your Chargebee site (`acme.chargebee.com`) and a Chargebee API key, then save.

![The Chargebee integration page in Tolt](https://mintcdn.com/tolt-29/IdZ6_r2VYMOh5a6x/images/dashboard/chargebee-integration-light.webp?fit=max\&auto=format\&n=IdZ6_r2VYMOh5a6x\&q=85\&s=fdcdbbc7219a8e643f09d0c2a67ebad0)

**2. Add tolt.js**

Add the script to every page of your site and app. See [Install tolt.js](/tracking/script).

```html HTML theme={"system"}
<script
  async
  src="https://cdn.tolt.io/v2/tolt.js"
  data-tolt="YOUR_PUBLIC_ORG_KEY"
></script>
```

**3. Pass the referral to Chargebee**

Store the referral on the Chargebee customer. Pick the path that matches your checkout.

**Drop-in checkout**

In Chargebee, go to **Settings → Configure Chargebee → Custom Fields** and add a customer field with the API name `cf_tolt_referral`. Then set it on the cart when the buyer starts checkout:

```js Chargebee.js theme={"system"}
async function startCheckout() {
  // Waits for the recorded click. Undefined when the
  // visitor wasn't referred.
  const referral = (await window.tolt?.ready())?.click_id;
  if (referral) {
    const cart = Chargebee.getInstance().getCart();
    cart.setCustomer({ cf_tolt_referral: referral });
  }
  // ...then open the checkout
}
```

**API**

Creating customers from your server? Send `window.tolt_referral` from the browser and add it to `meta_data`:

```ts TypeScript theme={"system"}
import Chargebee from "chargebee";

const chargebee = new Chargebee({
  site: "acme",
  apiKey: process.env.CHARGEBEE_API_KEY!,
});

const { customer } = await chargebee.customer.create({
  email: "jane@example.com",
  meta_data: { tolt_referral: referral },
});
```

```bash cURL theme={"system"}
curl https://acme.chargebee.com/api/v2/customers \
  -u "$CHARGEBEE_API_KEY:" \
  -d email="jane@example.com" \
  --data-urlencode 'meta_data={"tolt_referral":"REFERRAL_ID"}'
```

**4. Add the webhook**

Copy the webhook URL from the Chargebee integration page in the Tolt dashboard. In Chargebee, go to **Settings → Configure Chargebee → Webhooks → Add Webhook**, paste it and select these events:

Subscription Created, Subscription Started, Subscription Cancelled, Subscription Deleted, Payment Succeeded, Payment Refunded, Coupon Deleted

Also turn on **Exclude card information from webhook call**.

**5. Test it**

Open a partner link like `acme.com/?ref=sam`, complete a checkout, then find the customer under **Customers** and the commission under **Commissions** in the dashboard.

> [!WARNING]
>
> With Chargebee connected, Tolt records payments for you. Don't also call `POST /v2/transactions` for the same payments, or commissions double count.

## Details

> **Excluding tax**
>
> Turn on **Exclude Chargebee tax in the tracking amount** on the Chargebee integration page. Commissions then use the amount before tax. It's off by default.

> **Refunds and cancellations**
>
> A refunded payment zeroes unpaid commissions or creates a negative one if already paid. A cancelled or deleted subscription marks the customer canceled. See [Refunds](/guides/refunds).


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