Polar billing with Better Auth

This how-to adds per-user software as a service (SaaS) subscription billing to a TypeScript Next.js App Router application that already uses Better Auth. It creates checkout on the server and authorizes paid access from Polar Customer State. The identity invariant is one Better Auth user to one Polar customer. Polar’s externalId stores the immutable application user identifier (ID) on that customer. Email is used only for a verified, one-time recovery association when an existing Polar customer has no external ID. Do not apply this model unchanged to organizations, teams, shared accounts, or seat-based billing. The request path has four responsibilities:

Better Auth: authenticates the request and proves email ownership before any email-based customer association.
Your server: creates or associates the Polar customer and sets the allowed product, discounts, trials, customer IP address, and redirect URLs.
Polar Customer State: returns the current customer and granted benefits.
Your authorization code: checks one stable benefit ID before protected work runs.

The implementation follows this order:

Pin the integration and local validation environment.
Define the customer lifecycle and recurring product.
Validate environment configuration.
Add the Polar plugin to the existing Better Auth configuration.
Create or safely associate a verified customer’s Polar record.
Add bounded local rate limits and Customer State caching.
Create checkout from a server-owned route.
Authorize protected work from Customer State.
Resolve checkout completion from verified server state.
Add abortable, bounded client polling and portal recovery.
Run build and sandbox validation before deployment.

Use the supported package set

The integration examples target exact Better Auth, Polar adapter, and Polar SDK versions. The optional validation harness is a disposable runnable application, not a production database or a replacement for your existing auth setup. For an existing application, keep its current Better Auth installation in place. The snippets on this page were validated with Better Auth 1.6.23; do not silently replace a working auth version just to follow the billing setup. Install the missing integration dependencies with exact versions:

npm install --save-exact @polar-sh/better-auth@1.8.4 \
  @polar-sh/sdk@0.47.1 zod@4.4.3
npm ls better-auth

If npm ls reports a Better Auth version other than 1.6.23, confirm adapter compatibility and run the full validation path before deployment. Skip framework, React, database, and TypeScript replacement when your application already supplies them. For the clean validation harness, use Node.js 22.19.0 with npm 10.9.3. Next.js 16 requires Node.js 20.9 or newer, and this harness keeps the runtime and Node type declarations on the same major version.

Create the validation application

Create a TypeScript App Router application with create-next-app 16.2.10. The executable package version is available in the create-next-app registry metadata.

npx create-next-app@16.2.10 polar-billing-check \
  --ts --app --src-dir --use-npm \
  --import-alias "@/*" --yes
cd polar-billing-check

Pin the harness runtime and package manager

Record the exact local runtime, then make npm save exact dependency versions.

printf '22.19.0\n' > .nvmrc
npm pkg set engines.node="22.19.0"
npm pkg set packageManager="npm@10.9.3"
npm config set save-exact true --location=project

Install harness-only dependencies

Install the framework, integration, SQLite, and matching type packages used by the runnable example.

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 -D typescript@5.8.3 @types/node@22.19.21
npm install -D @types/react@19.2.17 @types/react-dom@19.2.3
npm install -D @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 pinned release manifest. Keep the SDK on 0.47.x while using this adapter version. Also keep the canonical Better Auth Polar plugin documentation for supported usage and the pinned source only for version-specific behavior.

Choose the customer lifecycle before configuring Better Auth

This guide uses createCustomerOnSignUp: false so signup does not depend on Polar availability. Lazy creation also means the adapter’s customer create, profile synchronization, and delete hooks are not your lifecycle policy. With eager creation enabled, adapter 1.8.4 runs customer hooks around Better Auth user operations. Those hooks are best-effort synchronization: they depend on Better Auth operation context, and remote deletion can fail after the local user has already been deleted. See the pinned customer hooks. Define these policies before deploying lazy creation:

Email and name changes: update the Polar customer by its existing external ID after the local change is verified. Do not reassign ownership by email.
Account deletion: decide whether to retain, delete, or anonymize the Polar customer. Deleting a customer can cancel subscriptions and revoke benefits; use the versioned Delete Customer API only when that matches your product policy.
Account recreation: a new local user ID is a new identity. Do not let a new account take over a Polar customer whose external ID points to the deleted ID. Reconcile the record through an authenticated support or administrative flow.
Account merge: choose the surviving local user ID first, then reconcile the Polar customer deliberately. Never infer a merge only from matching email.

