Polar Revenue Attribution Setup

traffic.cx reads paid orders (one-off purchases, subscription starts and renewals) and refunds.

First install the tracker. You need an owner/admin role in traffic.cx and permission to create a Polar organization access token. Use a separate traffic.cx test site for sandbox orders; they appear in that site's reports. Connecting creates a webhook in your Polar organization.

1. Connect

1. In Polar, open Settings → Developers and create an organization access token with these scopes: orders:read, refunds:read, organizations:read, webhooks:read and webhooks:write.
2. In traffic.cx, open Settings → Revenue, choose Connect next to Polar and paste the token.

Sandbox tokens work too: traffic.cx tries production first, then the sandbox. It creates the webhook endpoint, keeps its signing secret encrypted, and imports the last 90 days.

2. Pass the visitor's IDs

Polar copies checkout metadata to the order.

// Server-side sandbox example. tcx contains the validated browser IDs.
const response = await fetch('https://sandbox-api.polar.sh/v1/checkouts/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POLAR_CHECKOUT_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    products: [process.env.POLAR_PRODUCT_ID],
    success_url: 'https://example.com/thanks',
    metadata: tcx,
  }),
});
if (!response.ok) throw new Error('Polar checkout failed');
const checkout = await response.json();
const url = checkout.url;

Pass tcx from the browser identifier handoff, choose a product from your trusted server catalogue, replace the success URL and return url from your authenticated checkout endpoint. The checkout token needs checkouts:write; it is separate from the reporting token you give traffic.cx. Polar's create-checkout reference confirms that checkout metadata is copied to the resulting order/subscription. For live checkout, use the matching live token/product and https://api.polar.sh/v1/checkouts/.

What traffic.cx records

Amounts are the order's net amount: Polar collects the tax as the merchant of record.

3. Verify and troubleshoot

Follow the attribution test flow in Polar's sandbox. Confirm the completed order has tcx_pvid in its metadata and appears in traffic.cx with the expected source. For subscriptions, verify the start and a later renewal; also check a successful refund.

• Token rejected: check organization access and every reporting/webhook scope. Your checkout token additionally needs checkouts:write.
• Checkout rejected: use a sandbox token with a sandbox product and the sandbox API host, or live credentials/products with the live host.
• Missing payment: check for an order.paid delivery, not only a created checkout, and inspect the webhook log or sync the connection.
• Unattributed: send IDs in checkout metadata, not customer_metadata. Confirm the visit was recorded and falls inside the lookback window.

The example payload and connector fixtures are checked. A new Polar account connection and sandbox transaction are not claimed as verified; complete those checks for your setup.