Polar Payments with Better Auth

Configure per-user Polar checkout and server-side entitlements in a Better Auth app.

This how-to is for developers adding per-user software as a service (SaaS) billing to a TypeScript Next.js application. It uses the App Router and assumes the application already uses Better Auth for authentication. Your goal is to create a server-owned Polar checkout and authorize paid access from Customer State. Polar’s externalId stores your application’s user identifier (ID) on the Polar customer.

This page implements one billing model: one Better Auth user maps to one Polar customer. Do not apply it unchanged to organizations, teams, or seat-based billing.

The request path has four responsibilities:

• Better Auth: authenticates the request and supplies the verified user ID
• Your server: creates or associates the Polar customer and fixes checkout policy
• Polar Customer State: returns active subscriptions and granted benefits
• Your authorization code: checks one stable benefit ID before protected work runs

Use the supported package set

This how-to pins the software development kit (SDK) and adapter versions that its imports target. The clean validation path also pins the framework and TypeScript toolchain.

1. Create a clean validation application

   Create a TypeScript App Router application with create-next-app 16.2.10. This exact version is available in the versioned Next.js package metadata. Skip this step when you are adding the integration to an existing application.

   npx create-next-app@16.2.10 polar-billing-check \
     --ts --app --src-dir --use-npm \
     --import-alias "@/*" --yes
   cd polar-billing-check
   
2. Install the pinned integration dependencies

   Install the exact versions used by every snippet on this page. The clean harness also pins React and TypeScript so another reader can reproduce the type check.

   npm install next@16.2.10 react@19.2.7 react-dom@19.2.7
   npm install better-auth@1.6.23 @polar-sh/better-auth@1.8.4
   npm install @polar-sh/sdk@0.47.1 better-sqlite3@12.11.1 zod@4.4.3
   npm install --save-dev typescript@5.8.3 @types/node@26.1.1
   npm install --save-dev @types/react@19.2.17 @types/react-dom@19.2.3
   npm install --save-dev @types/better-sqlite3@7.6.13
   

Adapter 1.8.4 declares @polar-sh/sdk ^0.47.0 and Better Auth ^1.4.12 in its release manifest. Keep the SDK on 0.47.x while you use this adapter version. The adapter 1.8.4 release includes the update to SDK 0.47.0.

Choose lazy customer creation before configuring Better Auth

This how-to sets createCustomerOnSignUp: false and creates the Polar customer on the first billing action. That policy keeps Polar availability out of signup and makes recovery explicit.

Adapter 1.8.4 uses two eager hooks when createCustomerOnSignUp is true. It creates or finds a customer before local user creation, then assigns externalId after local creation. See the pinned customer hooks.

The same adapter also registers a user-deletion hook in the pinned server integration. With eager creation enabled, that hook deletes the matching Polar customer after local deletion. Polar customer deletion immediately cancels active subscriptions, revokes benefits, and clears the external ID. Polar anonymizes personally identifiable information only when deletion uses anonymize=true.

Because this page uses lazy creation, the adapter does not perform that automatic customer deletion. Define your account-deletion policy separately before adding remote deletion to your application.

Prepare Polar and the application

Complete these prerequisites before you add application code. Use separate Polar sandbox and production resources so IDs cannot cross environments.

1. Create the product and access benefit

   Create a Polar product for the paid plan. Then create a Feature Flag benefit, which grants application feature access, and attach it to that product.

2. Create a scoped organization token

   Create a Polar Organization Access Token, which authenticates your server to the Polar application programming interface (API). Grant only the scopes used by this page:

   • customers:read
   • customers:write
   • checkouts:read
   • checkouts:write
   • customer_sessions:write
3. Protect signup before billing integration

   Keep email verification, signup rate limits, and your bot challenge enabled. Lazy creation prevents Polar calls during signup, but these controls still protect account creation.

4. Add local environment variables

   Set an explicit billing environment. Preview and staging deployments can set NODE_ENV=production, so do not use NODE_ENV as the Polar environment selector.

