Polar

Attribute Polar orders, subscription renewals and refunds to the visits that led to them.

Use this connector when your products are sold through Polar checkouts. Seean verifies each delivery with Polar’s webhook secret, records order.paid events as orders and matches refund.created events to them. Attribution is derived on Seean’s server from the buyer’s tracked visits when the order metadata carries the visitor ID.

Quick connect

After Enable (step 1 below), skip steps 2–4: paste an organization access token (organization Settings, Developers section) with the scopes webhooks:read and webhooks:write into Quick connect under Polar and choose Connect automatically. Seean creates the webhook for this website’s URL with order.paid and refund.created (raw format), saves its signing secret and shows Secret saved (ends in …). An older endpoint for the same Seean URL is deleted only after the new one is saved, so running quick connect again is safe; if the provider refuses that deletion the panel asks you to delete the old endpoint yourself. The key is used for that one request and is not stored; you can delete it afterwards. Sandbox tokens connect the sandbox organization. Seean keeps one Polar connection per website, so use the key for the mode you take real payments in: a test or sandbox key replaces a live connection. If the key is wrong or lacks a permission, the panel shows the reason (including the provider’s own message, such as an endpoint limit) and nothing is saved. Saving a secret manually or choosing Disable while quick connect runs cancels it, and the endpoint it created is deleted. The manual setup below always works.

Setup

In Seean open Settings → Integrations → Payment providers on your own website, choose Polar, select Enable and copy the webhook URL (https://events.seean.io/api/connect/polar/<site ID>; use the exact value shown).
In Polar open your organization’s Settings → Webhooks and add an endpoint with that URL. Keep the payload format Raw.
Select the order.paid and refund.created events.
Copy the endpoint’s webhook secret (whsec_…) and paste it into Seean, then choose Save secret. Seean accepts both of Polar’s signing schemes: Standard Webhooks secrets issued from 8 September 2026 and earlier Polar HMAC secrets.
Pass the attribution metadata described below when you create checkouts. Do not paste the site tracker token into Polar; only the webhook secret is used.

Only the website owner can connect, replace or disconnect a provider; one connection per provider; demo websites cannot connect providers.

Attribution handoff

Read window.seean.attribution() in the browser when the visitor starts checkout, send it to your server and attach it as checkout metadata. Polar copies checkout metadata to the order, which is where Seean reads it:

// Browser
await window.seean?.ready;
const a = window.seean?.attribution?.() ?? {};
const seean = { seean_visitor_id: a.visitorId, seean_landing_path: a.landingPath, seean_converting_path: a.convertingPath, seean_campaign: a.campaign };
// send `seean` to the endpoint that creates the checkout

// Server (Polar SDK)
const checkout = await polar.checkouts.create({
  products: ["prod_123"],
  successUrl: "https://example.com/thanks",
  metadata: Object.fromEntries(Object.entries(seean).filter(([, v]) => v)),
});

Key	Meaning
`seean_visitor_id`	Links the order to the buyer’s tracked visits; touches, first and last source, landing page and time to buy are derived from that history.
`seean_landing_path`	Used only when Seean has no tracked visit for the visitor in the 90 days before the order.
`seean_converting_path`	The page where checkout started.
`seean_campaign`	Overrides the campaign derived from the tracked history.

Plain Polar checkout links carry no per-visitor metadata, so orders from them are recorded as Unattributed; create checkouts through the API or SDK to attribute them. Orders without seean_visitor_id are always recorded, just unattributed.

What is recorded

Event	Result in Seean
`order.paid`	Order with `total_amount` in `currency`. `billing_reason: purchase` becomes a one-time order; `subscription_create`, `subscription_cycle` and `subscription_update` become subscription orders, so renewals are recorded as separate orders.
`refund.created`	Refund of the order in `order_id` by `amount`.

The order ID is the Polar order ID, the product name is the order’s product name (then its description) and the order time is created_at. Other events are acknowledged and ignored.

Refunds

refund.created reduces the order by the refunded amount; partial refunds are supported and each refund ID is applied once. Refunds lower net revenue in the period of the original order. If the original order has not arrived, Seean returns HTTP 503 and shows Last event failed: Order not found. The provider can retry after the order arrives; the refund ID prevents double counting. A refund whose order is still missing one day after the refund was created is acknowledged and ignored, so refunds of payments Seean never recorded do not keep the endpoint failing; record those with the Order API. See delivery recovery if retries expire.

Currency

Orders are stored in the website’s reporting currency (Settings → Integrations → Revenue integration). Polar amounts are already in minor units. An order in another currency is acknowledged but not stored, and the reason appears under the provider.

Verify

Create a sandbox order, or resend a delivery from the endpoint’s log in Polar. The status line under Polar shows the last event time and, if the last event could not be stored, the error. Then open Revenue for a range containing the order and check the amount, product and derived attribution. Duplicate deliveries return duplicate and change nothing.

Limits

Seean verifies the webhook-id, webhook-timestamp and webhook-signature headers and rejects deliveries whose timestamp is more than five minutes old.
Request bodies above 64 KiB are rejected with 413. Events Seean does not handle are acknowledged with 200; rate limits return 429 and temporary ingestion failures return 503 so the provider can retry. See delivery recovery.
Disable stops accepting events (the URL answers 404); delete the endpoint in Polar so it stops retrying. Existing orders are kept.

Something unclear? Contact support.