Polar Checkout

Create a Polar Checkout session for subscription payments

This endpoint wraps the official @polar-sh/nextjs Checkout helper. It validates the query string, redirects users to Polar’s hosted checkout, and returns them to /success when payment completes.

• Endpoint: GET /api/checkout
• File Location: src/app/api/checkout/route.ts
• Authentication: Pricing UI enforces Supabase auth before building the checkout URL

Query Parameters

products · string · required

Comma-separated Polar product IDs. Usually a single ID such as prod_monthly_... or prod_yearly_....

Source: Polar Dashboard → Products → Copy product ID (or use NEXT_PUBLIC_POLAR_PRODUCT_ID_*).

customerEmail · string

Prefills the email field in Polar Checkout. The pricing component passes the Supabase user’s email.

metadata · string

JSON string forwarded to Polar and later surfaced in webhook payloads. Sabo stores { "user_id": "uuid" } so the webhook can link the Polar subscription back to the Supabase user.

Example Request

Because the endpoint performs a redirect, you typically build a URL and assign it to window.location.href:

const checkoutUrl = new URL('/api/checkout', window.location.origin);
checkoutUrl.searchParams.set('products', planId);
checkoutUrl.searchParams.set('customerEmail', user.email ?? '');
checkoutUrl.searchParams.set('metadata', JSON.stringify({ user_id: user.id }));

window.location.href = checkoutUrl.toString();

Example Response

HTTP/1.1 307 Temporary Redirect
Location: https://polar.sh/checkout/checkout_123...

Polar returns 307/308 redirects rather than JSON payloads. The browser navigates to the hosted checkout UI automatically.

How It Works

1. Proxy to Polar

   @polar-sh/nextjs generates a handler that validates query parameters, injects your POLAR_ACCESS_TOKEN, and negotiates the redirect with Polar.

2. Success redirect

   successUrl is set to ${NEXT_PUBLIC_SITE_URL}/success. After payment, Polar sends the buyer there. The success page is purely informational—the webhook activates the subscription.

3. Webhook metadata

   The metadata string travels with the subscription so /api/webhooks/polar can read user_id and associate the subscription + orders with the right Supabase user.

Implementation

The default boilerplate uses "sandbox" for safety during development:

src/app/api/checkout/route.ts

import { Checkout } from "@polar-sh/nextjs";

export const GET = Checkout({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  successUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/success`,
  server: "sandbox",
});

Production-ready version: To switch dynamically based on environment, update the handler:

src/app/api/checkout/route.ts (environment-driven)

import { Checkout } from "@polar-sh/nextjs";

export const GET = Checkout({
  accessToken: process.env.POLAR_ACCESS_TOKEN!,
  successUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/success`,
  server: process.env.POLAR_SANDBOX === "true" ? "sandbox" : "production",
});

Then set POLAR_SANDBOX=false in production so Polar serves live checkout URLs.

Frontend Integration

The pricing component handles authentication, reads the plan IDs from src/lib/payments/plans.ts, and then calls the endpoint:

src/components/marketing/pricing.tsx (excerpt)

const handleCheckout = async (productId: string | null) => {
  if (!productId) return;

  const {
    data: { user },
  } = await supabase.auth.getUser();
  if (!user) {
    sessionStorage.setItem('signin-redirect-to', '/pricing');
    router.push('/sign-in');
    return;
  }

  const checkoutUrl = new URL('/api/checkout', window.location.origin);
  checkoutUrl.searchParams.set('products', productId);
  checkoutUrl.searchParams.set('customerEmail', user.email ?? '');
  checkoutUrl.searchParams.set(
    'metadata',
    JSON.stringify({ user_id: user.id })
  );

  window.location.href = checkoutUrl.toString();
};

Testing

1. Set POLAR_SANDBOX=true and ensure ngrok/HTTPS tunneling is running for webhooks.
2. Sign in, visit /pricing, and click Upgrade to Pro.
3. Complete checkout using 4242 4242 4242 4242.
4. Confirm /success loads and webhook logs show subscription.created followed by order.paid.

Do not rely on the success page alone. Always keep /api/webhooks/polar configured so database records stay in sync even if the buyer closes the browser early.