Use your application’s public uniform resource locator (URL) as APP_URL. The webhook secret is absent because this how-to does not configure webhooks.

BETTER_AUTH_SECRET=your_32_character_or_longer_secret_here
BETTER_AUTH_URL=http://localhost:3000
APP_URL=http://localhost:3000
POLAR_ENVIRONMENT=sandbox
POLAR_ACCESS_TOKEN=your_polar_access_token_here
POLAR_PRO_PRODUCT_ID=12345678-1234-4234-8234-123456789012
POLAR_PRO_BENEFIT_ID=23456789-2345-4345-8345-234567890123

Validate configuration at startup

Validate billing configuration once so route code can use typed values. The shared UUID schema also validates checkout identifiers later in the flow.

// src/lib/validation.ts
import { z } from "zod";

export const uuidSchema = z.string().uuid();

export const billingEnvSchema = z.object({
  APP_URL: z.string().url(),
  POLAR_ENVIRONMENT: z.enum(["sandbox", "production"]),
  POLAR_ACCESS_TOKEN: z.string().min(1),
  POLAR_PRO_PRODUCT_ID: uuidSchema,
  POLAR_PRO_BENEFIT_ID: uuidSchema,
});

Parse the environment and require APP_URL to be an origin without a path or query.

// src/lib/env.ts
import { billingEnvSchema } from "@/lib/validation";

const parsed = billingEnvSchema.parse(process.env);
const appUrl = new URL(parsed.APP_URL);

if (
  appUrl.username ||
  appUrl.password ||
  appUrl.pathname !== "/" ||
  appUrl.search ||
  appUrl.hash
) {
  throw new Error("APP_URL must contain only an origin");
}

export const env = Object.freeze({
  ...parsed,
  APP_URL: appUrl.origin,
});

Configure Better Auth and Polar

Create one Polar client for server code. Global retries stay disabled so write requests are never replayed automatically.

// src/lib/polar.ts
import { Polar } from "@polar-sh/sdk";

import { env } from "@/lib/env";

export const polarClient = new Polar({
  accessToken: env.POLAR_ACCESS_TOKEN,
  server: env.POLAR_ENVIRONMENT,
  timeoutMs: 3_000,
  retryConfig: { strategy: "none" },
});

Configure Better Auth with lazy Polar customer creation. Adapter 1.8.4 parses the portal return URL during initialization, so pass an absolute URL. The behavior is visible in the pinned portal source.

// src/lib/auth.ts
import { polar, portal } from "@polar-sh/better-auth";
import Database from "better-sqlite3";
import { betterAuth } from "better-auth";

import { env } from "@/lib/env";
import { polarClient } from "@/lib/polar";

export const auth = betterAuth({
  database: new Database("auth.db"),
  emailAndPassword: { enabled: true },
  plugins: [
    polar({
      client: polarClient,
      createCustomerOnSignUp: false,
      use: [
        portal({
          returnUrl: new URL("/settings/billing", env.APP_URL).toString(),
        }),
      ],
    }),
  ],
});

Mount the Better Auth handler at its documented Next.js App Router path. This mount also serves the Polar portal endpoint added by the adapter.

// src/app/api/auth/[...all]/route.ts
import { toNextJsHandler } from "better-auth/next-js";

import { auth } from "@/lib/auth";

export const { GET, POST } = toNextJsHandler(auth);

For a new SQLite-backed Better Auth application, create the required tables before starting the development server. Use the Better Auth migration command.

npx auth@latest migrate

Create or associate the customer on the first billing action

The first server-owned billing action must ensure that the signed-in user has one Polar customer. The helper below also recovers a customer that exists by email but lacks an external ID.

Import the generated error classes from their model paths. These paths target the exact SDK 0.47.1 package, so re-run the validation harness before changing the SDK.

// src/lib/billing/customer.ts
import { HTTPValidationError } from
  "@polar-sh/sdk/models/errors/httpvalidationerror.js";
import { ResourceNotFound } from
  "@polar-sh/sdk/models/errors/resourcenotfound.js";