Prepare Polar and the application

Create a recurring subscription product for the paid plan, not a one-time purchase. A Feature Flag benefit attached to a recurring product follows the subscription lifecycle, while a one-time purchase can grant the benefit permanently. See Feature Flag benefits.

Create the recurring product and access benefit

Create the recurring Polar product, then attach one Feature Flag benefit for the application capability this guide calls Pro access. Copy both IDs.

Create a scoped organization token

Create a Polar Organization Access Token and grant only the scopes used here:

customers:read
customers:write
checkouts:read
checkouts:write
customer_sessions:write

Keep verified-email signup controls enabled

The email recovery association later in this guide is safe only after the application has proved ownership of the session email. Keep signup rate limits, bot controls, and email verification enabled.For email and password, configure emailVerification.sendVerificationEmail and emailAndPassword.requireEmailVerification: true. For social sign-in, enable the provider-specific requireEmailVerification option only for providers that report a trustworthy verification claim. Otherwise, require a separate verified email step before billing.

Generate a high-entropy Better Auth secret instead of copying a sample value. For the pinned version in this guide, run:

npx auth@1.6.23 secret

Use one canonical application origin. This guide passes APP_URL directly to Better Auth instead of maintaining a second BETTER_AUTH_URL value.

BETTER_AUTH_SECRET=<generated-secret>
APP_URL=http://localhost:3000
POLAR_ENVIRONMENT=sandbox
POLAR_ACCESS_TOKEN=<sandbox-token>
POLAR_PRO_PRODUCT_ID=12345678-1234-4234-8234-123456789012
POLAR_PRO_BENEFIT_ID=23456789-2345-4345-8345-567890123456
CUSTOMER_IP_HEADER=

CUSTOMER_IP_HEADER is empty in the local sandbox. In production, set it to the header your trusted ingress overwrites with the connecting customer IP. Do not trust a client-controlled forwarded header. Polar uses the request IP for country, currency, billing-country prefilling, and preliminary tax behavior when checkout is created from a backend.

Validate configuration at startup

Validate configuration once so route code uses typed values. The shared universally unique identifier (UUID) schema also validates checkout IDs later. Production requires HTTPS and a configured trusted customer-IP header.

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

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

export const billingEnvSchema = z.object({
  BETTER_AUTH_SECRET: z.string().min(32),
  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,
  CUSTOMER_IP_HEADER: z.string().regex(/^[a-z0-9-]*$/),
});

Parse the origin and apply production-only requirements explicitly.

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

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

if (appUrl.pathname !== "/" || appUrl.search || appUrl.hash) {
  throw new Error("APP_URL must contain only an origin");
}
if (appUrl.username || appUrl.password) {
  throw new Error("APP_URL cannot contain credentials");
}
if (appUrl.protocol !== "http:" && appUrl.protocol !== "https:") {
  throw new Error("APP_URL must use HTTP or HTTPS");
}
if (parsed.POLAR_ENVIRONMENT === "production") {
  if (appUrl.protocol !== "https:") throw new Error("HTTPS is required");
  if (!parsed.CUSTOMER_IP_HEADER) {
    throw new Error("CUSTOMER_IP_HEADER is required in production");
  }
}

Export normalized values and turn an empty sandbox IP header into undefined.

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

Configure Better Auth and Polar

Add the Polar plugin to your existing Better Auth configuration without replacing its database adapter, auth methods, session policy, trusted origins, providers, or hooks. The full SQLite configuration below exists only for the clean harness. Create one Polar client for server code. Global retries remain 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" },
});

Define the Polar billing plugin separately so an existing app can append the same plugin to its current plugins array.

// src/lib/auth.ts
import { polar, portal } from "@polar-sh/better-auth";
import { env } from "@/lib/env";
import { polarClient } from "@/lib/polar";

import { billingRoutes } from "@/lib/billing/routes";

