Start free Open dashboard
Menu

Polar revenue analytics for Next.js

This guide adds ProductLense to a Next.js site and connects Polar, so every Polar payment is attributed to the channel, campaign and landing page that first brought the customer. It takes four steps and about ten minutes.

1. Add ProductLense to Next.js

The script goes in app/layout.tsx with next/script. Replace SITE_ID with the id from Settings → Sites.

app/layout.tsx
import Script from 'next/script';
import type { ReactNode } from 'react';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://api.productlense.app/a.js"
          data-site="SITE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

2. Identify signed-in users

app/productlense-identify.tsx
'use client';
import { useEffect } from 'react';

declare global {
  interface Window {
    productlense?: (...args: unknown[]) => void;
  }
}

export function ProductLenseIdentify({ userId, email }: { userId?: string; email?: string }) {
  useEffect(() => {
    if (userId) window.productlense?.('identify', userId, email ? { email } : undefined);
  }, [userId, email]);
  return null;
}

3. Connect Polar

Setup steps

  1. In Polar, open Settings → Developers and create an organization access token with the four read scopes.
  2. In ProductLense, open Settings → Billing connections → Polar and paste the token and organization id.
  3. In Polar → Settings → Webhooks, add a webhook endpoint with the URL ProductLense shows after you save the connection (pattern https://api.productlense.app/api/webhooks/{provider}/{connection_id}).
  4. Select the events listed below and paste the generated secret into ProductLense.
  5. ProductLense backfills 12 months of orders.

Credentials and permissions

FieldSecretWhere to find it
Organization access tokenYes, encrypted at restSettings → Developers → New token with customers:read, subscriptions:read, orders:read and organizations:read.
Organization IDNoThe UUID shown in Settings → General.
Webhook secretYes, encrypted at restThe secret generated when you add the webhook endpoint pointing at ProductLense.

Webhook

URL pattern, shown with your connection id after you save:

text
https://api.productlense.app/api/webhooks/polar/{connection_id}

Events: order.created, order.paid, order.updated, order.refunded, subscription.created, subscription.updated, subscription.active, customer.created, customer.updated, customer.state_changed

Verification: Standard Webhooks signature headers.

What ProductLense reads

Customers
Customers with email and external id.
Subscriptions
Subscriptions with status and interval.
Payments
Orders.
Refunds
The refunded amount on each order, plus refunded tax.
Fees
The platform fee amount when present on the order, otherwise 0.

What ProductLense never touches

  • Never creates, changes, refunds or cancels anything: read-only API calls and incoming webhooks only.
  • Never moves money, issues payouts, or reads bank account details.
  • Never sees full card numbers; providers do not expose them.
  • Never sends your customer data to the AI model: Ask and the daily insight see aggregates only.

Match payments to your users

Set the Polar customer external id to the id you pass to identify.

server: create a Polar checkout
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: [PRODUCT_ID], external_customer_id: user.id }),
});

Polar on Next.js: questions

Where does the ProductLense script go in Next.js?
In app/layout.tsx with next/script. Add the Script component to app/layout.tsx with strategy="afterInteractive" and data-site. The script is about 2.3 KB, loads with defer, sets no cookies, and records route changes in single-page apps through the history API, so no extra router code is needed.
How do I identify users in Next.js?
Call window.productlense('identify', userId) once the signed-in user is known, as in the app/productlense-identify.tsx example on this page. Use the same id you store on Polar as pl_user_id, so Polar payments match by id rather than by email.
Does ProductLense work with Polar?
Yes. ProductLense connects to Polar with organization access token, organization ID, webhook secret, backfills 12 months of history, and stays current through signed webhooks plus a nightly reconcile. One connection is included on Starter; Growth and Scale allow every provider at once on the same site.
What data does ProductLense read from Polar?
Customers, subscriptions, payments, refunds and fees, read-only. Payments: orders. Refunds: the refunded amount on each order, plus refunded tax. Fees: the platform fee amount when present on the order, otherwise 0.
Can ProductLense change anything in my Polar account?
No. ProductLense only makes read calls and receives webhooks. It never creates, changes, refunds or cancels anything, never moves money, and never sees card numbers. Credentials are encrypted at rest, and the AI features only ever see aggregated numbers, never your customers’ data.

Free up to 10k events a month. No card.

Add the script, connect Stripe or any of 14 other billing providers, and see revenue by channel the same day.

Start free Read the docs →