Polar

Connect Polar with an organization access token. Pulse imports your orders, listens for new sales and refunds, and credits each order to the visit behind it.

Connect Polar#

1. Create a token

   In Polar open Settings, Developers, New token and grant two scopes:

   Scope	Why
   orders:read	Import orders.
   webhooks:write	Let Pulse register its own webhook.

2. Paste it into Pulse

   Settings, Revenue, Connect, Polar. The token starts with polar_oat_. Pulse imports the last 365 days and registers the webhook.

3. Optional: paste a webhook secret

   Only needed when Pulse cannot register the webhook (a non-https local setup). Create the endpoint in Polar yourself and paste its secret into the second field.

What is synced#

• Orders that are paid, refunded or partially refunded.
• Amount is the order's net amount (total minus tax) in its own currency.
• Product name, country from the billing address, and the email stored only as a keyed one-way hash.
• Kind: a subscription cycle is a renewal, other subscription orders are subscription sales, the rest are one-time.

Webhooks are verified with Polar's Standard Webhooks signature (webhook-id, webhook-timestamp, webhook-signature); requests older than five minutes are rejected.

Attribution#

Nothing to do for checkout links. When a visitor clicks a link to buy.polar.sh, or a polar.sh link whose path contains checkout, the script adds these parameters at click time (and logs a checkout event). Mark links that reach Polar another way with data-pulse-checkout="polar".

• reference_id=<visitor id>
• metadata[pulse_vid]=<visitor id>

Pulse reads pulse_vid (and an optional source) from the order's metadata. If you create checkout sessions with the Polar API, set metadata to { pulse_vid: window.pulse.visitorId() } yourself, reading the id in the browser and sending it to your server.

Refunds and currencies#

A fully refunded order stops counting; a partial refund reduces the sale by the refunded net amount. Orders in other currencies are converted to US dollars at the payment day's rate (see currencies).

Common issues#

“Polar rejected this token”

Create an organization access token in Settings, Developers.

“This Polar token lacks a scope”

Edit the token and add orders:read and webhooks:write.

Sales have no source

The buyer did not arrive through a tagged link. Make sure the script runs on the page with your buy button and the button links to a Polar checkout URL (not an embedded widget).