const polarBilling = polar({
  client: polarClient,
  createCustomerOnSignUp: false,
  use: [
    portal({
      returnUrl: new URL(billingRoutes.settings, env.APP_URL).toString(),
    }),
  ],
});

In your existing application, add polarBilling to the existing plugins array and keep the rest of your auth configuration unchanged. Also ensure every auth method that can reach billing produces a verified local email before association. The clean harness uses SQLite and logs verification links only in sandbox. Never use this database or console delivery as a production starting point.

import Database from "better-sqlite3";
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  baseURL: env.APP_URL,
  secret: env.BETTER_AUTH_SECRET,
  database: new Database("auth.db"),
  emailVerification: {
    sendVerificationEmail: async ({ user, url }) => {
      if (env.POLAR_ENVIRONMENT === "production") {
        throw new Error("Configure transactional email before production");
      }
      console.info(`Verify ${user.email}: ${url}`);
    },
    sendOnSignUp: true,
    sendOnSignIn: true,
  },
  emailAndPassword: { enabled: true, requireEmailVerification: true },
  plugins: [polarBilling],
});

Mount the Better Auth handler at its documented 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 the clean harness only, create the SQLite schema with the CLI version that matches the deployed Better Auth version. Do not use a mutable latest CLI for a schema migration.

npx auth@1.6.23 migrate
printf '\nauth.db\nauth.db-*\n' >> .gitignore

auth.db is local-only. A relative SQLite file is not suitable for typical serverless, ephemeral, or multi-process deployment, and it can contain user and session data after testing. Production must keep the application’s existing production-grade database configuration.

Create or associate the customer on the first billing action

The first billing action must ensure the verified signed-in user maps to exactly one Polar customer. Email recovery is allowed only when the local email is verified and the matching Polar customer has no external ID. Import the generated SDK error classes from their pinned model paths. These deep imports target SDK 0.47.1, so re-run validation 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;
  emailVerified: boolean;
  name: string;
};

Reject unverified identities inside the helper as defense in depth, even though billing routes also reject them before calling this code.

export class EmailVerificationRequiredError extends Error {}
export class PolarCustomerConflictError extends Error {}

function assertVerifiedUser(user: BillingUser) {
  if (!user.emailVerified) {
    throw new EmailVerificationRequiredError();
  }
}

Associate an email-matched customer only when exactly one match exists and its external ID is empty or already matches the local user. Polar external IDs are unique and should be treated as immutable ownership identifiers.

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 has another owner");
  }

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

Create a customer only after the verified email lookup fails. A 422 does not become success by itself: the helper performs one read-after-write recovery lookup and rethrows the original validation error unless that lookup proves the customer is now safely owned by this user. This bounds the concurrency recovery path without treating arbitrary invalid data as a successful create.

export async function ensurePolarCustomer(user: BillingUser) {
  assertVerifiedUser(user);
  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;
  }
}

After initial association, synchronize verified profile changes by external ID in your own account-update flow. Do not use this email recovery helper as a general profile synchronization mechanism.

Add bounded local API controls

The harness uses process-local controls so it can run without another service. Production with multiple processes must replace them with shared implementations. A distributed rate-limit consume/reset operation must be atomic; a remote read-then-write sequence is not sufficient. Use one bounded fixed-window helper for checkout, status polling, and protected feature routes. It removes expired entries during periodic sweeps and returns a retry delay for Retry-After.

// src/lib/billing/rate-limit.ts
const buckets = new Map<string, { count: number; resetAt: number }>();
let nextSweep = 0;

export function consumeRateLimit(key: string, max: number, windowMs = 60_000) {
  const now = Date.now();
  if (now >= nextSweep) {
    for (const [name, value] of buckets) {
      if (value.resetAt <= now) buckets.delete(name);
    }
    nextSweep = now + 60_000;
  }

  const current = buckets.get(key);
  if (!current || current.resetAt <= now) {
    buckets.set(key, { count: 1, resetAt: now + windowMs });
    return { allowed: true, retryAfter: 0 };
  }
  const retryAfter = Math.ceil((current.resetAt - now) / 1_000);
  if (current.count >= max) return { allowed: false, retryAfter };
  current.count += 1;
  return { allowed: true, retryAfter };
}

