Connect Paddle
You create the notification destination in your own Paddle dashboard and paste its secret into Klibon. Klibon also needs a read-only Paddle key, used for two things: listing your products, so each can pay its own rate, and reading a paying customer's email, which Paddle leaves off its notifications and which matches a signup you reported with Klibon.signup(). Give it Products, Prices and Customers read access. A program activates only once one of its products pays, so the key is part of setup — you can save the secret first and add the key afterwards.
Create the destination
- In Paddle, go to Developer tools → Notifications → New destination.
- Paste the URL shown on your program's Setup page: destination
https://klibon.com/api/webhooks/paddle/<program_id> - Subscribe to the three events below, and no others.
- Copy the secret — it starts with
pdl_ntfset_— and paste it into Klibon.
Getting the referral code to Paddle
Paddle's checkout takes no query parameters, so the code travels as custom data instead. The good news is that Paddle then copies it onto the subscription and onto every future transaction, so renewals need nothing further from you.
Checkout buttons
If your buttons carry data-items, the tracking script fills in data-custom-data for you when you have not set one yourself — and data-discount-code when the visitor has a coupon to use (Coupon codes). Paddle names a discount on its webhooks by dsc_… id only, so register the id with the code.
<a
href="#"
data-items='[{"priceId": "pri_123", "quantity": 1}]'
data-custom-data='{"klibon": "REPLACE_ME"}'
>
Buy
</a>Opening the checkout yourself
// The referral code the script is holding for this visitor, or null.
const code = window.Klibon?.referral() ?? null
Paddle.Checkout.open({
items: [{ priceId: 'pri_123', quantity: 1 }],
// Paddle copies this onto the subscription it creates, and onto every
// transaction after — so renewals arrive attributed with no extra work.
customData: { klibon: code ?? '' }
})What each event becomes
| Paddle event | In Klibon |
|---|---|
transaction.completed | A sale, or a renewal when the transaction came from a recurring subscription. |
adjustment.created | A refund or chargeback, once Paddle has approved it. |
adjustment.updated | The same refund, when approval came later than creation. |
A transaction whose origin is subscription_update is ignored: that is a proration for a plan change, and counting it would burn a cycle of your program's commission duration.
Usage-based pricing works when usage is billed as a one-time charge. Added to the next renewal, it is part of that renewal's transaction; billed straight away, it arrives as a subscription_charge transaction. Either way the affiliate earns on what was actually billed. Usage billed as a quantity change charged immediately is a proration, and is ignored like one — bill it on the next billing period instead.
Klibon connects to Paddle Billing. Paddle Classic, and its subscription modifiers, are not supported.
A refund adjustment is born pending_approval and Klibon waits for it. Nothing is reversed until Paddle approves the refund, so one that is ultimately rejected never touches the commission.
What the commission is calculated on
Paddle is a merchant of record: the total your customer pays includes the tax Paddle collects and remits, which never reaches you. Klibon commissions the amount before tax, so an affiliate is paid a share of your revenue rather than a share of somebody's VAT.
Sandbox
Paddle's notifications carry no marker saying which environment they came from, so Klibon cannot tell a sandbox payment from a real one. Point a sandbox destination at a program that is still a draft: tracking works, events arrive, and nothing is owed to anyone. Wire the live destination when you activate.
Troubleshooting
Signature failures
The secret is per destination and changes if you delete and recreate one. Klibon shows "Error" on your Setup page with the reason when a signature does not verify.
Events arrive but nothing is attributed
Open the event in the Events tab. Not referred means the transaction carried no custom_data.klibon. Check the value is present on the transaction in Paddle's own dashboard — if it is missing there, it never left your page.