The Payment Adapter Pattern in Next.js: Stripe, LemonSqueezy, and Polar Without App-Wide Rewrites
Most SaaS apps start with one payment provider. That is fine. The mistake is letting that provider become the architecture. If Stripe-specific objects leak into pages, server actions, admin tools, and webhook handlers, switching to LemonSqueezy or Polar becomes a rewrite. Even adding one-time products next to subscriptions can become awkward. The payment adapter pattern keeps provider details behind a small interface. Payment code tends to sprawl fast: pricing CTAs, authenticated checkout, one-t
Most SaaS apps start with one payment provider.
That is fine. The mistake is letting that provider become the architecture.
If Stripe-specific objects leak into pages, server actions, admin tools, and webhook handlers, switching to LemonSqueezy or Polar becomes a rewrite. Even adding one-time products next to subscriptions can become awkward.
The payment adapter pattern keeps provider details behind a small interface.
The Shape of the Problem
Payment code tends to sprawl fast: pricing CTAs, authenticated checkout, one-time marketing checkout, billing portal links, webhooks, refunds, seat changes, usage credits. Import a provider SDK directly in even half of these, and every feature becomes provider-aware — which means every provider migration becomes an app-wide grep.
If each layer imports a provider SDK directly, every feature becomes provider-aware.
That makes the code harder to test and harder to change.
A Small Interface Is Enough
You do not need a large abstraction. Start with the operations the app actually performs:
export interface PaymentAdapter {
createCheckout(params: CheckoutParams): Promise<string>;
createMarketingCheckout(params: MarketingCheckoutParams): Promise<string>;
createPortalSession(customerId: string): Promise<string>;
handleWebhook(payload: string, signature: string): Promise<WebhookResult>;
refundPayment(params: RefundParams): Promise<RefundResult>;
}
Enter fullscreen mode Exit fullscreen mode
The rest of the app imports getPaymentAdapter() instead of stripe, lemonsqueezy, or polar.
const adapter = await getPaymentAdapter();
const checkoutUrl = await adapter.createCheckout({
planId: 'pro',
interval: 'monthly',
seats: 5,
customerId,
});
Enter fullscreen mode Exit fullscreen mode
That one boundary gives you room to change providers without changing every caller.
Keep Plans Provider-Neutral
Plan definitions should describe your product, not your provider.
export const plans = [
{
id: 'pro',
name: 'Pro',
price: { monthly: 19, yearly: 190 },
limits: { projects: 'unlimited', aiCredits: 5000 },
},
] as const;
Enter fullscreen mode Exit fullscreen mode
Provider-specific IDs belong in environment variables or provider mapping code:
PAYMENT_PROVIDER="stripe"
STRIPE_PRICE_PRO_MONTHLY="price_..."
# or
PAYMENT_PROVIDER="polar"
CHECKOUT_VARIANT_PRO="..."
Enter fullscreen mode Exit fullscreen mode
This lets the app reason about pro while the adapter handles provider IDs.
Marketing Checkout Is Different
Authenticated SaaS checkout usually attaches a customer, organization, subscription, and return URL.
Marketing checkout may sell source-code licenses or plugins before the buyer has an account.
That path needs its own method:
await adapter.createMarketingCheckout({
productKey: 'plugin-ai-kit',
successUrl,
cancelUrl,
});
Enter fullscreen mode Exit fullscreen mode
The pricing page can route to /api/checkout?product=plugin-ai-kit, and the route can call the active adapter.
If you prefer direct hosted checkout URLs, keep those as the simpler path:
CHECKOUT_URL_PLUGIN_AI_KIT="https://provider.example/buy/plugin-ai-kit"
Enter fullscreen mode Exit fullscreen mode
In Codapult, CHECKOUT_VARIANT_* wins over CHECKOUT_URL_*, so API checkout is used when a provider variant exists and direct links remain available as fallback.
Webhooks Need Normalized Events
Provider webhooks are not interchangeable.
Stripe, LemonSqueezy, and Polar use different event names, payload shapes, signature headers, and product identifiers. The adapter should normalize those into app-level events.
type WebhookResult =
| { type: 'subscription.updated'; subscriptionId: string; customerId: string }
| { type: 'subscription.deleted'; subscriptionId: string }
| { type: 'payment.refunded'; paymentId: string }
| { type: 'ignored' };
Enter fullscreen mode Exit fullscreen mode
The route validates rate limits and signature, then passes the normalized result to application code.
What Not to Abstract
Do not hide every provider feature.
Stripe Connect, LemonSqueezy licensing, and Polar's Merchant of Record model are not identical. If you need a provider-specific feature, keep it explicit at the edge of the adapter.
Good adapters remove duplication. Bad adapters pretend different products are the same.
The Payoff
With this boundary in place, pages don't import provider SDKs, webhook routes normalize events before they hit application code, and tests mock one interface instead of three. Switching providers becomes a config change and an adapter update — not a rewrite.
Codapult includes Stripe, LemonSqueezy, and Polar payment adapters; the payments docs show the provider switch and checkout paths.