Customer State is latency-sensitive and authorization-sensitive. This harness uses a three-second per-user cache to reduce repeated Polar calls. That creates up to three seconds of entitlement staleness, so choose a shorter, longer, or zero TTL according to your revocation requirements.

// 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 type BillingState = CustomerState | null;
const cache = new Map<string, { value: BillingState; expiresAt: number }>();
const ttlMs = 3_000;
const maxEntries = 1_000;

export async function getBillingState(userId: string): Promise<BillingState> {
  const cached = cache.get(userId);
  if (cached && cached.expiresAt > Date.now()) return cached.value;
  let value: BillingState;
  try {
    value = await polarClient.customers.getStateExternal({
      externalId: userId,
    });
  } catch (error) {
    if (!(error instanceof ResourceNotFound)) throw error;
    value = null;
  }

Bound the local cache instead of allowing it to grow with every distinct user.

  cache.delete(userId);
  cache.set(userId, { value, expiresAt: Date.now() + ttlMs });
  while (cache.size > maxEntries) {
    const oldest = cache.keys().next().value as string | undefined;
    if (!oldest) break;
    cache.delete(oldest);
  }
  return value;
}

The SDK timeout, short cache, and per-user route limits bound local latency and API consumption. Higher-volume production systems should use a shared cache, organization-wide budgets, and a circuit breaker so a Polar outage does not turn all application traffic into synchronized upstream calls.

Create checkout from a server-owned route

Keep price-sensitive fields on the server. The browser sends only the plan key; the server sets the product, discount policy, trial policy, customer identity, customer IP address, and redirect URLs. Define application-specific route constants once so examples cannot drift. Replace these values when your application uses different paths.

// src/lib/billing/routes.ts
export const billingRoutes = {
  signIn: "/sign-in",
  settings: "/settings/billing",
  app: "/app",
  finish: "/billing/finish",
} as const;

Read the customer IP only from a header guaranteed by your deployment ingress. For comma-separated trusted forwarding headers, this example uses the first address after the trusted proxy has overwritten client input.

// src/lib/billing/request.ts
import { isIP } from "node:net";
import { env } from "@/lib/env";

export function hasValidOrigin(request: Request) {
  return request.headers.get("origin") === env.APP_URL;
}

export function getTrustedCustomerIp(request: Request) {
  if (!env.CUSTOMER_IP_HEADER) return undefined;
  const raw = request.headers.get(env.CUSTOMER_IP_HEADER);
  const value = raw?.split(",")[0]?.trim();
  if (!value || isIP(value) === 0) {
    throw new Error("Trusted customer IP is unavailable");
  }
  return value;
}

Pass that IP into Polar checkout creation. Polar documents this requirement for backend and Next.js route-handler checkout creation in its Checkout API guide.

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

export async function createProCheckout(
  user: BillingUser,
  customerIpAddress?: string,
) {
  await ensurePolarCustomer(user);
  return polarClient.checkouts.create({
    products: [env.POLAR_PRO_PRODUCT_ID],
    externalCustomerId: user.id,
    customerEmail: user.email,
    customerName: user.name,
    customerIpAddress,

Finish the checkout policy with server-owned discount, trial, and redirect settings.

    allowDiscountCodes: false,
    allowTrial: false,
    successUrl: new URL(
      `${billingRoutes.finish}?checkout_id={CHECKOUT_ID}`,
      env.APP_URL,
    ).toString(),
    returnUrl: new URL(billingRoutes.settings, env.APP_URL).toString(),
  });
}

Classify durable Polar configuration failures separately from transient upstream failures while keeping public error messages generic.

// src/lib/billing/polar-errors.ts
export function polarErrorKind(error: unknown) {
  if (!error || typeof error !== "object") return "transient";
  const record = error as Record<string, unknown>;
  const raw = record.statusCode ?? record.status;
  const status = typeof raw === "number" ? raw : undefined;
  if (status === 401 || status === 403 || status === 422) {
    return "configuration";
  }
  return "transient";
}

The checkout route enforces same-origin POST requests, a verified session, one plan key, and a per-user rate limit before creating checkout.