import { polarClient } from "@/lib/polar";

export type BillingUser = {
  id: string;
  email: string;
  name: string;
};

export class PolarCustomerConflictError extends Error {}

Associate an email-matched customer only when its external ID is empty or already matches the local user. Polar requires each external ID to be unique and prevents changing it after assignment.

async function associateExistingCustomer(user: BillingUser) {
  const { result } = await polarClient.customers.list({
    email: user.email,
  });

  if (result.items.length === 0) return false;
  if (result.items.length !== 1) {
    throw new PolarCustomerConflictError("Customer email is not unique");
  }

  const customer = result.items[0];
  if (customer.externalId === user.id) return true;
  if (customer.externalId) {
    throw new PolarCustomerConflictError("Customer belongs to another user");
  }

  await polarClient.customers.update({
    id: customer.id,
    customerUpdate: { externalId: user.id },
  });
  return true;
}

Create a customer with the local user ID when no safe email match exists. A validation error triggers one lookup retry to handle a concurrent create request.

export async function ensurePolarCustomer(user: BillingUser) {
  try {
    await polarClient.customers.getStateExternal({ externalId: user.id });
    return;
  } catch (error) {
    if (!(error instanceof ResourceNotFound)) throw error;
  }

  if (await associateExistingCustomer(user)) return;

  try {
    await polarClient.customers.create({
      externalId: user.id,
      email: user.email,
      name: user.name,
    });
  } catch (error) {
    if (!(error instanceof HTTPValidationError)) throw error;
    if (await associateExistingCustomer(user)) return;
    throw error;
  }
}

Add a concrete checkout rate limiter

The local harness uses a fixed-window in-memory limiter so the route is runnable without another service. Replace this file with a shared-store implementation before deploying more than one application process.

// src/lib/billing/rate-limit.ts
const windowMs = 60_000;
const maxAttempts = 5;
const attempts = new Map<string, { count: number; resetAt: number }>();

export function allowBillingAttempt(userId: string) {
  const now = Date.now();
  const current = attempts.get(userId);

  if (!current || current.resetAt <= now) {
    attempts.set(userId, { count: 1, resetAt: now + windowMs });
    return true;
  }

  if (current.count >= maxAttempts) return false;
  current.count += 1;
  return true;
}

Create checkout from a server-owned route

Keep price-sensitive fields on the server. The browser sends only the plan key, while the server sets the product, discount policy, trial policy, and redirect URLs.

// src/lib/billing/checkout.ts
import type { BillingUser } from "@/lib/billing/customer";
import { ensurePolarCustomer } from "@/lib/billing/customer";
import { env } from "@/lib/env";
import { polarClient } from "@/lib/polar";

export async function createProCheckout(user: BillingUser) {
  await ensurePolarCustomer(user);

  return polarClient.checkouts.create({
    products: [env.POLAR_PRO_PRODUCT_ID],
    externalCustomerId: user.id,
    customerEmail: user.email,
    customerName: user.name,
    allowDiscountCodes: false,
    allowTrial: false,
    successUrl: new URL(
      "/billing/finish?checkout_id={CHECKOUT_ID}",
      env.APP_URL,
    ).toString(),
    returnUrl: new URL("/settings/billing", env.APP_URL).toString(),
  });
}

The route enforces four server-side controls before it creates a checkout:

• verifies the request origin for cross-site request forgery (CSRF) protection
• verifies the Better Auth session
• accepts only the pro plan key
• rate limits each authenticated user

It returns JavaScript Object Notation (JSON) containing only a server-created checkout URL.

// src/app/api/billing/checkout/route.ts
import { auth } from "@/lib/auth";
import { createProCheckout } from "@/lib/billing/checkout";
import { PolarCustomerConflictError } from
  "@/lib/billing/customer";
import { allowBillingAttempt } from "@/lib/billing/rate-limit";
import { env } from "@/lib/env";

