Integrations

Polar revenue attribution: orders, metadata and refunds

Connect Polar’s paid-order events to tracked visits with checkout metadata. Signed delivery establishes the payment; the optional visitor IDs establish the link back to acquisition.

Before you connect

Install the tracker on your verified website and confirm the first event. Open that site’s Settings → Revenue as a workspace owner or admin, choose Polar, and copy the webhook URL shown there. Your deployment’s settings are the authority for its origin.

Configure the webhook

1. In Polar Settings → Webhooks, add an endpoint using the Raw payload format. Copy your site’s exact URL from AnalyticFast and select the three events below. Use Polar’s sandbox with a separate analytics site before live payments.
2. For hosted tracking, the endpoint has this form:

   https://t.analyticfast.com/api/webhooks/polar/YOUR_SITE_ID

   Replace YOUR_SITE_ID with this site’s ID; use the exact URL from Settings if its origin differs.
3. Subscribe to these events:
   • order.paid
   • refund.created
   • refund.updated
4. Copy the endpoint signing secret into AnalyticFast without editing it. The adapter verifies Standard Webhooks headers against the raw request and supports the documented legacy and newer Polar secret formats. Do not use an organization access token as the signing secret.
5. Save. Optionally enter product IDs to filter transactions. A matching product includes the entire transaction, so a filter is not product-level revenue allocation.

Carry the visitor into checkout

When creating Checkout on your server, attach ml_visitor_id and ml_session_id in metadata, omitting unavailable values. Keep your application’s existing metadata. See Polar’s Checkout API guide.

// Browser: read IDs immediately before asking your server to create checkout.
const attribution = window.analyticfast?.attribution?.() ?? {};
// Send these optional IDs with your existing checkout request.
// Server: validate them and copy only the present values into provider metadata.
// Keep prices, products and all payment credentials under server control.

// Fragment for an existing server-created Polar Checkout request:
metadata: { ml_visitor_id, ml_session_id }
// Keep your existing product configuration, success URL and application fields.

A hosted link’s reference_id is an application reference. AnalyticFast does not overwrite it with a visitor ID, and plain Polar links are not automatically decorated with arbitrary metadata fields. If your flow only uses a static link, add an explicit server-created checkout handoff before relying on metadata attribution.

What creates revenue and refunds

Paid orders are keyed by order ID. Subscription-cycle and subscription-meter-cycle orders are classified as renewals. Only refund resources with a successful status subtract revenue, linked by order_id; the recorded refund includes amount plus tax_amount. Do not also use cumulative order.refunded events as a second refund stream.

Verify with a real signed test delivery

1. On your separate test site, arrive with a unique UTM campaign and complete a sandbox payment through your actual checkout flow.
2. Inspect the provider’s delivery log, then check the payment, its currency and its attributed visit in AnalyticFast. Test mode data should stay out of your production analytics site.
3. Retry the same delivery and confirm no duplicate revenue. Issue a successful partial or full refund and confirm the net amount falls once. For subscriptions, test a later renewal.

The settings test button is a local parser preview. It does not contact Polar, verify signatures over the network or persist revenue.

Limits to check before going live

A delivered event with no successful refund status is ignored. A webhook delivery receipt alone does not show that its contents met the adapter’s payment/refund rules. Inspect the actual order or refund in the sandbox and compare its currency and net total with AnalyticFast.

No universal historical import runs when you save a webhook. Validate new deliveries first. Keep currencies separate and compare like date ranges; an analytics revenue total is not a bank payout statement.

Official references

• Webhook endpoint setup
• Delivery and signature verification
• Paid-order webhook
• Refund webhook
• Hosted checkout links

Setup reviewed against the current adapter and official documentation on October 31, 2026. This is an implementation guide, not a claim that a live checkout was exercised.

Add your website to AnalyticFast, then open Settings → Revenue to copy its webhook URL.