// src/app/api/billing/checkout/route.ts
import { auth } from "@/lib/auth";
import { createProCheckout } from "@/lib/billing/checkout";
import { consumeRateLimit } from "@/lib/billing/rate-limit";
import { getTrustedCustomerIp, hasValidOrigin } from
  "@/lib/billing/request";

export async function POST(request: Request) {
  if (!hasValidOrigin(request)) {
    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 });
  }
  if (!session.user.emailVerified) {
    return Response.json({ error: "Verify your email" }, { status: 403 });
  }
  const body = await request.json().catch(() => null) as
    | { plan?: unknown }
    | null;
  if (body?.plan !== "pro") {
    return Response.json({ error: "Unknown plan" }, { status: 400 });
  }

Apply the rate limit and include Retry-After when it is exceeded.

  const limit = consumeRateLimit(`checkout:${session.user.id}`, 5);
  if (!limit.allowed) {
    return Response.json(
      { error: "Too many attempts" },
      {
        status: 429,
        headers: { "Retry-After": String(limit.retryAfter) },
      },
    );
  }

  try {
    const customerIp = getTrustedCustomerIp(request);
    const checkout = await createProCheckout(session.user, customerIp);
    return Response.json(
      { url: checkout.url },
      { headers: { "Cache-Control": "no-store" } },
    );

Handle ownership conflicts, permanent configuration defects, and transient Polar failures separately in logs and status codes.

  } catch (error) {
    const { PolarCustomerConflictError } = await import(
      "@/lib/billing/customer"
    );
    if (error instanceof PolarCustomerConflictError) {
      return Response.json(
        { error: "Billing account conflict" },
        { status: 409 },
      );
    }

    const { polarErrorKind } = await import("@/lib/billing/polar-errors");
    const kind = polarErrorKind(error);
    console.error("Unable to create Polar checkout", { kind, error });
    return Response.json(
      { error: kind === "configuration"
          ? "Billing configuration error"
          : "Billing is unavailable" },
      { status: kind === "configuration" ? 500 : 503 },
    );
  }
}

The dynamic imports above keep each teaching block short. In application code, normal top-level imports are preferable. Add a client button that always resets its disabled state on non-navigation exits, including network failure and invalid JSON.

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

Validate the response shape before navigation and catch all non-navigation failures.

      const json = await response.json().catch(() => null) as
        | { url?: unknown; error?: unknown }
        | null;
      if (!response.ok || typeof json?.url !== "string") {
        const message = typeof json?.error === "string"
          ? json.error
          : "Unable to start checkout";
        throw new Error(message);
      }
      window.location.assign(json.url);
    } catch (cause) {
      setError(cause instanceof Error ? cause.message : "Checkout failed");
    } finally {
      setStarting(false);
    }
  }

Render disabled and accessible error states.

  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 is the authorization source. Only ResourceNotFound from the Customer State request means that no Polar customer exists; validation, timeout, rate-limit, and server failures must propagate as availability failures. Authorize the stable benefit ID attached to the recurring product.

// 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 state-changing protected POST route applies the same Origin check as checkout, then rate limits each authenticated user before making a Customer State request.

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

export async function POST(request: Request) {
  if (!hasValidOrigin(request)) {
    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 limit = consumeRateLimit(`feature:${session.user.id}`, 60);
  if (!limit.allowed) {
    return Response.json(
      { error: "Too many requests" },
      { status: 429, headers: { "Retry-After": String(limit.retryAfter) } },
    );
  }

Fail closed on authorization while distinguishing Polar unavailability from a genuine missing entitlement.

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

Route checkout completion from verified state

The success URL never grants access. The server verifies the checkout ID, signed-in user, checkout ownership, checkout status, and Customer State before the browser can proceed. Define one client-safe runtime contract instead of duplicating a TypeScript type. There are five distinct response states: pending, ready, resume, failed, and support.

// src/lib/billing/status-contract.ts
import { z } from "zod";

export const billingStatusSchema = z.discriminatedUnion("state", [
  z.object({ state: z.literal("pending") }),
  z.object({
    state: z.literal("resume"),
    location: z.string().url(),
  }),
  z.object({
    state: z.enum(["ready", "failed"]),
    location: z.string().startsWith("/"),
  }),
  z.object({
    state: z.literal("support"),
    message: z.string().min(1),
  }),
]);

export type BillingStatus = z.infer<typeof billingStatusSchema>;

Resolve ownership before interpreting checkout state. The current versioned Polar reference is Get Checkout Session.

// src/lib/billing/status.ts
import type { BillingStatus } from "@/lib/billing/status-contract";
import { hasProAccess } from "@/lib/billing/access";
import { billingRoutes } from "@/lib/billing/routes";
import { getBillingState } from "@/lib/billing/state";
import { polarClient } from "@/lib/polar";

export class CheckoutOwnershipError extends Error {}
const benefitGraceMs = 30_000;

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 open, confirmed, failed, and expired checkouts explicitly. confirmed only means the customer clicked Pay; it does not prove payment success.

  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: billingRoutes.settings };
  }

