Use this when you sell through a Polar checkout link opened from your own page — a buy button, a pricing card — with no server code of your own.
There is no server call to attach data to, so the ids go on the link instead. The tag has already set them by the time anyone can click.
<a id="buy" href="https://buy.polar.sh/polar_cl_XXXXXXXX">Buy now</a>
<script>
document.getElementById("buy").addEventListener("click", function (e) {
// Read at CLICK time, not when the page was built. On a first visit the
// tag may not have run yet when the HTML is parsed.
var vid = window.truestat && window.truestat.visitorId;
var vs = window.truestat && window.truestat.sessionId;
var url = new URL(e.currentTarget.href);
if (vid) url.searchParams.set("metadata[ts_vid]", vid);
if (vs) url.searchParams.set("metadata[ts_vs]", vs);
e.currentTarget.href = url.toString();
});
</script>metadata[key] is Polar's own syntax for putting a value on a checkout
link. It arrives on the order as metadata.ts_vid, which is the same place the
Checkout API puts it — so both routes
produce identical data and the same renewal behaviour.
Opening it with Polar's embed
If you use Polar's embedded checkout rather than a plain link, set the same parameters on the URL you hand it:
<script src="https://cdn.jsdelivr.net/npm/@polar-sh/checkout@0.1/dist/embed.global.js" defer></script>
<a
href="https://buy.polar.sh/polar_cl_XXXXXXXX"
data-polar-checkout
data-polar-checkout-theme="light"
id="buy"
>Buy now</a>
<script>
// Set the ids BEFORE the embed reads the href — on page load rather than on
// click, because the embed intercepts the click itself.
window.addEventListener("load", function () {
var el = document.getElementById("buy");
var vid = window.truestat && window.truestat.visitorId;
if (!vid) return;
var url = new URL(el.href);
url.searchParams.set("metadata[ts_vid]", vid);
el.href = url.toString();
});
</script>What this cannot do
It depends on your page's JavaScript running. A customer with scripts blocked reaches the same checkout with no ids attached, and that payment arrives unattributed. The sale is never lost — only its source.
If your server creates the checkout, prefer the Checkout API: the ids are read from a cookie the browser cannot forge, and nothing depends on client-side code.