Polar

Set up revenue attribution with Polar.

Polar

Polar is a payment platform for developers and open-source projects. This guide shows how to pass EngageTrack visitor and session IDs through Polar's metadata field for revenue attribution.

How It Works

The EngageTrack SDK generates a visitor ID and session ID (stored in browser storage, accessible via the SDK's JavaScript API)
When creating a Polar checkout, you pass these values in the metadata field
After payment, Polar sends a webhook to EngageTrack with the metadata
EngageTrack reads the visitor ID and attributes the revenue to the traffic source

Checkout API

Node.js / Express

import { Polar } from "@polar-sh/sdk";
 
const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN });
 
app.post("/create-checkout", async (req, res) => {
	// Receive visitor/session IDs from the client request body
	const { engagetrack_visitor_id: visitorId, engagetrack_session_id: sessionId } = req.body;
 
	const checkout = await polar.checkouts.create({
		productPriceId: "price_xxxxxxxxxxxxx",
		successUrl: "https://yoursite.com/success",
		metadata: {
			engagetrack_visitor_id: visitorId,
			engagetrack_session_id: sessionId,
		},
	});
 
	res.json({ url: checkout.url });
});

Next.js App Router (Route Handler)

import { NextRequest, NextResponse } from "next/server";
import { Polar } from "@polar-sh/sdk";
 
const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN! });
 
export async function POST(request: NextRequest) {
	// Receive visitor/session IDs from the client request body
	const { price_id, engagetrack_visitor_id, engagetrack_session_id } =
		await request.json();
	const visitorId = engagetrack_visitor_id ?? "";
	const sessionId = engagetrack_session_id ?? "";
 
	const checkout = await polar.checkouts.create({
		productPriceId: price_id,
		successUrl: "https://yoursite.com/success",
		metadata: {
			engagetrack_visitor_id: visitorId,
			engagetrack_session_id: sessionId,
		},
	});
 
	return NextResponse.json({ url: checkout.url });
}

Polar uses a metadata field (not custom_data) to pass arbitrary key-value pairs through the checkout. EngageTrack expects the keys engagetrack_visitor_id and engagetrack_session_id.

Checkout Links

If you use Polar Checkout Links, append the metadata as URL parameters:

<a id="polar-checkout" href="https://polar.sh/yourorg/products/your-product">
	Buy Now
</a>
 
<script>
	document.addEventListener("DOMContentLoaded", function () {
		const visitorId = window.engagetrack?.getVisitorId() || "";
		const sessionId = window.engagetrack?.getSessionId() || "";
 
		document.querySelectorAll('a[href*="polar.sh"]').forEach((link) => {
			const url = new URL(link.href);
			url.searchParams.set("metadata[engagetrack_visitor_id]", visitorId);
			url.searchParams.set("metadata[engagetrack_session_id]", sessionId);
			link.href = url.toString();
		});
	});
</script>

Set Up the Webhook

Go to Polar Dashboard → Settings → Webhooks
Click Add endpoint
Enter the webhook URL:

https://api.engagetrack.net/api/v1/webhooks/revenue/polar/{YOUR_SITE_PUBLIC_ID}

Under Events, select:
- order.created
- subscription.updated
- refund.created
Click Save

If you connected Polar via the EngageTrack dashboard (Site Settings → Revenue), the webhook is registered automatically and you can skip this step.

Verify

Open your site and confirm the SDK is loaded by running window.engagetrack.getVisitorId() in the browser console
Complete a test purchase using Polar's sandbox mode
Go to your EngageTrack dashboard → Revenue tab
The test payment should appear within a few seconds, attributed to your traffic source

If the payment appears without attribution:

Check the Polar webhook logs for delivery errors (Polar Dashboard → Settings → Webhooks → select endpoint)
Verify the metadata field in the webhook payload contains engagetrack_visitor_id
Ensure the EngageTrack SDK is loaded and the cookie values are non-empty when creating the checkout