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

> [tab] 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.

> [tab] 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](https://docs.tolt.com/tracking/script.md).

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

**3. Pass the referral to Paddle**

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

> [tab] 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.

> [tab] 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.

> [tab] 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.

> [tab] 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

> [accordion] 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.

> [accordion] 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](https://docs.tolt.com/guides/refunds.md).


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