Documentation

Polar guide

Subscribe to order.paid, refund.created, and refund.updated. Standard Webhooks headers authenticate id.timestamp.rawBody with HMAC-SHA256 and base64 v1 signatures. Secrets generated since 2026-09-08 decode the whsec_ suffix; legacy Polar secrets use the entire literal string. The verifier supports both documented key generations and five-minute timestamp freshness. Official delivery/key migration guide.

Paid orders use data.id, total_amount, currency, product_id, customer_id, subscription_id and metadata. Both subscription_cycle and subscription_meter_cycle are classified as recurring revenue; the latter bills usage at the end of a meter period. Order webhook, order lifecycle.

Only successful refund resources count. Use refund id, original order_id, and amount + tax_amount in currency. Do not also subscribe order.refunded for ingestion: that order payload is a cumulative balance and would duplicate refund resources. Refund event, official schema, refund model and totals.

Put ml_visitor_id and ml_session_id in server-created checkout metadata. Hosted links support reference_id and UTMs, but arbitrary metadata query keys were not established. The tracker preserves existing application references and does not auto-tag Polar links. Checkout links.

No live checkout, legacy endpoint, or new endpoint delivery was exercised. Missing refund success status fails closed even if a generated example omits the status field.