How to track Polar.sh revenue by marketing channel

Polar.sh revenue tracking works by writing the visitor's source into the checkout's metadata before they leave your site, then reading it back from the order once it is paid.

Polar copies up to 50 pairs of that metadata onto the order and the subscription, so the source rides along on every webhook and API response.

Subscriptions make the loss bigger: a $29 plan kept for 22 months pays $638, so a channel credited only for the first order gets 4.5% of what it earned.

Where Polar.sh sales lose their source

Polar is the Merchant of Record and hosts the checkout: the buyer pays on a Polar page, reached by redirect or inside an iframe from Polar's origin when you use Embedded Checkout.

Your first-party cookie cannot follow, and a Google Analytics 4 tag on your pages sees the click but not what happens inside Polar's checkout.

Step 1: Tag your Polar checkout links

A Polar Checkout Link accepts 5 UTM parameters and reference_id as query parameters, and Polar saves them in the metadata of each session the link creates.

Polar's changelog dates the feature to May 19, 2025, and the Checkout Links documentation says link and session metadata propagate to the order and subscription.

Keep 1 link per product and vary the query string by placement, and use the free UTM builder so "newsletter" and "Newsletter" never become 2 sources.

If a tagged ad lands on a page whose Buy button uses the plain link, the tags are lost, so append saved UTMs to each checkout link, or use step 2.

CHECKOUT_LINK_URL?utm_source=newsletter&utm_medium=email&utm_campaign=oct-launch&reference_id=issue-42

Step 2: Create the checkout on your server

When your own code starts the purchase, call POST /v1/checkouts/ with a checkouts:write token and put the source in metadata.

1// app/api/checkout/route.ts (Next.js route handler)2import { cookies } from "next/headers";3 4const KEYS = ["vid", "utm_source", "utm_medium", "utm_campaign", "landing_path"];5 6export async function POST(req: Request) {7  const { productId } = await req.json();8  const jar = await cookies();9 10  // Polar rejects empty strings, so leave missing keys out11  const metadata: Record<string, string> = {};12  for (const key of KEYS) {13    const value = jar.get(key)?.value;14    if (value) metadata[key] = value.slice(0, 500);15  }16 17  const res = await fetch("https://api.polar.sh/v1/checkouts/", {18    method: "POST",19    headers: {20      Authorization: "Bearer " + process.env.POLAR_ACCESS_TOKEN,21      "Content-Type": "application/json",22    },23    body: JSON.stringify({24      products: [productId],25      success_url: "https://example.com/welcome?checkout_id={CHECKOUT_ID}",26      metadata,27    }),28  });29 30  const checkout = await res.json();31  return Response.json({ url: checkout.url });32}

The Create Checkout Session reference sets these limits, so store a visitor ID and a few parsed UTM values, since a long landing URL can overrun 500 characters.

Step 3: Subscribe to the events that carry money

Add an endpoint under Webhooks in your organization's settings, with the Raw format and a secret. Of the 30-plus events in Polar's webhook events documentation, attribution needs order.paid and order.refunded, plus subscription.created and subscription.canceled if you report churn by channel.

Skip order.created and subscription.cycled: a renewal sends 5 events in the order below, its order is still pending at event 3, and event 5 is the one to book. A failed charge moves the subscription to past_due instead.

The handler below uses API version 2026-10 and version 1.0.2 of the @polar-sh/sdk package.

1// app/api/webhooks/polar/route.ts2import { webhooks } from "@polar-sh/sdk/2026-10";3 4export async function POST(req: Request) {5  const body = await req.text();6 7  let event: Awaited<ReturnType<typeof webhooks.validateEvent>>;8  try {9    event = await webhooks.validateEvent(10      body,11      {12        "webhook-id": req.headers.get("webhook-id") ?? "",13        "webhook-timestamp": req.headers.get("webhook-timestamp") ?? "",14        "webhook-signature": req.headers.get("webhook-signature") ?? "",15      },16      process.env.POLAR_WEBHOOK_SECRET!,17    );18  } catch (error) {19    // An event type this SDK version does not know is not a bad signature20    if (error instanceof webhooks.PolarWebhookUnknownTypeError) {21      return new Response(null, { status: 202 });22    }23    return new Response(null, { status: 403 });24  }25 26  if (event.type === "order.paid") {27    const o = event.data;28    await upsertRevenue({29      orderId: o.id, // unique key, so redeliveries do not duplicate30      subscriptionId: o.subscription_id,31      billingReason: o.billing_reason,32      netCents: o.net_amount,33      currency: o.currency,34      email: o.customer.email,35      source: o.metadata.utm_source ?? null,36      visitorId: o.metadata.vid ?? null,37    });38  }39 40  if (event.type === "order.refunded") {41    await recordRefund(event.data.id, event.data.refunded_amount);42  }43 44  return new Response(null, { status: 202 });45}

