Connect Polar
You create the endpoint in your own Polar dashboard and paste the secret into Klibon. Klibon also needs an organization access token with products:read only, used for one thing: listing your products, so each can pay its own rate. A program activates only once one of them has its own commission rate, so the token is part of setup — you can save the secret first and add the token afterwards.
Create the endpoint
- In Polar, go to Settings → Webhooks → Add endpoint.
- Paste the URL shown on your program's Setup page: endpoint
https://klibon.com/api/webhooks/polar/<program_id> - Choose the Raw format, and subscribe to the two events below.
- Copy the secret Polar shows you, and paste it into Klibon.
Polar changed how webhook secrets are signed in September 2026. Klibon accepts both schemes without being told which one your secret belongs to, so an endpoint created before the change and one created after both work.
Getting the referral code to Polar
Checkout links
Polar checkout links accept reference_id as a query parameter, and copy it into the session's metadata, which propagates to the order. The tracking script adds it for you: any <a> on your page pointing at a Polar checkout link is decorated on the way out.
https://buy.polar.sh/polar_cl_abc123?reference_id=<code> A value you set yourself is never overwritten. If you already use reference_id for something, pass the code as metadata instead.
Your own checkout session
Read the code in the browser with window.Klibon.referral(), send it with your checkout request (Install the tracking script shows both halves), and put it in the metadata:
// The code your page sent with the checkout request: window.Klibon.referral(),
// read in the browser. It came from the browser, so keep it only if it has the
// shape of a Klibon code: 1 to 64 letters, digits, dashes or underscores.
const referral = req.body.referral
const code = typeof referral === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(referral)
? referral
: undefined
const checkout = await polar.checkouts.create({
products: ['prod_123'],
successUrl: 'https://example.com/thanks',
// Propagates to the order and the subscription, so renewals stay attributed too.
metadata: code ? { klibon: code } : {}
})What each event becomes
| Polar event | In Klibon |
|---|---|
order.paid | A sale on a purchase or a first subscription order, a renewal on every cycle after. |
refund.created | A refund, prorated against the commission it reverses. |
Klibon ignores order.paid with a billing reason of subscription_update. That is a mid-period plan change rather than a new payment, and counting it would burn a cycle of your program's commission duration.
order.refunded is ignored too: it restates what refund.created already reported, and acting on both would reverse a commission twice.
What the commission is calculated on
Polar is a merchant of record: the total your customer pays includes the tax Polar collects and remits, which never reaches you. Klibon commissions the net amount — after discounts, before tax — so an affiliate is paid a share of your revenue rather than a share of somebody's VAT.
Troubleshooting
No events are arriving
Polar disables an endpoint after ten consecutive failures, and treats a redirect as a failure. Check the endpoint is still enabled, and that the URL matches your Setup page exactly.
Events arrive but nothing is attributed
Open the event in the Events tab. Not referred means no code came through. Click your own tracking link, land on your site, and check window.Klibon.referral() returns a code before you reach the checkout — if it does but the order does not carry it, the link was probably opened in a way that skipped the decoration, such as a window.open from your own JavaScript.