Connect Polar

Polar orders land in Statiz in real time through a webhook you create in your own Polar dashboard, refunds net out automatically, and Sync now backfills up to a year of history. Setup needs three values from Polar: a webhook signing secret, a personal access token, and your organization ID.

Connect at most ONE revenue source per website — either the Polar integration or the client-side statiz.revenue() beacon, never both, or the same payment counts twice (why).

Step 1: Create the webhook

In the Polar dashboard, open Settings → Webhooks and click Add endpoint.

Polar's webhook documentation showing how to set up webhook endpoints.
Polar's webhook setup guide — create the endpoint in Settings → Webhooks.
  1. Paste the Endpoint URL shown in Statiz under Settings → Revenue → Connect Polar — it looks like https://your-statiz-url/api/webhooks/polar/{your site id}. Statiz must be reachable at a public URL (localhost can't receive webhooks — deploy first or use a tunnel).
  2. Select exactly these two events:
    • order.paid — a completed order (a positive revenue row)
    • order.refunded — Statiz then fetches the order's individual refunds from Polar's API and writes each as a negative row
  3. After creating the endpoint, copy its Signing secret (whsec_…) — you'll paste it in Step 3.

Step 2: Copy your token & org ID

Statiz needs two more values from Polar — both live in the Polar dashboard's Settings:

  • Organization ID — under Settings → General → Profile, the Identifier field (a UUID like fda84e25-7b55-…).
  • Personal access token — under Settings → General → Developer → Token. Create one with no expiration and only these scopes: checkouts:read, orders:read, organizations:read, products:read, subscriptions:read, refunds:read. It starts with polar_oat_.

The token can only read — Statiz never creates orders, checkouts, or refunds in your Polar account.

Step 3: Connect in Statiz

Open your website in Statiz, go to Settings → Revenue, pick Polar as the provider, then paste the organization ID, the access token and the whsec_… signing secret and click Connect.

Statiz's Settings → Revenue tab with Polar selected, showing the webhook setup guide with the organization ID field, the access token and signing secret fields.
Settings → Revenue with Polar selected — org ID, access token and signing secret in one form.

Statiz verifies the token against the organization (and tells you if the token can't read it), encrypts everything with AES-256-GCM, and stores it — the raw token is never logged or shown again.

Step 4: Sync and verify

Click Sync now once connected. The first sync backfills paid orders and succeeded refunds from Polar's API — up to 365 days — and reports how many transactions were imported. Later orders arrive in real time through the webhook.

The connected Polar card in Statiz showing the organization label, the webhook URL, and the Sync now button with an import result.
Connected — the card names the organization and shows the URL your Polar webhook must point at.

To verify the webhook end-to-end, complete a test checkout and watch the Revenue tile on the dashboard jump. Duplicate deliveries and re-syncs are harmless — orders are stored under their Polar order id, refunds under their refund id, so nothing is counted twice.

Notes & caveats

  • Polar's webhook payloads for refunds carry no amounts — Statiz fetches the order's refunds through the API with your token, which is why refunds:read is required.
  • Polar revenue is counted per order subtotal — before tax and fees, Polar's own revenue metric.
  • To attribute payments to tracked visitors, pass the visitor id as the order's metadata or the customer's external_id — the full recipe is in Link payments to visitors.
  • Polar retries failed deliveries up to ten times; Statiz acknowledges everything it processed, so retries are always safe.
  • Disconnecting removes the stored token and secret — also delete the endpoint in Polar's dashboard if you're done.