export async function POST(request: Request) {
  if (request.headers.get("origin") !== env.APP_URL) {
    return Response.json({ error: "Invalid origin" }, { status: 403 });
  }

  const session = await auth.api.getSession({ headers: request.headers });
  if (!session) {
    return Response.json({ error: "Authentication required" }, { status: 401 });
  }

  const body = (await request.json().catch(() => null)) as
    | { plan?: unknown }
    | null;
  if (body?.plan !== "pro") {
    return Response.json({ error: "Unknown plan" }, { status: 400 });
  }

Finish the same route by applying the limiter and handling Polar failures. The handler discards every client field except plan.

  if (!allowBillingAttempt(session.user.id)) {
    return Response.json({ error: "Too many attempts" }, { status: 429 });
  }

  try {
    const checkout = await createProCheckout(session.user);
    return Response.json(
      { url: checkout.url },
      { headers: { "Cache-Control": "no-store" } },
    );
  } catch (error) {
    if (error instanceof PolarCustomerConflictError) {
      return Response.json(
        { error: "Billing account conflict" },
        { status: 409 },
      );
    }

    console.error("Unable to create Polar checkout", error);
    return Response.json(
      { error: "Billing is unavailable" },
      { status: 503 },
    );
  }
}

Add a client button that prevents duplicate browser submissions while checkout starts. Server validation remains the authorization and pricing boundary.

// src/components/upgrade-button.tsx
"use client";

import { useState } from "react";

export function UpgradeButton() {
  const [starting, setStarting] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function startCheckout() {
    if (starting) return;
    setStarting(true);
    setError(null);

    const response = await fetch("/api/billing/checkout", {
      method: "POST",
      credentials: "same-origin",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ plan: "pro" }),
    });

Handle the response and send the browser only to the server-provided checkout URL.

    const result = (await response.json()) as {
      url?: string;
      error?: string;
    };

    if (!response.ok || !result.url) {
      setError(result.error ?? "Unable to start checkout");
      setStarting(false);
      return;
    }

    window.location.assign(result.url);
  }

Render the disabled state and an accessible error message.

  return (
    <div>
      <button type="button" disabled={starting} onClick={startCheckout}>
        {starting ? "Opening checkout…" : "Upgrade to Pro"}
      </button>
      {error ? <p role="alert">{error}</p> : null}
    </div>
  );
}

Read Customer State and authorize on the server

Customer State returns the current subscriptions and granted benefits for one customer. Treat only a real 404 as “no Polar customer”; keep validation, rate-limit, timeout, and server failures distinct.

// src/lib/billing/state.ts
import type { CustomerState } from
  "@polar-sh/sdk/models/components/customerstate.js";
import { ResourceNotFound } from
  "@polar-sh/sdk/models/errors/resourcenotfound.js";

import { polarClient } from "@/lib/polar";

export async function getBillingState(userId: string) {
  try {
    return await polarClient.customers.getStateExternal({
      externalId: userId,
    });
  } catch (error) {
    if (error instanceof ResourceNotFound) return null;
    throw error;
  }
}

export type BillingState = CustomerState | null;

Authorize the stable benefit ID that you attached to the paid product. Product names and benefit metadata can change without changing this identifier.

// src/lib/billing/access.ts
import type { BillingState } from "@/lib/billing/state";
import { env } from "@/lib/env";

export function hasProAccess(state: BillingState) {
  return (
    state?.grantedBenefits.some(
      (benefit) => benefit.benefitId === env.POLAR_PRO_BENEFIT_ID,
    ) ?? false
  );
}

A protected server route must derive the user ID from the verified session. Return 503 when Polar cannot answer instead of converting an availability failure into a denied entitlement.

// src/app/api/pro-feature/route.ts
import { auth } from "@/lib/auth";
import { hasProAccess } from "@/lib/billing/access";
import { getBillingState } from "@/lib/billing/state";

export async function POST(request: Request) {
  const session = await auth.api.getSession({ headers: request.headers });
  if (!session) {
    return Response.json({ error: "Authentication required" }, { status: 401 });
  }

  try {
    const state = await getBillingState(session.user.id);
    if (!hasProAccess(state)) {
      return Response.json({ error: "Pro plan required" }, { status: 403 });
    }
  } catch (error) {
    console.error("Unable to verify Polar entitlement", error);
    return Response.json({ error: "Entitlement unavailable" }, { status: 503 });
  }

  return Response.json({ ok: true });
}

