Polar

​

What this lets you do

​

Before you start

• A Traceten account with at least one site tracked.
• A Polar organization, and permission to create access tokens on it.
• Your Polar organization ID. It is the UUID in your organization settings.
• The Traceten snippet installed and verified on the site your checkout runs from.
• Workspace admin in Traceten. Connecting and disconnecting a revenue source affects the whole workspace, so only admins can do it.

​

Connect Polar

​

What Traceten does with the token

1. Reads the organization’s name, to confirm the token can see the organization you named.
2. Reads one order, to prove the token can actually see the revenue it is being connected for.
3. Creates a webhook endpoint on your Polar organization pointed at Traceten, subscribed to four events, in Polar’s raw payload format.
4. Stores the token and the webhook signing secret, both encrypted.
5. Starts importing your last 90 days of paid orders, reading newest first and stopping at the window edge. Polar’s order list has no date filter, so one page (the one straddling that boundary) is retrieved and parsed in full, including the buyer email addresses on the orders that turn out to be older than 90 days. Those orders are discarded in memory: not imported, not stored, not logged. No page beyond the boundary is requested.

​

Refunds and net revenue

• The refund is dated on the day it was issued, not the day of the original order. A past day’s revenue figure never changes after the fact, and a day on which you refunded more than you took in reads as a negative number.
• Conversion counts stay gross. A refunded order still counts as a conversion. The money is reported separately as a refunded figure beside the net one.
• Partial refunds subtract exactly what Polar returned.
• A cancelled subscription is not a refund. Cancelling stops future charges. The charges already paid were earned and stay in your totals, so cancelling changes no figure in Traceten. Only a refund takes money back off.

​

The signing secret

​

Sandbox tokens

​

How attribution works

1. Checkout metadata: if you passed the visitor’s _traceten_vid cookie as traceten_visitor_id, Traceten matches it to the originating session exactly.
2. Checkout Link redirect: if you added ?checkout_id={CHECKOUT_ID} to the Checkout Link’s Success URL, the Traceten snippet on that page reports the checkout id and Traceten matches it to the browser that completed the purchase. See below.
3. Email hash: if the buyer’s session called traceten.identify({ email }), Traceten matches the order’s customer email (hashed, never stored) to that visitor.
4. No match: the payment is still recorded so revenue totals stay complete, but it shows as unattributed (no AI source).

​

Checkout Links: attribute without writing code

https://yourdomain.com/thanks?checkout_id={CHECKOUT_ID}

• You change nothing in your code. The only edit is the Success URL in Polar.
• Polar must be connected to Traceten. Traceten ignores a thank-you-page report for a site whose Polar organization is not connected, and does not hold it until you connect. A report can also be discarded for up to a minute after you connect.
• The order of events does not matter. Polar’s webhook usually reaches Traceten before the buyer’s browser finishes redirecting. When that happens the order is recorded first and re-attributed the moment the browser reports in, on the original order’s own date.
• The thank-you page must load within 30 minutes of payment. Traceten pairs a report with an order only when the two are no more than 30 minutes apart. Polar’s redirect happens straight after payment, so this only matters for a thank-you page opened again much later.
• The thank-you page needs the snippet. If the Success URL points somewhere the snippet is not installed, nothing is reported and the order stays unattributed.

​

The amount Traceten records

​

Passing the visitor ID through checkout

// Client-side: read the visitor id and send it to your own backend
const visitorId = window.traceten.getVisitorId(); // null before the first pageview resolves

// Server-side: create a Polar checkout
const visitorId = req.cookies["_traceten_vid"] ?? "";

await fetch("https://api.polar.sh/v1/checkouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POLAR_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    products: ["YOUR_PRODUCT_ID"],
    metadata: { traceten_visitor_id: visitorId },
  }),
});

​

Verify it worked

1. Polar reads Connected in the dashboard.
2. The import banner finishes, and the Revenue page shows historical orders.
3. Place a real order. It appears in Revenue within a minute or two.

​

Troubleshooting

​

Next

• How attribution works
• Currencies