Connect Paddle

Connecting Paddle sends every sale, renewal and refund to Clakta as it happens. That is the first half of measuring Paddle performance; the second is carrying the visitor's session into the checkout, so each sale is credited to the traffic that produced it.

Both halves are covered below, and the second one is automatic if you already install the tracking script.

Connect

1. Go to Project settings → Sales platforms.
2. Choose Paddle, name the connection, and click Create connection. Clakta generates a webhook URL — copy it.
3. In Paddle, go to Developer tools → Notifications and click New destination.
4. Paste the URL, select the events in the table below, and save.
5. Open the destination you just created and copy its secret key — it starts with pdl_ntfset_.
6. Back in Clakta, paste the secret key and click Finish.

The card reads Added once the secret is saved.

Events to select

Selecting extra events is harmless: anything Clakta does not handle is acknowledged and ignored.

Attribute sales to visitors

A Paddle checkout opens in an overlay or an inline frame, so the visitor's session travels with it in the checkout's customData. Paddle stores that against the transaction — and copies it onto the subscription and every renewal that follows, so one setup credits a customer's whole lifetime.

If your checkout runs on a page with the Clakta script, this is automatic. Both ways of opening a Paddle checkout are covered: buttons using Paddle's paddle_button class, and Paddle.Checkout.open() calls.

If you create transactions from your server, pass it yourself. This is the most reliable option, because it never depends on the browser. Send clakta.getSessionId() from the page along with your checkout request, then:

await fetch("https://api.paddle.com/transactions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${PADDLE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items,
    custom_data: { clakta_session_id: claktaSessionId },
  }),
})

If you build the checkout options yourself, decorate them first:

Paddle.Checkout.open(
  clakta.decoratePaddleCheckout({
    items: [{ priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg", quantity: 1 }],
  }),
)

Privacy-friendly projects

Projects in privacy-friendly mode have no client-side session id to send, so Paddle sales are recorded but not linked to a visitor, and no buyer name or email is stored.

What gets recorded

• Revenue, in the transaction's own currency, and only what the customer actually paid — an invoice covered by account credit is not counted twice. If Clakta does not support that currency, the amount is kept and your project currency applies.
• Customer name and email, once a customer.* event has arrived for them.
• Products — every line of the order, with its Paddle product name.
• Payment method — card, PayPal, Apple Pay, Google Pay or Pix. Bank transfers and local methods read Other.
• Status, and the date the payment settled.
• Attribution — the session, plus the click token and UTMs when the checkout carried them.

Refunds and chargebacks

A refund marks the order refunded once Paddle approves it. A refund still awaiting approval leaves the order paid, because no money has moved yet.

A partial refund also leaves the order paid: Clakta records a sale as one amount, and flipping the whole order would erase revenue you actually kept.

A chargeback marks the order refunded as soon as it is raised, since the money is pulled at that point. Win the dispute later and the order goes back to paid.

Disconnect

Remove the connection from Project settings → Sales platforms. Deliveries stop being accepted immediately. Orders already recorded stay where they are — disconnecting never deletes history.

Delete the destination in Paddle too, so it stops retrying against an endpoint that no longer exists.

Troubleshooting