Route checkout completion from verified state

The success URL does not grant access. The application must verify the checkout identifier, the signed-in user, checkout ownership, checkout status, and Customer State.

The status endpoint returns one of four explicit results:

Checkout and Customer State	Response
open	{ state: "resume", location: checkout.url }
confirmed	{ state: "pending" }
succeeded with the Pro benefit	{ state: "ready", location: "/app" }
succeeded without the benefit	{ state: "pending" }
failed or expired	{ state: "failed", location: "/settings/billing" }

Define the response type next to the resolver so the browser and server share one contract.

// src/lib/billing/status.ts
import { polarClient } from "@/lib/polar";
import { hasProAccess } from "@/lib/billing/access";
import { getBillingState } from "@/lib/billing/state";

export type BillingStatus =
  | { state: "pending" }
  | { state: "ready" | "resume" | "failed"; location: string };

export class CheckoutOwnershipError extends Error {}

export async function resolveBillingStatus(
  userId: string,
  checkoutId: string,
): Promise<BillingStatus> {
  const checkout = await polarClient.checkouts.get({ id: checkoutId });
  if (checkout.externalCustomerId !== userId) {
    throw new CheckoutOwnershipError();
  }

Route each checkout status explicitly. Clicking Pay can produce confirmed, but only succeeded confirms checkout completion.

  if (checkout.status === "open") {
    return { state: "resume", location: checkout.url };
  }

  if (checkout.status === "confirmed") {
    return { state: "pending" };
  }

  if (checkout.status === "failed" || checkout.status === "expired") {
    return { state: "failed", location: "/settings/billing" };
  }

  if (checkout.status === "succeeded") {
    const state = await getBillingState(userId);
    if (hasProAccess(state)) {
      return { state: "ready", location: "/app" };
    }
  }

  return { state: "pending" };
}

Validate the universally unique identifier (UUID) before calling Polar. Return 404 for a missing checkout or an ownership mismatch, and 503 for other Polar failures.

// src/app/api/billing/status/route.ts
import { ResourceNotFound } from
  "@polar-sh/sdk/models/errors/resourcenotfound.js";

import { auth } from "@/lib/auth";
import {
  CheckoutOwnershipError,
  resolveBillingStatus,
} from "@/lib/billing/status";
import { uuidSchema } from "@/lib/validation";

export async function GET(request: Request) {
  const session = await auth.api.getSession({ headers: request.headers });
  if (!session) {
    return Response.json({ error: "Authentication required" }, { status: 401 });
  }

  const value = new URL(request.url).searchParams.get("checkout_id");
  const parsed = uuidSchema.safeParse(value);
  if (!parsed.success) {
    return Response.json({ error: "Invalid checkout ID" }, { status: 400 });
  }

Resolve the status without exposing another user’s checkout or accepting browser-provided destination URLs.

  try {
    const result = await resolveBillingStatus(session.user.id, parsed.data);
    return Response.json(result, {
      headers: { "Cache-Control": "no-store" },
    });
  } catch (error) {
    if (
      error instanceof ResourceNotFound ||
      error instanceof CheckoutOwnershipError
    ) {
      return Response.json({ error: "Checkout not found" }, { status: 404 });
    }

    console.error("Unable to resolve checkout status", error);
    return Response.json({ error: "Billing is unavailable" }, { status: 503 });
  }
}

Add a bounded finishing page

The finishing page polls only while the status is pending. It stops after 30s and lets the customer retry or return to billing settings.

// src/app/billing/finish/page.tsx
import { FinishingBilling } from "@/components/finishing-billing";

export default async function BillingFinishPage({
  searchParams,
}: {
  searchParams: Promise<{ checkout_id?: string }>;
}) {
  const { checkout_id: checkoutId } = await searchParams;
  return <FinishingBilling checkoutId={checkoutId ?? ""} />;
}

