Tutorials

How to integrate Polar into Next.js step by step

Complete technical guide to integrating Polar into a Next.js app: SDK, checkout, webhook, local testing, and common errors.

Israel Palma Sebastià

March 3, 2026

3 min read

Polar is one of the two most-used payment gateways in indie SaaS in 2026 (the other one is Stripe). Its big advantage: as Merchant of Record, it handles VAT for you. If you sell to Europe, it saves headaches.

This guide explains how to integrate Polar in a Next.js app step by step. It assumes you already have a Polar account and a product created.

Step 1: install the SDK

bun add @polar-sh/sdk

Step 2: configure environment variables

In your .env.local:

POLAR_ACCESS_TOKEN=polar_oat_...
POLAR_WEBHOOK_SECRET=whsec_...
POLAR_SERVER=production

For development, use POLAR_SERVER=sandbox. Sandbox keys are different, configure them in a .env.development.local.

Step 3: create the client

src/lib/polar/client.ts:

import { Polar } from '@polar-sh/sdk';

export const polar = new Polar({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  server: process.env.POLAR_SERVER as 'production' | 'sandbox',
});

Step 4: create the checkout endpoint

src/app/api/checkout/route.ts:

import { polar } from '@/lib/polar/client';
import { auth } from '@/lib/auth/server';
import { headers } from 'next/headers';
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { productId } = await req.json();

  const checkout = await polar.checkouts.create({
    productId,
    customerEmail: session.user.email,
    successUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/checkout/success`,
  });

  return NextResponse.json({ url: checkout.url });
}

Step 5: the webhook

Polar notifies you via webhook when someone pays, cancels, or when a subscription changes. Without a properly configured webhook, you don't find out and your DB goes out of sync.

src/app/api/webhooks/polar/route.ts:

import { polar } from '@/lib/polar/client';
import { db } from '@/lib/db/client';
import { headers } from 'next/headers';

export async function POST(req: Request) {
  const body = await req.text();
  const headersList = await headers();
  const signature = headersList.get('webhook-signature');

  // Verify signature
  const event = polar.webhooks.verify({
    body,
    signature: signature!,
    secret: process.env.POLAR_WEBHOOK_SECRET!,
  });

  switch (event.type) {
    case 'subscription.created':
      await db.subscription.create({
        data: {
          userId: event.data.metadata.userId,
          polarSubscriptionId: event.data.id,
          status: 'active',
        },
      });
      break;

    case 'subscription.canceled':
      await db.subscription.update({
        where: { polarSubscriptionId: event.data.id },
        data: { status: 'canceled' },
      });
      break;

    case 'order.created':
      // One-time purchase
      await db.purchase.create({
        data: {
          userId: event.data.metadata.userId,
          polarOrderId: event.data.id,
          amount: event.data.amount,
        },
      });
      break;
  }

  return new Response('OK', { status: 200 });
}

Step 6: testing locally

For Polar to send webhooks to localhost, use a tunnel like ngrok or Cloudflare Tunnel:

ngrok http 3000

Then configure the webhook URL in Polar Dashboard → Webhooks → your public ngrok URL + /api/webhooks/polar.

Any test purchase in sandbox triggers the webhook and you should see the event come in.

Step 7: the checkout button on the frontend

'use client';
import { useRouter } from 'next/navigation';

export function CheckoutButton({ productId }: { productId: string }) {
  const router = useRouter();

  async function handleCheckout() {
    const res = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ productId }),
    });
    const { url } = await res.json();
    router.push(url);
  }

  return <button onClick={handleCheckout}>Buy</button>;
}

Common errors

1. Webhook doesn't arrive: check that the public URL is reachable and the signing secret matches.

2. Invalid signature: make sure you pass the body as a raw string, not parsed, when verifying the signature.

3. User shows up but subscription doesn't: verify you pass metadata: { userId } when creating checkout. Without it, you don't know which user the subscription belongs to.

When Polar beats Stripe

You sell mostly to Europe
Monthly volume < €5,000
You want simplicity over advanced features
You don't want to deal with VAT at your accountant

If your volume grows a lot, Stripe becomes interesting again because of lower fees. But Polar is the fast option to start.

Bottom line

Integrating Polar in Next.js is ~150 lines of code if you already have auth. The webhook is the most delicate piece: spend time testing it in sandbox before going to production.

Once it works, you forget about VAT. And if you sell to Europe, that's worth its weight in gold.

Enjoyed this article?

Subscribe for more tutorials and tips on building products with AI

Step 1: install the SDK

Step 2: configure environment variables

Step 3: create the client

Step 4: create the checkout endpoint

Step 5: the webhook

Step 6: testing locally

Step 7: the checkout button on the frontend

Common errors

When Polar beats Stripe

Bottom line

Enjoyed this article?

Next.js 16 styling guide: Tailwind v4 + shadcn done right in 2026