Revenue Connectors · Polar

Connect Polar to Admaxxer

Forward Polar's order.created and subscription.created webhooks to Admaxxer so every checkout, sponsorship, and SaaS subscription shows up in your revenue attribution, blended MER, and cohort LTV. Five-minute setup, signed via the Polar-Webhook-Signature or X-Polar-Signature header, visitors stitched via metadata.admx_visitor_id.

Open Revenue Settings Back to all connectors

1. Prerequisites

2. Create a Polar API token

  1. In the Polar dashboard, go to Settings › Developers › Personal Access Tokens › + New token (or the Organization Tokens equivalent).
  2. Name it Admaxxer Revenue Read.
  3. Scopes: orders:read, subscriptions:read, products:read. Nothing else.
  4. Copy the token value and paste it into Admaxxer › Revenue Settings › Polar.

3. Add the webhook endpoint

Polar will send signed webhook events to a single Admaxxer URL. Replace <YOUR_WEBSITE_ID> with the UUID shown in Revenue Settings.

https://admaxxer.com/api/pixel/webhooks/polar/<YOUR_WEBSITE_ID>
  1. In the Polar dashboard, go to Settings › Webhooks › + Add endpoint.
  2. URL: paste your Admaxxer webhook URL.
  3. Format: Raw (JSON).
  4. Events:
    • order.created
    • subscription.created
  5. Recommended additional: order.refunded, subscription.canceled.
  6. Save. Polar reveals a webhook secret.
  7. Copy the secret and paste it into Admaxxer Revenue Settings › Polar › Webhook signing secret.

The signing secret is what makes the Polar-Webhook-Signature or X-Polar-Signature header verifiable. Without it, Admaxxer rejects every inbound webhook with 401 invalid_signature.

4. Stamp the visitor ID on every checkout

Pass metadata when creating a Polar Checkout. The Admaxxer pixel exposes window.admx.getVisitorId():

// Server-side, polar-sh SDK
const checkout = await polar.checkouts.create({
  productPriceId: 'price_xxx',
  successUrl: 'https://example.com/thanks',
  metadata: {
    admx_visitor_id: req.cookies['admx_vid'] || ''
  }
});

Polar Checkout link with metadata

// Append metadata to the checkout link via query param
const visitorId = window.admx.getVisitorId() || '';
const url = new URL(polarCheckoutUrl);
url.searchParams.set('metadata[admx_visitor_id]', visitorId);
window.location.href = url.toString();

The metadata propagates from the Checkout to the resulting Order and (for subscriptions) the Subscription record. Admaxxer reads metadata.admx_visitor_id from the webhook payload.

5. Verify the connection

  1. In Polar, go to Settings › Webhooks, select your Admaxxer endpoint, and click Send test event (or use Polar's CLI).
  2. Choose order.created and send.
  3. In Admaxxer, open Revenue Settings. The "Last 50 webhook deliveries" panel shows the test with status ok.
  4. Run a real test purchase in Polar's sandbox or test mode. Inspect the resulting Order and confirm metadata.admx_visitor_id is non-empty.
  5. Within 3 seconds, the order appears in the Admaxxer attribution dashboard, joined to the visitor's acquisition source.

6. Troubleshooting

Webhook returns 401 invalid_signature
Signing secret mismatch. Re-copy the webhook secret from the Polar webhook screen into Admaxxer Revenue Settings. Don't paste your API token — only the webhook signing secret validates inbound payloads.
Order appears as unattributed
metadata.admx_visitor_id was empty on the Order. Confirm metadata.admx_visitor_id was set when creating the Checkout. Inspect the Order in the Polar dashboard to verify.
Subscription renewals not appearing
Renewals fire order.created linked to a subscription_id. Make sure your endpoint subscribes to order.created, not just subscription.created (which only fires once).
Refunds not subtracting from MER
Add order.refunded to the same endpoint. Admaxxer treats refunds as negative revenue events linked to the original order.

Frequently asked

Is Polar a good fit for non-OSS products?
Yes. Polar started as a sponsorship tool for open-source maintainers but has expanded into a general-purpose merchant-of-record for SaaS, digital downloads, and subscriptions. The Admaxxer connector treats every order.created and subscription.created event identically regardless of product category, so the same revenue-attribution flow works for OSS sponsorships and pure SaaS revenue.
Why are there two possible signature headers?
Polar's webhook implementation has used both Polar-Webhook-Signature and X-Polar-Signature at different points in their API timeline. Admaxxer accepts either header — whichever Polar sends — and verifies with the same HMAC-SHA256 logic. You don't need to configure anything; we read both header names.
How do I add metadata on a Polar Checkout?
When creating a Checkout via Polar's API or SDK, pass metadata: { admx_visitor_id: '<visitor-id>' }. The metadata object propagates to the Order and Subscription that result from the checkout. The Admaxxer pixel exposes window.admx.getVisitorId() so your server can fetch the visitor ID when constructing the Polar checkout.
What if the visitor pays via a magic link emailed by Polar?
If you send the visitor a Polar checkout link by email and they pay from a different device, the visitor ID embedded in the metadata when you generated the link still travels with the order — that's why we stamp it on the order itself, not the URL or cookie. The order remains attributed to the visitor who originally added it to cart, even if they finish payment on a different device.
How are subscription renewals attributed?
subscription.created fires once on the initial subscription. Subsequent renewals fire order.created with a subscription_id reference, which Admaxxer joins to the original subscription's metadata. Cohort LTV correctly accumulates across all renewals back to the original visitor.

Next steps