Define the response contract again in the client file so readers do not need to search backward for its shape.

// src/components/finishing-billing.tsx
"use client";

import { useEffect, useState } from "react";

type BillingStatus =
  | { state: "pending" }
  | { state: "ready" | "resume" | "failed"; location: string };

const sleep = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));

Poll with bounded exponential backoff. The browser follows only destinations returned by the server-owned status route.

async function pollBillingStatus(checkoutId: string) {
  const deadline = Date.now() + 30_000;
  let delay = 500;

  while (Date.now() < deadline) {
    const query = new URLSearchParams({ checkout_id: checkoutId });
    const response = await fetch(`/api/billing/status?${query}`, {
      credentials: "same-origin",
      cache: "no-store",
    });

    if (response.ok) {
      const result = (await response.json()) as BillingStatus;
      if (result.state !== "pending") return result;
    } else if (response.status !== 503) {
      throw new Error("Unable to verify checkout");
    }

    await sleep(delay);
    delay = Math.min(delay * 2, 5_000);
  }

  return null;
}

Run the poll when the component mounts or the customer clicks Try again.

export function FinishingBilling({ checkoutId }: { checkoutId: string }) {
  const [attempt, setAttempt] = useState(0);
  const [message, setMessage] = useState("Verifying payment…");

  useEffect(() => {
    let active = true;

    void pollBillingStatus(checkoutId)
      .then((result) => {
        if (!active) return;
        if (result) window.location.assign(result.location);
        else setMessage("Payment is taking longer than expected.");
      })
      .catch(() => {
        if (active) setMessage("We could not verify this checkout.");
      });

    return () => {
      active = false;
    };
  }, [attempt, checkoutId]);

Render a finite recovery path instead of an endless loading state.

  return (
    <div>
      <p role="status">{message}</p>
      <button type="button" onClick={() => setAttempt((value) => value + 1)}>
        Try again
      </button>
      <a href="/settings/billing">Back to billing</a>
    </div>
  );
}

Add the customer portal client

The portal plugin adds authenticated customer methods to the Better Auth client. This client lets a customer open Polar’s hosted billing portal after a Polar customer exists.

// src/lib/auth-client.ts
import { polarClient } from "@polar-sh/better-auth/client";
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  plugins: [polarClient()],
});

Call the portal method from an authenticated client component after Customer State exists. Hide this button before the first billing action creates or associates the Polar customer.

// src/components/manage-billing-button.tsx
"use client";

import { authClient } from "@/lib/auth-client";

export function ManageBillingButton() {
  return (
    <button
      type="button"
      onClick={() => void authClient.customer.portal()}
    >
      Manage billing
    </button>
  );
}

Webhooks are not required for this implementation because every authorization decision reads Customer State directly. Add Polar webhooks only when another feature requires asynchronous delivery.

Validate the integration

The pinned setup at the start of this page is the local type-check harness. Copy every snippet into its documented file path, add the environment variables, and add this script to package.json.

npm pkg set scripts.typecheck="tsc --noEmit"
npm run typecheck

Before publishing or deploying the integration, verify this path end to end:

• Install the pinned Better Auth, adapter, and SDK versions from a clean lockfile
• Run the Better Auth database migration and start the Next.js application
• Sign in, start checkout, and verify the server ignores extra browser fields
• Confirm a new billing action creates one customer with the local user ID as externalId
• Confirm an email-matched customer with no external ID becomes associated once
• Reject a customer whose existing external ID belongs to another local user
• Return 401 without a valid session and 429 after five checkout attempts per minute
• Reject malformed checkout IDs and another user’s checkout with 404
• Route open, confirmed, succeeded, failed, and expired checkout states as documented
• Grant protected access only after Customer State contains POLAR_PRO_BENEFIT_ID
• Return 503 when Polar cannot provide the entitlement decision
• Verify the 30s finishing flow stops polling and offers a retry path
• Run npm run typecheck with every published TypeScript and TSX snippet in place