Referrals with Polar

Connect Polar and every paid order, subscription renewal and refund reaches the program, credited to the partner whose link or code brought the customer. Polar signs deliveries with Standard Webhooks, with a timestamp.

Add an endpoint

1. Open the program, Setup, Billing, Polar, and copy the endpoint URL.
2. In Polar: Organization settings, Webhooks, Add Endpoint. Paste the URL, format Raw, and select order.paid and order.refunded.
3. Paste the endpoint's secret on the card (shown when you add it, or one you set yourself). Both the current and the older form of Polar's secrets are accepted.

Pass the referral to checkout

Set metadata.boltclaw_ref on the checkout link or session; Polar copies link metadata to the order and the subscription.

await polar.checkouts.create({
  products: ["prod_monthly"],
  externalCustomerId: "acme-user-10442",
  metadata: { boltclaw_ref: ref, boltclaw_customer_id: "acme-user-10442" },
});

The customer is your own id from the metadata, else Polar's external_id for the customer, else Polar's customer id.

Refunds

order.refunded carries the running total refunded, so a partial refund takes back that share of the commission and a second refund adds to the first. Polar has no dispute event.

Discount codes

A discount code typed at Polar's checkout arrives as its text, so a sale made with a partner's code alone is credited to them.

Test mode

Polar's sandbox is its own environment and its events do not say they are tests. Add a second Polar integration for the sandbox and switch Sandbox on.

Check it works

On the program's Setup tab, the Billing row of the setup status turns Connected with the first verified event, and says when a delivery was refused (nearly always the wrong secret). Then press Send a test sale to see a click, a signup, a sale and a refund go through your rules with test data, or make a real test purchase in Polar's sandbox. See Connect your billing system for the whole setup status and what test data never does.