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

# Paddle integration

> Connect Paddle Billing or Paddle Classic and turn referred payments into commissions automatically.

Browsertolt.js + Paddle.jsPaddlebillingToltattribution*1*?ref=sam*2*customData.tolt\_referral*3*transaction.completed*4*comm\_2nV8… 1470

## Set up

**1. Connect Paddle**

In the dashboard, go to **Settings → Integrations → Paddle** and pick your Paddle version.

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

**Paddle Billing**

In Paddle, open **Developer Tools → Authentication** and create a server-side API key (not a client-side token) with these permissions:

ReadAdjustments, Customers, Products, Subscriptions, Transactions, NotificationsRead & WriteDiscounts

Paste the key into Tolt.

**Paddle Classic**

In Paddle, open **Developer Tools → Authentication**. Copy your **Public key**, **Vendor ID** and **API key** into Tolt.

**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 Paddle**

Add `tolt_referral` to `customData` when you open the checkout.

**Paddle Billing**

```js Paddle.js theme={"system"}
Paddle.Checkout.open({
  items: [{ priceId: "pri_01hac19sfx1vn50r342majkg43", quantity: 1 }],
  customer: { email: "jane@example.com" },
  customData: { tolt_referral: window.tolt_referral },
});
```

Creating transactions from your server instead? Set `custom_data: { "tolt_referral": "<referral>" }` on the transaction.

**Paddle Classic**

```js Paddle.js theme={"system"}
Paddle.Checkout.open({
  product: 12345,
  email: "jane@example.com",
  customData: { tolt_referral: window.tolt_referral },
});
```

`passthrough: JSON.stringify({ tolt_referral: window.tolt_referral })` works too.

**4. Add the webhook**

Copy the webhook URL from the Paddle integration page in the Tolt dashboard and add it in Paddle.

**Paddle Billing**

In Paddle, go to **Developer Tools → Notifications** and add a destination with that URL. Select these events:

`subscription.created`, `subscription.canceled`, `transaction.completed`, `adjustment.created`, `adjustment.updated`, `discount.updated`

Then copy the destination's **secret key** into the **Webhook secret** field in Tolt and save.

**Paddle Classic**

In Paddle, go to **Developer Tools → Events** and add the URL. Select these alerts:

Subscription Created, Subscription Updated, Subscription Cancelled, Subscription Payment Success, Subscription Payment Refunded, Payment Succeeded, Payment Refunded

**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 Paddle connected, Tolt records payments for you. Don't also call `POST /v2/transactions` for the same payments, or commissions double count.

## Details

> **Excluding fees and tax**
>
> The Paddle integration page has two switches: **Exclude Paddle fee** and **Exclude Paddle tax** from the tracked amount. Both are off by default.

> **Refunds**
>
> Paddle Billing refunds and chargebacks arrive as adjustments, Paddle Classic refunds as refund alerts. Unpaid commissions are zeroed and paid ones get a negative commission. See [Refunds](/guides/refunds).


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