Polar revenue, joined to the visits behind it.

Virling reads Polar orders, refunds and, when allowed, subscriptions with an organization access token.

Create a token

1. In Polar, open your organization's settings and create an Organization Access Token. Polar's guide: organization access tokens.
2. Give it the orders:read and refunds:read scopes, plus subscriptions:read so Retention can tell who still pays. No other scopes are needed.
3. Paste it into Virling. It starts with polar_oat_.

Production and sandbox tokens both work. Virling tries api.polar.sh first and sandbox-api.polar.sh second. If a scope is missing, connecting fails with a message naming it.

What is imported

• Orders from the last 90 days on the first run, then new orders every minute. Unpaid orders are checked again every 10 minutes for up to 30 days, and imported once paid.
• Refunds. New refunds update the order they belong to. A pending refund is read again once it settles.
• Renewals. An order with billing reason subscription_cycle is marked as a renewal.
• Subscription status, once an hour, when the token has subscriptions:read. Without it, retention falls back to payment recency.

How a payment finds its visitor

Virling reads virling_vid from, in order: the order's metadata, the order's custom field data, then the customer's metadata.

With a checkout session, set it in metadata:

const checkout = await polar.checkouts.create({
  products: "PRODUCT_ID",
  success_url: "https://yourdomain.com/thanks",
  metadata: { virling_vid: req.cookies.virling_vid },
});
// Send the customer to checkout.url

Checkout links

Checkout links on buy.polar.sh need no code beyond one setting:

1. In Polar, add a custom field with the slug virling_vid to the checkout link.
2. Keep the link as a normal <a href> on a page that runs the script.

When a visitor clicks it, the script adds custom_field_data.virling_vid=<visitor ID> to the link, unless it is already there, and Polar prefills the field.

Full reference: Polar in the docs.