A succeeded checkout gets a bounded grace period for Customer State propagation. After the grace period, missing the configured benefit becomes an actionable support/configuration state instead of pending forever.

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

    const changedAt = checkout.modifiedAt ?? checkout.createdAt;
    const age = Date.now() - Date.parse(String(changedAt));
    if (age < benefitGraceMs) return { state: "pending" };

    console.error("Succeeded checkout missing expected benefit", {
      checkoutId,
      userId,
    });
    return {
      state: "support",
      message:
        "Payment succeeded, but Pro access is not available. Contact support.",
    };
  }
  return { state: "pending" };
}

The status endpoint validates the UUID before Polar, rate limits each user, masks ownership mismatches as 404, and returns 400 for malformed IDs.

// src/app/api/billing/status/route.ts
import { ResourceNotFound } from
  "@polar-sh/sdk/models/errors/resourcenotfound.js";
import { auth } from "@/lib/auth";
import { consumeRateLimit } from "@/lib/billing/rate-limit";
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 limit = consumeRateLimit(`status:${session.user.id}`, 20);
  if (!limit.allowed) {
    return Response.json(
      { error: "Too many status requests" },
      { status: 429, headers: { "Retry-After": String(limit.retryAfter) } },
    );
  }

Validate and resolve the request without exposing another user’s checkout.

  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 });
  }

  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 an abortable finishing page

The browser polls only while the server returns pending. Every attempt has a strict 30-second deadline, each fetch has an abort signal, cleanup cancels the active loop, and retry cannot start a second concurrent loop. The server component passes the checkout ID to the client component.

// 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 ?? ""} />;
}

Use one abortable delay helper.

// src/components/finishing-billing.tsx
"use client";
import { useEffect, useState } from "react";
import { billingRoutes } from "@/lib/billing/routes";
import { billingStatusSchema } from "@/lib/billing/status-contract";

function abortableSleep(ms: number, signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    const onAbort = () => {
      clearTimeout(timer);
      reject(new DOMException("Aborted", "AbortError"));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", onAbort);
      resolve();
    }, ms);
    signal.addEventListener("abort", onAbort, { once: true });
  });
}

Poll with bounded exponential backoff. The remaining deadline limits both the fetch timeout and the final sleep, so the attempt does not run beyond 30 seconds.

async function pollBillingStatus(checkoutId: string, signal: AbortSignal) {
  const deadline = Date.now() + 30_000;
  let delay = 500;
  while (Date.now() < deadline) {
    const remaining = deadline - Date.now();
    const requestSignal = AbortSignal.any([
      signal,
      AbortSignal.timeout(Math.min(3_000, remaining)),
    ]);
    const query = new URLSearchParams({ checkout_id: checkoutId });
    const response = await fetch(`/api/billing/status?${query}`, {
      credentials: "same-origin",
      cache: "no-store",
      signal: requestSignal,
    });
    if (response.ok) {
      const json = await response.json().catch(() => null);
      const parsed = billingStatusSchema.safeParse(json);
      if (!parsed.success) throw new Error("Invalid billing response");
      if (parsed.data.state !== "pending") return parsed.data;
    } else if (response.status !== 503) {
      throw new Error("Checkout verification failed");
    }

Bound the delay by the remaining deadline.

    const remainingAfterFetch = deadline - Date.now();
    if (remainingAfterFetch <= 0) break;
    await abortableSleep(Math.min(delay, remainingAfterFetch), signal);
    delay = Math.min(delay * 2, 5_000);
  }
  return null;
}