Step 4: Verify signatures and respect delivery limits

Per Polar's webhook delivery guide, each delivery is signed with the Standard Webhooks headers.

Secrets generated on or after September 8, 2026 at 00:00 UTC follow that spec, and older secrets use Polar's original HMAC scheme with the full whsec_ string as the key.

Polar's SDK tries both keys, while a generic library needs an older secret base64-encoded first.

Step 5: Store an amount that excludes tax

Polar collects tax as Merchant of Record, so total_amount holds money that was never yours. For channel reports I'd store net_amount, which reflects a discount a campaign gave away and leaves tax out.

Polar's fees documentation works through a $30 purchase from Sweden, and the table gives the same amounts as order fields.

Step 6: Credit renewals and reverse refunds

Polar's documentation says checkout metadata is copied to the order and the subscription and does not say renewal orders repeat it, so save the source against subscription_id at the first paid order and credit every order with that ID to it.

Skip that and the $29 plan earns its channel $29 of $638, leaving $609 with no source (see subscription LTV attribution).

order.refunded covers full and partial refunds, moving the order to refunded or partially_refunded with refunded_amount recording how much, so a $10 refund on a $29 order stores 1,000 and the channel keeps $19.

Per Polar's refund documentation the refundable maximum is the net amount, and Polar may refund a lower-value order itself within 60 days of purchase to head off a chargeback.

Refunding a subscription's order leaves the subscription running, so handle cancellations separately.

Choose which touch gets the credit

Whatever you write at checkout is a fixed answer. UTMs from a first visit give you first-touch attribution, and UTMs from the visit that clicked Buy give you last-touch, and you can store both under separate keys.

A split across several touches needs a visitor ID joined to a click log you keep, and the comparison of last-touch, first-touch and linear models covers when each fits.

In this example a buyer clicks a YouTube link, then a Hacker News post, then returns directly to buy the $29 plan and keeps it 22 months.

Step 7: Reconcile nightly and test in the sandbox

Handlers break after deploys, so compare orders nightly.

List Orders needs the orders:read scope, returns 10 orders per page by default, up to 100, and filters by metadata, so 1 call per source value, summing net_amount for orders whose status is paid, gives a channel report with no extra tooling.

Amounts are in cents, so 40 newsletter orders of 2,900 sum to 116,000, or $1,160.

curl -G "https://api.polar.sh/v1/orders/" \
  -H "Authorization: Bearer $POLAR_ACCESS_TOKEN" \
  --data-urlencode "metadata[utm_source]=newsletter" \
  --data-urlencode "limit=100"

Polar's sandbox is a separate environment with its own account, organization and token, served from sandbox-api.polar.sh, and production tokens fail there. Pay with Stripe's test card 4242 4242 4242 4242 and a future expiry, then check 3 things.

• The order.paid delivery in the sandbox webhook settings holds your metadata keys, spelled exactly as you wrote them.
• The net_amount and tax_amount match the checkout page.
• A refund produces order.refunded, and redelivering order.paid leaves 1 row for that order.

Polar.sh revenue tracking with TrackRev

TrackRev is SaaS affiliate software with revenue attribution built in, so it does the join and the renewal bookkeeping for Polar.sh orders.

You connect Polar with a read-only Organization Access Token with 3 scopes plus your Organization Identifier, and TrackRev asks for order.paid and order.refunded webhooks.

It joins an order to a click through a visitor ID: API checkouts take it as metadata.vid, as in step 2, and its pixel adds a vid parameter to links that point at buy.polar.sh.

Without a vid it falls back to the buyer's email. TrackRev pulls orders over the read-only API after verifying a webhook, so replays cannot double count, and an hourly sync covers workspaces with no webhook.

With 1 or 2 channels and a few orders a week, tagged links and a script over the Orders API are enough.

TrackRev earns its price when you want click-level journeys with several touches per buyer, or affiliate commissions from the same orders.

The same plans read Stripe, Paddle Billing, Lemon Squeezy, Creem and Dodo Payments, and Indie at $29 a month and Growth at $299 a year put no limit on the revenue tracked (pricing).