Skip to content
Statsy
Sign inStart free trial

Polar

Connect Polar so orders, refunds and cancelled subscriptions are credited to the channel that brought the customer.

Polar sells digital products and subscriptions for developers, and reports each order to Statsy over a signed webhook.

Connect Polar

  1. Copy the webhook URL

    In Statsy, open Site settings › Integrations and press Connect on the Polar tile. The dialog shows the URL for your site, ending in /api/hooks/polar/ and your ws_ site key, with a copy button.

  2. Add it as a webhook in Polar

    Paste the URL into a new webhook endpoint in Polar and subscribe it to the events listed below.

  3. Paste the signing secret back

    Polar generates a secret when you add the endpoint; it usually starts with whsec_. Paste it into the second field in the dialog and press Save and connect. It is stored encrypted and never shown again, so keep your own copy.

Note. Paste the secret exactly as Polar gives it to you, whsec_ prefix included. Statsy expects that shape and decodes it for you.

Which events to subscribe to

EventWhat Statsy does with it
order.createdRecords the payment. It is stored as a renewal when the order's billing reason is subscription_cycle, and as a one-time payment otherwise.
refund.createdRecords a refund.
subscription.canceled, subscription.revokedMarks the customer as churned.

Passing the visitor through

Polar carries a metadata object through checkout. The script adds metadata[statsy_vid] to Polar checkout links when they are clicked, so hosted links need no work.

If you create a checkout session through Polar's API, set the same key:

js
const vid = statsy.visitorId();

await polar.checkouts.create({
  products: ['PRODUCT_ID'],
  metadata: vid ? { statsy_vid: vid } : {},
});

How the webhook is verified

Polar follows the Standard Webhooks specification: an id, a timestamp and a base64 signature across three headers. Statsy verifies all three and rejects anything signed more than five minutes away from its own clock.

Amounts

Order totals arrive in the smallest unit of the order currency. Refunds are stored as negative amounts and reduce net revenue in the attribution report.

Last updated · Markdown version