Each effect owns one AbortController. Cleanup cancels the request and any sleep, including React development Strict Mode cleanup. The retry button is disabled while an attempt is active.

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

  useEffect(() => {
    const controller = new AbortController();
    setPolling(true);
    setMessage("Verifying payment…");
    void pollBillingStatus(checkoutId, controller.signal)
      .then((result) => {
        if (controller.signal.aborted) return;
        if (!result) {
          setMessage("Payment is taking longer than expected.");
        } else if (result.state === "support") {
          setMessage(result.message);
        } else {
          window.location.assign(result.location);
        }
      })

Ignore expected aborts, surface other failures, and reset the polling state only for the currently active attempt.

      .catch((error) => {
        if (controller.signal.aborted) return;
        console.error("Checkout polling failed", error);
        setMessage(
          "Checkout verification failed. Try again or return to billing.",
        );
      })
      .finally(() => {
        if (!controller.signal.aborted) setPolling(false);
      });
    return () => controller.abort();
  }, [attempt, checkoutId]);

  function retry() {
    setMessage("Verifying payment…");
    setPolling(true);
    setAttempt((value) => value + 1);
  }

Render a finite recovery path. Clicking retry resets the message before starting the next, non-overlapping attempt.

  return (
    <div>
      <p role="status">{message}</p>
      <button
        type="button"
        disabled={polling}
        onClick={retry}
      >
        {polling ? "Verifying…" : "Try again"}
      </button>
      <a href={billingRoutes.settings}>Back to billing</a>
    </div>
  );
}

Add the customer portal and runnable harness pages

The Polar portal should be offered only after Customer State proves a Polar customer exists. The client must also surface portal failures instead of discarding them. Create the Better Auth client once for sign-in, signup, and Polar portal methods.

// 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()],
});

Handle portal loading and errors in the client component.

// src/components/manage-billing-button.tsx
"use client";
import { useState } from "react";
import { authClient } from "@/lib/auth-client";

export function ManageBillingButton() {
  const [opening, setOpening] = useState(false);
  const [error, setError] = useState<string | null>(null);
  async function openPortal() {
    setOpening(true);
    setError(null);
    try {
      const result = await authClient.customer.portal();
      if (result.error) {
        setError(result.error.message ?? "Unable to open billing portal");
      }
    } catch {
      setError("Unable to open billing portal");
    } finally {
      setOpening(false);
    }
  }

Render the disabled state and an accessible portal error.

  return (
    <div>
      <button type="button" disabled={opening} onClick={openPortal}>
        {opening ? "Opening…" : "Manage billing"}
      </button>
      {error ? <p role="alert">{error}</p> : null}
    </div>
  );
}

The billing settings page renders Upgrade for users without Pro access and hides Manage billing until a Polar customer exists.

// src/app/settings/billing/page.tsx
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { UpgradeButton } from "@/components/upgrade-button";
import { ManageBillingButton } from "@/components/manage-billing-button";
import { auth } from "@/lib/auth";
import { hasProAccess } from "@/lib/billing/access";
import { billingRoutes } from "@/lib/billing/routes";
import { getBillingState } from "@/lib/billing/state";

export default async function BillingSettingsPage() {
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session) redirect(billingRoutes.signIn);
  const state = await getBillingState(session.user.id);
  const pro = hasProAccess(state);
  return (
    <main>
      <h1>Billing</h1>
      {!pro ? <UpgradeButton /> : <p>Pro access is active.</p>}
      {state ? <ManageBillingButton /> : null}
    </main>
  );
}

The protected application page checks Customer State server-side rather than trusting the checkout redirect.

// src/app/app/page.tsx
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { auth } from "@/lib/auth";
import { hasProAccess } from "@/lib/billing/access";
import { billingRoutes } from "@/lib/billing/routes";
import { getBillingState } from "@/lib/billing/state";

