Billing

Paddle

Connect Paddle: what to pass at checkout, which webhook events, and where the signing secret is.

1. Pass the referral at checkout

// Paddle.js overlay or inline checkout:
Paddle.Checkout.open({
  items: [/* … */],
  customData: { referralmeter_ref: window.referralmeter?.ref() ?? "" },
});

// Or server-side, when creating a transaction: custom_data: { referralmeter_ref: ref }

Referralmeter reads referralmeter_ref from that field on the payment Paddle sends back. To mark a purchase as credits or a top-up (so your credits rule applies), also set kind: "credits" in the same metadata.

2. Connect the webhook

Paddle → Developer tools → Notifications → New destination. URL: the Paddle webhook URL from Billing connections. Copy the destination's secret key (pdl_ntfset_…) into Billing connections.

Paddle shows the secret key on the notification destination; it starts with pdl_ntfset_.

Events Referralmeter uses:

transaction.completed
adjustment.created
adjustment.updated
subscription.canceled

Test mode

Paddle's sandbox is a separate account and its events carry no test flag, so Referralmeter can't tell sandbox from live on its own. In Billing connections, tick This is a sandbox / test-mode connection on the Paddle card while the sandbox destination's secret is connected. Every event from that connection is then recorded as test (livemode: false): shown on your dashboard, never counted toward stats or plan limits, never paid out. Untick it when you switch to the live destination's secret.

Good to know

Refunds and chargebacks are Paddle adjustments; they count once Paddle approves them.