Billing

Polar

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

1. Pass the referral at checkout

const ref = window.referralmeter?.ref() ?? null; // send to your server

// Server, when creating the checkout (Polar SDK: polar.checkouts.create):
metadata: { referralmeter_ref: ref ?? "" },

Referralmeter reads referralmeter_ref from that field on the payment Polar 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

Polar → Settings → Webhooks → Add endpoint. URL: the Polar webhook URL from Referralmeter's Billing connections page. Format: Raw. Copy the signing secret back into Billing connections.

The signing secret is shown when you create the endpoint. Polar's older secrets and the newer whsec_ ones both work.

Events Referralmeter uses:

order.paid
refund.created
refund.updated
subscription.revoked

Test mode

Polar's sandbox is a separate environment and its events carry no test flag, so Referralmeter can't tell sandbox from production on its own. In Billing connections, tick This is a sandbox / test-mode connection on the Polar card while the sandbox endpoint'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 production endpoint's secret.

Good to know

Amounts are Polar's net amount (before tax), and refunds are proportional to it.