export default async function AppPage() {
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session) redirect(billingRoutes.signIn);
  const state = await getBillingState(session.user.id);
  if (!hasProAccess(state)) redirect(billingRoutes.settings);
  return <main><h1>Pro application</h1></main>;
}

For the clean harness, add minimal signup and sign-in controls so the validation path is runnable. The sandbox auth configuration prints verification links to the server console; production must use a transactional email provider.

// src/components/sign-up-form.tsx
"use client";
import { useState } from "react";
import type { FormEvent } from "react";
import { authClient } from "@/lib/auth-client";

export function SignUpForm() {
  const [message, setMessage] = useState("");
  async function submit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    const result = await authClient.signUp.email({
      name: String(data.get("name")),
      email: String(data.get("email")),
      password: String(data.get("password")),
    });
    setMessage(
      result.error ? result.error.message : "Check your email to verify.",
    );
  }

Render the signup fields.

  return (
    <form onSubmit={submit}>
      <h2>Create account</h2>
      <input name="name" required aria-label="Name" />
      <input name="email" type="email" required aria-label="Email" />
      <input name="password" type="password" required aria-label="Password" />
      <button type="submit">Sign up</button>
      <p role="status">{message}</p>
    </form>
  );
}

Add a sign-in form that redirects only after Better Auth returns a session.

// src/components/sign-in-form.tsx
"use client";
import { useState } from "react";
import type { FormEvent } from "react";
import { authClient } from "@/lib/auth-client";
import { billingRoutes } from "@/lib/billing/routes";

export function SignInForm() {
  const [error, setError] = useState("");
  async function submit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    const result = await authClient.signIn.email({
      email: String(data.get("email")),
      password: String(data.get("password")),
    });
    if (result.error) setError(result.error.message ?? "Unable to sign in");
    else window.location.assign(billingRoutes.settings);
  }

Render the sign-in fields.

  return (
    <form onSubmit={submit}>
      <h2>Sign in</h2>
      <input name="email" type="email" required aria-label="Email" />
      <input name="password" type="password" required aria-label="Password" />
      <button type="submit">Sign in</button>
      {error ? <p role="alert">{error}</p> : null}
    </form>
  );
}

Render both controls from /sign-in.

// src/app/sign-in/page.tsx
import { SignInForm } from "@/components/sign-in-form";
import { SignUpForm } from "@/components/sign-up-form";

export default function SignInPage() {
  return <main><SignUpForm /><SignInForm /></main>;
}

Webhooks are not required for this authorization model because every entitlement decision reads Customer State. Add Polar webhooks when another feature needs asynchronous delivery, analytics, or local denormalized state.

Validate the integration

The clean harness is a runnable integration fixture, not proof that payment and security behavior is correct in your deployment. Run TypeScript checking, a full Next.js build, and sandbox tests that exercise auth, ownership, failure, and cancellation paths. Add a type-check script and run both static checks.

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

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

Prompts

Development

Career

Polar billing with Better Auth

Use the supported package set

Choose the customer lifecycle before configuring Better Auth

Prepare Polar and the application

Validate configuration at startup

Configure Better Auth and Polar

Create or associate the customer on the first billing action

Add bounded local API controls

Create checkout from a server-owned route

Read Customer State and authorize on the server

Route checkout completion from verified state

Add an abortable finishing page

Add the customer portal and runnable harness pages

Validate the integration

​Use the supported package set

​Choose the customer lifecycle before configuring Better Auth

​Prepare Polar and the application

​Validate configuration at startup

​Configure Better Auth and Polar

​Create or associate the customer on the first billing action

​Add bounded local API controls

​Create checkout from a server-owned route

​Read Customer State and authorize on the server

​Route checkout completion from verified state

​Add an abortable finishing page

​Add the customer portal and runnable harness pages

​Validate the integration

Use the supported package set

Choose the customer lifecycle before configuring Better Auth

Prepare Polar and the application

Validate configuration at startup

Configure Better Auth and Polar

Create or associate the customer on the first billing action

Add bounded local API controls

Create checkout from a server-owned route

Read Customer State and authorize on the server

Route checkout completion from verified state

Add an abortable finishing page

Add the customer portal and runnable harness pages

Validate the integration