<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Jake Mcdonald</title>
    <description>The latest articles on DEV Community by Jake Mcdonald (@jakemcdonald).</description>
    <link>https://dev.to/jakemcdonald</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4217546%2Fa9eade7d-f8ac-423a-8781-7875de956c0d.png</url>
      <title>DEV Community: Jake Mcdonald</title>
      <link>https://dev.to/jakemcdonald</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/jakemcdonald"/>
    <language>en</language>
    <item>
      <title>Google, GitHub, or Magic Links? Picking Auth Providers for a Next.js MVP (Auth.js v5, 2026)</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Thu, 19 Nov 2026 16:22:35 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/google-github-or-magic-links-picking-auth-providers-for-a-nextjs-mvp-authjs-v5-2026-22cn</link>
      <guid>https://dev.to/jakemcdonald/google-github-or-magic-links-picking-auth-providers-for-a-nextjs-mvp-authjs-v5-2026-22cn</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 19, 2026 · About an 8-minute read · Checked against the Auth.js, GitHub, Google, and Resend docs&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. Every time I start a new SaaS, I lose an hour to the same question: which sign-in buttons go on the login page? Google? GitHub? Email magic links? All three? And then I lose another afternoon to callback URL errors and a consent screen I forgot to publish.&lt;/p&gt;

&lt;p&gt;This post is how I decide now, for a Next.js App Router app using Auth.js v5 (the &lt;code&gt;next-auth@5&lt;/code&gt; package). Short version: &lt;strong&gt;pick one OAuth provider your users already live in, add email magic links as the fallback, and skip passwords.&lt;/strong&gt; Below is why, plus the setup gotchas for each one. I checked the details against the &lt;a href="https://authjs.dev/getting-started/providers/google" rel="noopener noreferrer"&gt;Auth.js Google&lt;/a&gt;, &lt;a href="https://authjs.dev/getting-started/providers/github" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt;, and &lt;a href="https://authjs.dev/getting-started/authentication/email" rel="noopener noreferrer"&gt;email provider&lt;/a&gt; docs, &lt;a href="https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps" rel="noopener noreferrer"&gt;GitHub's OAuth app docs&lt;/a&gt;, &lt;a href="https://developers.google.com/identity/protocols/oauth2" rel="noopener noreferrer"&gt;Google's OAuth docs&lt;/a&gt;, and &lt;a href="https://resend.com/docs/add-a-domain" rel="noopener noreferrer"&gt;Resend's docs&lt;/a&gt; on November 19, 2026.&lt;/p&gt;

&lt;h2&gt;
  
  
  The short version: what I turn on first
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Your users are...&lt;/th&gt;
&lt;th&gt;Turn on first&lt;/th&gt;
&lt;th&gt;Add second&lt;/th&gt;
&lt;th&gt;Skip for now&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Developers&lt;/td&gt;
&lt;td&gt;GitHub&lt;/td&gt;
&lt;td&gt;Email magic link&lt;/td&gt;
&lt;td&gt;Passwords&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Everyone else (creators, small businesses, consumers)&lt;/td&gt;
&lt;td&gt;Google&lt;/td&gt;
&lt;td&gt;Email magic link&lt;/td&gt;
&lt;td&gt;Passwords&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Work accounts on mixed providers&lt;/td&gt;
&lt;td&gt;Email magic link&lt;/td&gt;
&lt;td&gt;Google&lt;/td&gt;
&lt;td&gt;Passwords&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two providers is the sweet spot for an MVP. One is too few, because somebody always wants to avoid the one you picked. Four buttons is a wall of logos, and every provider is another app registration, another secret, and another set of callback URLs to keep in sync across local, Preview, and production.&lt;/p&gt;

&lt;p&gt;Why skip passwords? The Credentials provider in Auth.js puts hashing, resets, rate limiting, and breach handling on you, and it requires the JWT session strategy. None of that makes your MVP more likely to get its first paying user.&lt;/p&gt;

&lt;h2&gt;
  
  
  The one setting that's the same for all of them: callback URLs
&lt;/h2&gt;

&lt;p&gt;Every Auth.js OAuth provider calls back to the same path pattern:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;https://your-domain.com/api/auth/callback/google
https://your-domain.com/api/auth/callback/github
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Locally that's &lt;code&gt;http://localhost:3000/api/auth/callback/&amp;lt;provider&amp;gt;&lt;/code&gt;. Most "it works locally but not in prod" auth bugs I've seen come down to that URL missing from the provider's settings for one environment.&lt;/p&gt;

&lt;p&gt;Auth.js v5 also picks up provider credentials from env vars on its own if you use its naming: &lt;code&gt;AUTH_GOOGLE_ID&lt;/code&gt;, &lt;code&gt;AUTH_GOOGLE_SECRET&lt;/code&gt;, &lt;code&gt;AUTH_GITHUB_ID&lt;/code&gt;, &lt;code&gt;AUTH_GITHUB_SECRET&lt;/code&gt;. Use those names and you'll write less config.&lt;/p&gt;

&lt;h2&gt;
  
  
  Google: the default for non-developer audiences
&lt;/h2&gt;

&lt;p&gt;Google is the button most normal people expect. The Auth.js side is short:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// auth.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;NextAuth&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next-auth"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;Google&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next-auth/providers/google"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;handlers&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;signIn&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;signOut&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;NextAuth&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;Google&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The Google Cloud side is where people get stuck:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Testing vs. In production.&lt;/strong&gt; An External app in "Testing" status is limited to test users you add by hand (up to 100). Google makes an exception when you only ask for the basic &lt;code&gt;openid&lt;/code&gt;, &lt;code&gt;email&lt;/code&gt;, and &lt;code&gt;profile&lt;/code&gt; scopes, which is all a sign-in button needs. Still, publish it before launch so you're not debugging this on launch day.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Ask only for sign-in scopes.&lt;/strong&gt; The moment you request Gmail, Drive, or Calendar access, you're into Google's verification review. For "Sign in with Google," you don't need any of that.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Refresh tokens only matter if you call Google APIs.&lt;/strong&gt; Auth.js notes Google only issues a refresh token the first time a user signs in. If all you want is a session, ignore it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Add every redirect URI&lt;/strong&gt; you'll use (localhost, your production domain, and any stable staging domain) to the OAuth client.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you want to restrict sign-ins to one company domain, the Auth.js docs show checking &lt;code&gt;profile.email_verified&lt;/code&gt; and the email's domain in the &lt;code&gt;signIn&lt;/code&gt; callback.&lt;/p&gt;

&lt;h2&gt;
  
  
  GitHub: the default for developer tools
&lt;/h2&gt;

&lt;p&gt;If your users write code, GitHub is the button they'll click. Same Auth.js setup, with &lt;code&gt;GitHub&lt;/code&gt; from &lt;code&gt;next-auth/providers/github&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Two things worth knowing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;GitHub OAuth apps now take up to 10 callback URLs.&lt;/strong&gt; GitHub added this in August 2026. Before that, you basically needed a separate OAuth app for local and production. Now one app can list both. GitHub also exposes wildcard matching per callback URL, and apps that had only one callback URL have it enabled by default (that was older GitHub behavior made visible). Review it and turn it off if you don't need it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Users can hide their email.&lt;/strong&gt; The Auth.js GitHub provider asks for the &lt;code&gt;read:user user:email&lt;/code&gt; scopes, and when the profile email is empty it fetches the user's email list and uses the primary address. Good to know when you're matching users to Stripe customers by email.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Email magic links: the fallback that catches everyone else
&lt;/h2&gt;

&lt;p&gt;Magic links are the best second option, because everyone has an email address. That includes people with work Microsoft accounts and people who'd rather not connect Google to a new app.&lt;/p&gt;

&lt;p&gt;The catches:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You need a database.&lt;/strong&gt; Auth.js stores the verification token, and it says plainly that an email provider can't be enabled without a database adapter. If you're already on Prisma + Postgres for billing, it's one more table.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Links expire.&lt;/strong&gt; By default, the user has 24 hours to click before they have to request a new one.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use a real sending domain.&lt;/strong&gt; With Resend, the test sender &lt;code&gt;onboarding@resend.dev&lt;/code&gt; can only send to the email address on your Resend account. Everyone else gets a 403 until you verify your own domain (Resend recommends a subdomain like &lt;code&gt;mail.yourapp.com&lt;/code&gt;). If magic links "work for me but not for my beta tester," this is almost always why.
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;Resend&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next-auth/providers/resend"&lt;/span&gt;

&lt;span class="c1"&gt;// AUTH_RESEND_KEY is read automatically&lt;/span&gt;
&lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;Resend&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"YourApp &amp;lt;login@mail.yourapp.com&amp;gt;"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The account-linking trap when you offer more than one
&lt;/h2&gt;

&lt;p&gt;Here's the bug you'll meet the week you add a second provider. Someone signs up with a magic link as &lt;code&gt;sam@gmail.com&lt;/code&gt;, then comes back and clicks "Sign in with Google" with the same address. Auth.js refuses with &lt;code&gt;OAuthAccountNotLinked&lt;/code&gt;. That's on purpose: for security, it won't auto-link an OAuth account to an existing user who isn't signed in.&lt;/p&gt;

&lt;p&gt;You have two options:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Leave it and explain it.&lt;/strong&gt; Show a friendly message on your sign-in error page: "You've signed in with a different method before; use that one." That's my default.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Opt in to linking&lt;/strong&gt; with &lt;code&gt;allowDangerousEmailAccountLinking: true&lt;/code&gt; on a provider, but only when you trust that provider to have verified the email. Google gives you an &lt;code&gt;email_verified&lt;/code&gt; flag. For GitHub, as noted above, the provider picks the primary email without checking whether it's verified, so I don't turn linking on there.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  A launch checklist for sign-in
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;code&gt;AUTH_SECRET&lt;/code&gt; set in every environment (&lt;code&gt;npx auth secret&lt;/code&gt; or &lt;code&gt;openssl rand -base64 32&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Callback URLs added for localhost and production in each provider's settings.&lt;/li&gt;
&lt;li&gt;Google OAuth app published, asking only for sign-in scopes.&lt;/li&gt;
&lt;li&gt;Resend (or another sender) using a verified domain, not the test address.&lt;/li&gt;
&lt;li&gt;A sign-in error page that explains &lt;code&gt;OAuthAccountNotLinked&lt;/code&gt; in plain words.&lt;/li&gt;
&lt;li&gt;One real sign-in per provider on the production domain before you share the link.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;You can wire all of this up yourself, and the steps above are everything I'd tell a friend. I built &lt;a href="https://shipember.com/" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt; because I was tired of redoing it for every project, along with the Stripe billing that comes after.&lt;/p&gt;

&lt;p&gt;ShipEmber is a Next.js App Router starter where sign-in already works the way this post describes: Auth.js v5 with Google, GitHub, and Resend magic links, each one switched on just by adding its env vars, a Prisma adapter with database sessions, and a custom &lt;code&gt;/login&lt;/code&gt; page. Behind it are Stripe Checkout, a customer portal route, a signature-verified webhook that keeps Free/Pro in Postgres, and a dashboard that checks the plan on the server. You still create your own OAuth apps and verify your own sending domain (no kit can do that for you), but the code is done.&lt;/p&gt;

&lt;p&gt;Where it doesn't fit: if you need teams, organizations, SSO/SAML, or per-seat billing from day one, a bigger kit will serve you better. In my &lt;a href="https://shipember.com/blog/best-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;October 30 comparison&lt;/a&gt;, those kits were listed at $199 to $349 and up (ShipFast from $199, Makerkit Pro $349, supastarter Solo $349). ShipEmber is deliberately small: one product, a Free plan, and a Pro plan.&lt;/p&gt;

&lt;p&gt;It's a one-time payment, &lt;strong&gt;$49&lt;/strong&gt; right now on the site (shown there as the launch price, with $79 listed as the regular price), and you can use it in unlimited personal and client projects. You get 14 days to ask for a refund if it doesn't work as described.&lt;/p&gt;

&lt;p&gt;Prefer watching over reading? There's a short walkthrough:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the ShipEmber walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;See pricing&lt;/a&gt; or &lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/nextjs-stripe-authjs-setup-checklist.html" rel="noopener noreferrer"&gt;Next.js + Stripe + Auth.js setup checklist&lt;/a&gt; · &lt;a href="https://shipember.com/blog/prisma-schema-saas-billing-stripe.html" rel="noopener noreferrer"&gt;Prisma Schema for SaaS Billing in Next.js&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-free-vs-pro-feature-gating.html" rel="noopener noreferrer"&gt;Free vs Pro Feature Gating in Next.js App Router&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Doc note: provider setup, callback URLs, env var names, the email-provider database requirement and 24-hour token expiry, and &lt;code&gt;OAuthAccountNotLinked&lt;/code&gt; / &lt;code&gt;allowDangerousEmailAccountLinking&lt;/code&gt; checked on authjs.dev; the GitHub provider email lookup checked in the next-auth source; multiple callback URLs and wildcard matching checked on docs.github.com and the GitHub changelog (Aug 14, 2026); Testing-status limits checked on developers.google.com; the resend.dev test-sender restriction and domain verification checked on resend.com/docs. All on November 19, 2026.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/nextjs-auth-providers-mvp.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>authjs</category>
      <category>webdev</category>
      <category>saas</category>
    </item>
    <item>
      <title>Prisma Schema for SaaS Billing in Next.js (2026): Users, Customers, Subscriptions, and Stripe Events</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Tue, 17 Nov 2026 16:21:39 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/prisma-schema-for-saas-billing-in-nextjs-2026-users-customers-subscriptions-and-stripe-events-48lo</link>
      <guid>https://dev.to/jakemcdonald/prisma-schema-for-saas-billing-in-nextjs-2026-users-customers-subscriptions-and-stripe-events-48lo</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 17, 2026 · About an 11-minute read · Checked against the Stripe, Auth.js, Prisma, and PostgreSQL docs&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. Every time I start a SaaS, there's a moment where I open &lt;code&gt;schema.prisma&lt;/code&gt; and ask the same question: how much of Stripe should live in my database? Copy too little and every page load turns into a Stripe API call. Copy too much and you end up with two sources of truth for money, which is a bad place to be.&lt;/p&gt;

&lt;p&gt;The rule I've settled on: &lt;strong&gt;Stripe owns the money, my database owns the answer to "can this user use Pro right now?"&lt;/strong&gt; I store IDs and a few fields of state that Stripe sends me through webhooks, and I let Stripe keep everything else: cards, invoices, amounts, tax, and retry schedules.&lt;/p&gt;

&lt;p&gt;This post walks through the schema I use for a one-product Free/Pro app in Next.js (App Router): the Auth.js models, a Stripe customer ID, a Subscription table, a StripeEvent table for idempotency, and the indexes that hold it together. The Stripe facts were checked against the &lt;a href="https://docs.stripe.com/api/subscriptions/object" rel="noopener noreferrer"&gt;Subscription object reference&lt;/a&gt;, the &lt;a href="https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-subscription-current-period-start-and-end" rel="noopener noreferrer"&gt;2025-03-31.basil changelog&lt;/a&gt;, and &lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe's webhook docs&lt;/a&gt;. The Auth.js models come from the &lt;a href="https://authjs.dev/getting-started/adapters/prisma" rel="noopener noreferrer"&gt;Auth.js Prisma adapter page&lt;/a&gt;, and the config notes from &lt;a href="https://www.prisma.io/docs/guides/upgrade-prisma-orm/v7" rel="noopener noreferrer"&gt;Prisma's v7 upgrade guide&lt;/a&gt;. I checked all of them on November 17, 2026.&lt;/p&gt;

&lt;h2&gt;
  
  
  The short version: store IDs and state, not money
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Data&lt;/th&gt;
&lt;th&gt;Where it lives&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Stripe customer ID (&lt;code&gt;cus_...&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Your DB, on &lt;code&gt;User&lt;/code&gt;, unique&lt;/td&gt;
&lt;td&gt;Links webhooks back to a user without guessing by email&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Subscription ID, status, price ID&lt;/td&gt;
&lt;td&gt;Your DB, &lt;code&gt;Subscription&lt;/code&gt; table&lt;/td&gt;
&lt;td&gt;Lets you check access on the server without calling Stripe&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Current period end, cancel flags&lt;/td&gt;
&lt;td&gt;Your DB, &lt;code&gt;Subscription&lt;/code&gt; table&lt;/td&gt;
&lt;td&gt;Shows "renews on" or "ends on" in the dashboard&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Processed event IDs (&lt;code&gt;evt_...&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Your DB, &lt;code&gt;StripeEvent&lt;/code&gt; table&lt;/td&gt;
&lt;td&gt;Stops a duplicate delivery from running twice&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Card numbers, CVCs, bank details&lt;/td&gt;
&lt;td&gt;Stripe only&lt;/td&gt;
&lt;td&gt;Checkout collects them on a Stripe-hosted page; they never need to touch your server&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Invoices, amounts, tax, proration&lt;/td&gt;
&lt;td&gt;Stripe only&lt;/td&gt;
&lt;td&gt;Stripe calculates them; the customer portal shows invoices&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;"Is this user Pro?"&lt;/td&gt;
&lt;td&gt;Derived in code&lt;/td&gt;
&lt;td&gt;Computed from status + price ID, not stored as a second truth&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Start with the Auth.js adapter models
&lt;/h2&gt;

&lt;p&gt;If you use Auth.js with a database session (or just want users in Postgres), &lt;code&gt;@auth/prisma-adapter&lt;/code&gt; expects specific models. The current Auth.js docs list four: &lt;strong&gt;&lt;code&gt;User&lt;/code&gt;&lt;/strong&gt;, &lt;strong&gt;&lt;code&gt;Account&lt;/code&gt;&lt;/strong&gt;, &lt;strong&gt;&lt;code&gt;Session&lt;/code&gt;&lt;/strong&gt;, and &lt;strong&gt;&lt;code&gt;VerificationToken&lt;/code&gt;&lt;/strong&gt;, plus an optional &lt;strong&gt;&lt;code&gt;Authenticator&lt;/code&gt;&lt;/strong&gt; model if you turn on WebAuthn (passkeys). Keep those model and field names as the docs show them. The adapter reads and writes them directly, so renaming &lt;code&gt;providerAccountId&lt;/code&gt; or &lt;code&gt;sessionToken&lt;/code&gt; breaks sign-in in ways that are confusing to debug.&lt;/p&gt;

&lt;p&gt;Billing fields go &lt;em&gt;next to&lt;/em&gt; the adapter fields, not in place of them. Adding &lt;code&gt;stripeCustomerId&lt;/code&gt; to &lt;code&gt;User&lt;/code&gt; is fine. The adapter ignores columns it doesn't know about.&lt;/p&gt;

&lt;p&gt;One Prisma 7 note: the schema on the Auth.js page still shows &lt;code&gt;url = env("DATABASE_URL")&lt;/code&gt; inside the &lt;code&gt;datasource&lt;/code&gt; block. In Prisma ORM 7, the connection URL moved out of &lt;code&gt;schema.prisma&lt;/code&gt; and into &lt;code&gt;prisma.config.ts&lt;/code&gt;, and Prisma no longer loads &lt;code&gt;.env&lt;/code&gt; for you (the docs use &lt;code&gt;import "dotenv/config"&lt;/code&gt;). If you copy the Auth.js schema into a Prisma 7 project, move the URL:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// prisma.config.ts (Prisma ORM 7)&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"dotenv/config"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;defineConfig&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;env&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"prisma/config"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="nf"&gt;defineConfig&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;schema&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"prisma/schema.prisma"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;datasource&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;env&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"DATABASE_URL"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The billing schema
&lt;/h2&gt;

&lt;p&gt;Here's the billing part. The Auth.js models stay as the docs show them; I've only added the relations to &lt;code&gt;User&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;datasource db {
  provider = "postgresql"
}

generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

// Mirrors Stripe's subscription statuses exactly, so no mapping layer
enum SubscriptionStatus {
  incomplete
  incomplete_expired
  trialing
  active
  past_due
  canceled
  unpaid
  paused
}

model User {
  id               String    @id @default(cuid())
  name             String?
  email            String    @unique
  emailVerified    DateTime?
  image            String?
  stripeCustomerId String?   @unique // cus_..., set once, reused forever

  accounts      Account[]
  sessions      Session[]
  subscriptions Subscription[]

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Subscription {
  id                   String             @id @default(cuid())
  userId               String
  stripeSubscriptionId String             @unique // sub_...
  status               SubscriptionStatus
  priceId              String             // price_..., used to derive the plan
  currentPeriodEnd     DateTime?          // from the subscription item (see below)
  cancelAtPeriodEnd    Boolean            @default(false)
  cancelAt             DateTime?          // a scheduled end date, if any

  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  user User @relation(fields: [userId], references: [id], onDelete: Cascade)

  @@index([userId])
}

// Idempotency ledger: one row per Stripe event you've handled
model StripeEvent {
  id        String   @id // evt_...
  type      String
  createdAt DateTime @default(now())
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few choices in there are worth explaining.&lt;/p&gt;

&lt;h2&gt;
  
  
  The customer: one &lt;code&gt;stripeCustomerId&lt;/code&gt; per user, and make it unique
&lt;/h2&gt;

&lt;p&gt;Stripe's webhook events about subscriptions carry a customer ID, not your user ID. So the first lookup in almost every handler is "which user has this customer ID?" That's why &lt;code&gt;stripeCustomerId&lt;/code&gt; is &lt;code&gt;@unique&lt;/code&gt;: it gives you an index for the lookup and makes it impossible for two users to point at the same Stripe customer.&lt;/p&gt;

&lt;p&gt;The trap is creating more customers than you meant to. Stripe's docs for Checkout Sessions say that if you leave &lt;code&gt;customer&lt;/code&gt; blank in &lt;code&gt;subscription&lt;/code&gt; mode, Checkout creates a new Customer object. That's fine the first time. But if a user checks out, cancels, and comes back later, a blank &lt;code&gt;customer&lt;/code&gt; gives them a second customer, and now their history is split. So:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;On the first checkout, pass &lt;code&gt;client_reference_id&lt;/code&gt; (your user ID) so the &lt;code&gt;checkout.session.completed&lt;/code&gt; handler knows who paid, then save &lt;code&gt;session.customer&lt;/code&gt; to &lt;code&gt;User.stripeCustomerId&lt;/code&gt;. (You can also create the customer yourself before Checkout and save it right away.)&lt;/li&gt;
&lt;li&gt;On every later checkout or portal session, pass the saved &lt;code&gt;customer&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Do you need a separate &lt;code&gt;Customer&lt;/code&gt; table? For one product with Free and Pro, no. A column is enough. A table starts to make sense when a customer can belong to an organization instead of a person, which is a bigger app than this post is about.&lt;/p&gt;

&lt;h2&gt;
  
  
  The subscription: the fields worth copying
&lt;/h2&gt;

&lt;p&gt;From the whole Subscription object, I copy six fields. Everything else I fetch from Stripe if I ever need it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;stripeSubscriptionId&lt;/code&gt;&lt;/strong&gt;, unique. It's what you upsert on when a &lt;code&gt;customer.subscription.updated&lt;/code&gt; event arrives.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;status&lt;/code&gt;&lt;/strong&gt;. Stripe lists eight values: &lt;code&gt;incomplete&lt;/code&gt;, &lt;code&gt;incomplete_expired&lt;/code&gt;, &lt;code&gt;trialing&lt;/code&gt;, &lt;code&gt;active&lt;/code&gt;, &lt;code&gt;past_due&lt;/code&gt;, &lt;code&gt;canceled&lt;/code&gt;, &lt;code&gt;unpaid&lt;/code&gt;, and &lt;code&gt;paused&lt;/code&gt;. Quick meanings, from the API reference:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;incomplete&lt;/code&gt;: the first payment attempt failed. If the first invoice isn't paid within 23 hours, it becomes &lt;code&gt;incomplete_expired&lt;/code&gt;, which is final.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;trialing&lt;/code&gt;: in a trial; it moves to &lt;code&gt;active&lt;/code&gt; when the trial ends.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;past_due&lt;/code&gt;: a renewal payment failed (for automatic charging) and Stripe is retrying.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;canceled&lt;/code&gt; or &lt;code&gt;unpaid&lt;/code&gt;: where it ends up after retries run out, depending on your Billing settings.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;paused&lt;/code&gt;: for example, a trial ended without a payment method. It's different from pausing collection, which leaves the status alone.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;I mirror these as a Prisma enum with Stripe's exact spellings. That way the webhook writes &lt;code&gt;sub.status&lt;/code&gt; straight through, and a value I forgot to map can't quietly become &lt;code&gt;active&lt;/code&gt;. If you'd rather not run a migration if Stripe ever adds a status, a plain &lt;code&gt;String&lt;/code&gt; column works too.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;priceId&lt;/code&gt;&lt;/strong&gt;, from &lt;code&gt;sub.items.data[0].price.id&lt;/code&gt;. I store the price, not a plan name, because the price is what Stripe actually knows about. The plan is something I derive (more below).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;currentPeriodEnd&lt;/code&gt;&lt;/strong&gt;. This one changed, and plenty of tutorials haven't caught up. Starting with API version &lt;strong&gt;2025-03-31.basil&lt;/strong&gt; (stripe-node v18), &lt;code&gt;current_period_start&lt;/code&gt; and &lt;code&gt;current_period_end&lt;/code&gt; were &lt;strong&gt;removed from the Subscription object&lt;/strong&gt; and added to each &lt;strong&gt;subscription item&lt;/strong&gt;. Stripe's changelog says to read &lt;code&gt;items.data.current_period_end&lt;/code&gt; instead. Code that still reads &lt;code&gt;subscription.current_period_end&lt;/code&gt; on a newer API version gets &lt;code&gt;undefined&lt;/code&gt;, and if it's behind a type cast, nothing complains. Your "renews on" date is just quietly empty.&lt;/p&gt;

&lt;p&gt;When you create a webhook endpoint for snapshot events, you pick its API version, so check both your SDK version and your endpoint's version. For a single-item Free/Pro subscription, reading the first item is enough:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/billing/sync.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"stripe"&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;toDate&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;subscriptionFields&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Subscription&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;stripeSubscriptionId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// same strings as the Prisma enum&lt;/span&gt;
    &lt;span class="n"&gt;priceId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;price&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="c1"&gt;// basil and later: the period lives on the item, not the subscription&lt;/span&gt;
    &lt;span class="n"&gt;currentPeriodEnd&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;toDate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;current_period_end&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;cancelAtPeriodEnd&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cancel_at_period_end&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;cancelAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;toDate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;cancel_at&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you ever sell multi-item subscriptions with different intervals, each item has its own period, and you'll want to decide which one you show.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;cancelAtPeriodEnd&lt;/code&gt; and &lt;code&gt;cancelAt&lt;/code&gt;&lt;/strong&gt;. &lt;code&gt;cancel_at_period_end&lt;/code&gt; is true when an active subscription is set to end at the end of the period. But in 2025, Stripe also added &lt;code&gt;cancel_at&lt;/code&gt; values (&lt;code&gt;min_period_end&lt;/code&gt;, &lt;code&gt;max_period_end&lt;/code&gt;) for subscriptions in flexible billing mode and marked the &lt;code&gt;cancel_at_period_end&lt;/code&gt; &lt;em&gt;parameter&lt;/em&gt; as deprecated. The changelog notes that the &lt;code&gt;cancel_at_period_end&lt;/code&gt; field isn't compatible with the new &lt;code&gt;cancel_at&lt;/code&gt; helpers. In practice, a subscription can be scheduled to end with &lt;code&gt;cancel_at&lt;/code&gt; set while &lt;code&gt;cancel_at_period_end&lt;/code&gt; is false. Storing both costs one column and keeps the "Your plan ends on..." banner honest either way.&lt;/p&gt;

&lt;h2&gt;
  
  
  StripeEvent: the table that makes webhooks safe to retry
&lt;/h2&gt;

&lt;p&gt;Stripe's docs say it plainly: webhook endpoints "might occasionally receive the same event more than once," and you should log the event IDs you've processed and skip ones you've seen. They also say Stripe doesn't guarantee events arrive in order, and that you shouldn't use &lt;code&gt;created&lt;/code&gt; to decide order or detect duplicates.&lt;/p&gt;

&lt;p&gt;That's what &lt;code&gt;StripeEvent&lt;/code&gt; is for. The &lt;code&gt;evt_...&lt;/code&gt; ID is the primary key, so the database itself refuses a second row for the same event. Insert it in the same transaction as the work, and two simultaneous deliveries can't both win. I walked through that claim-in-a-transaction pattern, plus refetching the subscription so out-of-order events don't matter, in &lt;a href="https://shipember.com/blog/stripe-webhook-idempotency-nextjs.html" rel="noopener noreferrer"&gt;Stripe Webhooks in Next.js: Idempotency, Out-of-Order Events, and Retries&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;I keep only &lt;code&gt;id&lt;/code&gt;, &lt;code&gt;type&lt;/code&gt;, and a timestamp. You could store the full payload for debugging, but it includes customer details, and the Dashboard already keeps event history. If you do store it, plan a cleanup job.&lt;/p&gt;

&lt;h2&gt;
  
  
  Derive the plan instead of storing it twice
&lt;/h2&gt;

&lt;p&gt;There's no &lt;code&gt;plan&lt;/code&gt; column in the schema above. That's on purpose. "Pro" is a fact about two things Stripe already told you, the status and the price, so I compute it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/billing/plan.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Subscription&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@/generated/prisma/client"&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;PRO_PRICE_IDS&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;STRIPE_PRO_MONTHLY_PRICE_ID&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;STRIPE_PRO_YEARLY_PRICE_ID&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Boolean&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;hasPro&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Pick&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Subscription&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"status"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="s2"&gt;"priceId"&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;paying&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"active"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"trialing"&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;paying&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="no"&gt;PRO_PRICE_IDS&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;priceId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Whether &lt;code&gt;past_due&lt;/code&gt; keeps access during Stripe's retries is a product decision. I lean toward a short grace period so a failed card doesn't lock someone out mid-task, but either is fine as long as it's in one function. And that function has to run on the server: in the page, the Server Action, and the API route. I covered where to call it in &lt;a href="https://shipember.com/blog/nextjs-free-vs-pro-feature-gating.html" rel="noopener noreferrer"&gt;Free vs Pro Feature Gating in Next.js App Router&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;If you'd still like a cached &lt;code&gt;plan&lt;/code&gt; column for fast queries, that's a reasonable trade. Just write it only from the webhook, in the same transaction as the subscription upsert, so the two can't drift apart.&lt;/p&gt;

&lt;h2&gt;
  
  
  What not to store
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Card data.&lt;/strong&gt; No card numbers, CVCs, or expiry dates. Checkout and the customer portal collect payment details on Stripe-hosted pages, so your app never has to touch them. Storing raw card data would pull your app into PCI requirements you don't want.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Prices and amounts.&lt;/strong&gt; Keep price IDs, not "$12/month." Prices change, currencies vary, and coupons exist. Stripe knows the real number.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Invoices and receipts.&lt;/strong&gt; The Stripe customer portal can show invoice history and handle cancel and upgrade. That saves you a table and a page. More on that in &lt;a href="https://shipember.com/blog/stripe-customer-portal-nextjs.html" rel="noopener noreferrer"&gt;Stripe Customer Portal in Next.js&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A plan you set from the success page.&lt;/strong&gt; The Checkout success URL just means the user's browser came back. Only the webhook should change billing state.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Indexes and unique constraints, in one list
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;User.email @unique&lt;/code&gt;: already in the Auth.js schema.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;User.stripeCustomerId @unique&lt;/code&gt;: the webhook's main lookup; also blocks two users from sharing a customer.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Subscription.stripeSubscriptionId @unique&lt;/code&gt;: the upsert key for subscription events.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Subscription @@index([userId])&lt;/code&gt;: for "load this user's subscription" on every gated request. If you only ever allow one subscription per user, make &lt;code&gt;userId&lt;/code&gt; &lt;code&gt;@unique&lt;/code&gt; instead and upsert by user. That's simpler, but you lose history when someone resubscribes and gets a new &lt;code&gt;sub_...&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;StripeEvent.id @id&lt;/code&gt;: the idempotency guarantee itself.&lt;/li&gt;
&lt;li&gt;Auth.js keys: &lt;code&gt;Account&lt;/code&gt; is keyed on &lt;code&gt;[provider, providerAccountId]&lt;/code&gt;, &lt;code&gt;Session.sessionToken&lt;/code&gt; is unique, and &lt;code&gt;VerificationToken&lt;/code&gt; is keyed on &lt;code&gt;[identifier, token]&lt;/code&gt;. Keep them as the docs define them.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;One Postgres detail people miss: a foreign key doesn't automatically create an index on the referencing column. The &lt;a href="https://www.postgresql.org/docs/current/ddl-constraints.html" rel="noopener noreferrer"&gt;PostgreSQL docs on constraints&lt;/a&gt; point this out and suggest indexing it yourself, since deletes on the referenced table have to scan for matching rows. That's why &lt;code&gt;Subscription&lt;/code&gt; gets &lt;code&gt;@@index([userId])&lt;/code&gt;, and it's worth adding the same to &lt;code&gt;Account&lt;/code&gt; and &lt;code&gt;Session&lt;/code&gt; if your user deletes cascade through big tables.&lt;/p&gt;

&lt;h2&gt;
  
  
  A 10-minute test before you trust it
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Run &lt;code&gt;stripe listen --forward-to localhost:3000/api/stripe/webhook&lt;/code&gt; and subscribe with a test card. You should see one &lt;code&gt;User.stripeCustomerId&lt;/code&gt;, one &lt;code&gt;Subscription&lt;/code&gt; row with &lt;code&gt;status = active&lt;/code&gt;, and one &lt;code&gt;StripeEvent&lt;/code&gt; row per handled event.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check &lt;code&gt;currentPeriodEnd&lt;/code&gt; isn't null.&lt;/strong&gt; If it is, you're reading the old subscription-level field.&lt;/li&gt;
&lt;li&gt;Check out a second time as the same user (after canceling). There should still be one Stripe customer for that user.&lt;/li&gt;
&lt;li&gt;Cancel through the customer portal. &lt;code&gt;cancelAtPeriodEnd&lt;/code&gt; or &lt;code&gt;cancelAt&lt;/code&gt; should be set, and &lt;code&gt;hasPro&lt;/code&gt; should stay true until the period ends.&lt;/li&gt;
&lt;li&gt;Resend one event (from the Dashboard, or with &lt;code&gt;stripe events resend&lt;/code&gt; in the CLI) and confirm nothing runs twice.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;None of this requires a product. It's a schema and a couple of helpers, and if you'd rather write them yourself, the code above is a solid start. I built &lt;a href="https://shipember.com/" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt; because I kept rebuilding this exact layer (plus the auth, checkout, webhook, and gating around it) for every new idea.&lt;/p&gt;

&lt;p&gt;ShipEmber is a Next.js App Router starter with that wiring done: Auth.js sign-in (Google, GitHub, and email magic links) on the Prisma adapter, Postgres via Prisma with a seed script, Stripe Checkout, a customer portal route, a signature-verified webhook route with a &lt;code&gt;StripeEvent&lt;/code&gt; table, and a dashboard that checks the plan on the server. Its schema follows the shape in this post: a unique &lt;code&gt;stripeCustomerId&lt;/code&gt; on &lt;code&gt;User&lt;/code&gt;, a &lt;code&gt;Subscription&lt;/code&gt; table with a unique Stripe subscription ID, and the idempotency table. It does differ in a couple of ways I mentioned above: it keeps one subscription row per user and caches a plan column that the webhook updates.&lt;/p&gt;

&lt;p&gt;To be honest about where it doesn't fit: if you need organizations, per-seat billing, or several products from day one, a bigger kit will serve you better. Those usually cost more. ShipFast's Starter plan shows $199 on shipfa.st, and supastarter's Solo plan is $349 (both checked on November 17, 2026). ShipEmber is deliberately small, built for one product with a Free plan and a Pro plan.&lt;/p&gt;

&lt;p&gt;It's a one-time payment, not a subscription. Right now the &lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;pricing page&lt;/a&gt; shows &lt;strong&gt;$49&lt;/strong&gt; as the launch price, going to $79. You can use it in unlimited personal and client projects, and if it doesn't work as described, you can email within 14 days for a refund.&lt;/p&gt;

&lt;p&gt;Prefer watching over reading? There's a short walkthrough:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the ShipEmber walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;See pricing&lt;/a&gt; or &lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/stripe-webhook-idempotency-nextjs.html" rel="noopener noreferrer"&gt;Stripe Webhooks in Next.js: Idempotency, Out-of-Order Events, and Retries&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-free-vs-pro-feature-gating.html" rel="noopener noreferrer"&gt;Free vs Pro Feature Gating in Next.js App Router&lt;/a&gt; · &lt;a href="https://shipember.com/blog/stripe-customer-portal-nextjs.html" rel="noopener noreferrer"&gt;Stripe Customer Portal in Next.js&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Doc note: subscription statuses, &lt;code&gt;cancel_at_period_end&lt;/code&gt;, and &lt;code&gt;cancel_at&lt;/code&gt; checked on docs.stripe.com/api/subscriptions/object; the item-level &lt;code&gt;current_period_end&lt;/code&gt; move on the 2025-03-31.basil changelog; &lt;code&gt;cancel_at&lt;/code&gt; enums and the &lt;code&gt;cancel_at_period_end&lt;/code&gt; deprecation on the 2025-05-28 and 2025-07-30 basil changelogs; Checkout customer creation on docs.stripe.com/api/checkout/sessions/create; duplicate and out-of-order events on docs.stripe.com/webhooks; Auth.js models on authjs.dev; Prisma 7 config on prisma.io/docs; foreign key indexing on postgresql.org/docs. All on November 17, 2026.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/prisma-schema-saas-billing-stripe.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>prisma</category>
      <category>stripe</category>
      <category>postgres</category>
    </item>
    <item>
      <title>Stripe Webhook Secrets Across Local, Preview, and Production: Stripe CLI vs Test vs Live Endpoints on Vercel (2026)</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Thu, 12 Nov 2026 16:24:26 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/stripe-webhook-secrets-across-local-preview-and-production-stripe-cli-vs-test-vs-live-endpoints-1eij</link>
      <guid>https://dev.to/jakemcdonald/stripe-webhook-secrets-across-local-preview-and-production-stripe-cli-vs-test-vs-live-endpoints-1eij</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 12, 2026 · About a 9-minute read · Checked against the Stripe and Vercel docs&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. The most common Stripe bug I've hit (and helped other people with) isn't in the billing logic at all. It's this line in the logs: &lt;code&gt;No signatures found matching the expected signature for payload.&lt;/code&gt; The code is fine. The handler is fine. The app is just holding the wrong &lt;code&gt;whsec_&lt;/code&gt; secret for the place it's running.&lt;/p&gt;

&lt;p&gt;That happens because a normal Next.js + Stripe + Vercel setup has &lt;strong&gt;at least three different webhook signing secrets&lt;/strong&gt;, and they all look the same: one from the Stripe CLI on your laptop, one for a test (sandbox) endpoint, and one for your live endpoint. Add Vercel's per-environment variables, Preview URLs that change, and Deployment Protection, and there are a lot of ways to plug the right secret into the wrong place.&lt;/p&gt;

&lt;p&gt;This post is the map I use. Everything here was checked against &lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe's webhook docs&lt;/a&gt;, &lt;a href="https://docs.stripe.com/webhooks/signature" rel="noopener noreferrer"&gt;Stripe's signature troubleshooting guide&lt;/a&gt;, the &lt;a href="https://docs.stripe.com/cli/listen" rel="noopener noreferrer"&gt;Stripe CLI &lt;code&gt;listen&lt;/code&gt; reference&lt;/a&gt;, &lt;a href="https://vercel.com/docs/environment-variables" rel="noopener noreferrer"&gt;Vercel's environment variable docs&lt;/a&gt;, and &lt;a href="https://vercel.com/docs/deployment-protection" rel="noopener noreferrer"&gt;Vercel's Deployment Protection docs&lt;/a&gt; on November 12, 2026.&lt;/p&gt;

&lt;h2&gt;
  
  
  The short version: one variable name, three different values
&lt;/h2&gt;

&lt;p&gt;Use one variable name everywhere, &lt;code&gt;STRIPE_WEBHOOK_SECRET&lt;/code&gt;, and give it a different value in each place:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Where the code runs&lt;/th&gt;
&lt;th&gt;Who sends the events&lt;/th&gt;
&lt;th&gt;Where the &lt;code&gt;whsec_&lt;/code&gt; comes from&lt;/th&gt;
&lt;th&gt;Stripe API key&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Your laptop (&lt;code&gt;next dev&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Stripe CLI (&lt;code&gt;stripe listen&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Printed by &lt;code&gt;stripe listen&lt;/code&gt; in your terminal&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sk_test_...&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Vercel Preview (optional)&lt;/td&gt;
&lt;td&gt;A sandbox/test endpoint in the Dashboard&lt;/td&gt;
&lt;td&gt;That endpoint's settings, &lt;strong&gt;Reveal secret&lt;/strong&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sk_test_...&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Vercel Production&lt;/td&gt;
&lt;td&gt;A live-mode endpoint in the Dashboard&lt;/td&gt;
&lt;td&gt;That live endpoint's settings, &lt;strong&gt;Reveal secret&lt;/strong&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sk_live_...&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Stripe's own troubleshooting guide says the most common cause of signature failures is using the wrong endpoint secret, and that "the secret for a CLI-forwarded endpoint is different from the secret for a Dashboard-managed endpoint." All of them start with &lt;code&gt;whsec_&lt;/code&gt;, so you can't tell them apart by looking.&lt;/p&gt;

&lt;h2&gt;
  
  
  Secret #1: the Stripe CLI secret (local development)
&lt;/h2&gt;

&lt;p&gt;On your laptop, Stripe can't reach &lt;code&gt;localhost&lt;/code&gt;, so the Stripe CLI connects to Stripe and forwards events to your dev server:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;stripe login
stripe listen --forward-to localhost:3000/api/webhooks/stripe
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When it starts, it prints &lt;code&gt;Ready! Your webhook signing secret is whsec_...&lt;/code&gt;. That value goes in &lt;code&gt;.env.local&lt;/code&gt; as &lt;code&gt;STRIPE_WEBHOOK_SECRET&lt;/code&gt;, and nowhere else. A few things worth knowing, all from the CLI reference:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You don't need a Dashboard endpoint&lt;/strong&gt; for this. The CLI secret is not the same as any endpoint secret you see in the Dashboard.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It doesn't change between restarts&lt;/strong&gt; of &lt;code&gt;stripe listen&lt;/code&gt;, so you set it once. If you want it in a script, &lt;code&gt;stripe listen --print-secret&lt;/code&gt; prints only the secret and exits.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It runs in a sandbox by default.&lt;/strong&gt; There's a &lt;code&gt;--live&lt;/code&gt; flag, but I'd keep local development on test keys and test events.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;stripe trigger checkout.session.completed&lt;/code&gt;&lt;/strong&gt; sends a test event through the listener. It works by making real API calls in your sandbox, so it creates the objects it needs (customers, payments) as a side effect.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;One Vercel-specific trap: if you also store a &lt;code&gt;STRIPE_WEBHOOK_SECRET&lt;/code&gt; in Vercel's &lt;strong&gt;Development&lt;/strong&gt; environment, &lt;code&gt;vercel env pull&lt;/code&gt; will write that value into &lt;code&gt;.env.local&lt;/code&gt;. Per Vercel's CLI docs, &lt;code&gt;vercel env pull&lt;/code&gt; merges into an existing file and keeps variables that exist only locally, so the clean setup is to &lt;strong&gt;not&lt;/strong&gt; set &lt;code&gt;STRIPE_WEBHOOK_SECRET&lt;/code&gt; in Vercel's Development scope at all and let the CLI secret live only in &lt;code&gt;.env.local&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Secret #2 and #3: test-mode and live-mode endpoints each have their own
&lt;/h2&gt;

&lt;p&gt;When you register an endpoint in the Dashboard (Workbench → Webhooks → &lt;strong&gt;Create an event destination&lt;/strong&gt;), Stripe shows a signing secret that starts with &lt;code&gt;whsec_&lt;/code&gt; on the endpoint's settings page. Stripe's docs are explicit that these are per endpoint and per mode: "Stripe generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys, the secret is different for each one."&lt;/p&gt;

&lt;p&gt;So even if your test and live endpoints point at the exact same URL, they have different secrets. And it's not just the secret: Stripe's API keys doc says each mode has its own keys and that "objects in one mode aren't accessible to the other." Your sandbox Price IDs won't exist in live mode, so &lt;code&gt;STRIPE_PRICE_PRO&lt;/code&gt; (or whatever you call it) needs a live value too.&lt;/p&gt;

&lt;p&gt;Rolling a secret is also per endpoint. In the endpoint's menu, &lt;strong&gt;Roll secret&lt;/strong&gt; lets you expire the old secret right away or keep it active for up to 7 days while you update your app. During that window Stripe signs each event once per active secret, so the official libraries keep working with either one.&lt;/p&gt;

&lt;h2&gt;
  
  
  Vercel: scope each value to the right environment, then redeploy
&lt;/h2&gt;

&lt;p&gt;Vercel environment variables are scoped to &lt;strong&gt;Production&lt;/strong&gt;, &lt;strong&gt;Preview&lt;/strong&gt;, and &lt;strong&gt;Development&lt;/strong&gt; (plus custom environments if you use them). For this setup:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Production:&lt;/strong&gt; live &lt;code&gt;STRIPE_WEBHOOK_SECRET&lt;/code&gt;, &lt;code&gt;sk_live_&lt;/code&gt; secret key, live Price IDs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Preview:&lt;/strong&gt; test values, &lt;em&gt;only&lt;/em&gt; if you actually want webhooks on Preview (see the next section). Vercel also lets you scope a Preview variable to one specific Git branch, and a branch-specific value overrides the general Preview value.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Development:&lt;/strong&gt; leave the webhook secret out, as above.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;You can set these in the dashboard (Project → Settings → Environment Variables) or with the CLI. On recent CLI versions (64.7.0 or later):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;vercel env add STRIPE_WEBHOOK_SECRET --environment production
vercel env add STRIPE_WEBHOOK_SECRET --environment preview
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Run it without piping the value in, so the CLI prompts you. Vercel's docs warn that piping with &lt;code&gt;echo&lt;/code&gt; saves the secret in your shell history. With the CLI, new Production variables default to the &lt;strong&gt;Secret&lt;/strong&gt; type, which is write-only after saving.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The step everyone forgets: redeploy.&lt;/strong&gt; Vercel's docs put it plainly: "Any change you make to environment variables are not applied to previous deployments, they only apply to new deployments." If you paste the live &lt;code&gt;whsec_&lt;/code&gt; into Production and immediately run a test purchase, the running deployment still has the old value and every event fails signature verification. Change the variable, redeploy, &lt;em&gt;then&lt;/em&gt; test.&lt;/p&gt;

&lt;h2&gt;
  
  
  Preview deployments: changing URLs and Deployment Protection
&lt;/h2&gt;

&lt;p&gt;Preview is where webhooks get awkward, for two reasons.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. The URL changes.&lt;/strong&gt; Vercel gives every deployment a unique URL like &lt;code&gt;&amp;lt;project&amp;gt;-&amp;lt;unique-hash&amp;gt;-&amp;lt;scope&amp;gt;.vercel.app&lt;/code&gt;, so a Stripe endpoint pointed at one commit's URL is stale after the next push. Vercel also gives each Git branch a URL, &lt;code&gt;&amp;lt;project&amp;gt;-git-&amp;lt;branch&amp;gt;-&amp;lt;scope&amp;gt;.vercel.app&lt;/code&gt;, which "won't change if you push new commits to the branch." If you want a test endpoint for Preview, point it at a branch URL (for example a long-lived &lt;code&gt;staging&lt;/code&gt; branch), not a commit URL.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Deployment Protection can block Stripe.&lt;/strong&gt; Vercel's &lt;strong&gt;Standard Protection&lt;/strong&gt; is available on every plan and protects everything except your production domains, which includes Preview URLs. With Vercel Authentication, an unauthenticated request gets redirected to a Vercel login. Stripe can't log in, and Stripe's docs say it treats redirects (&lt;code&gt;3xx&lt;/code&gt;) and access-restricted responses (&lt;code&gt;401&lt;/code&gt;, &lt;code&gt;403&lt;/code&gt;) as failed deliveries.&lt;/p&gt;

&lt;p&gt;You have two honest options:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Skip webhooks on Preview.&lt;/strong&gt; This is what I do for most projects. Local development uses the CLI, Production uses the live endpoint, and Preview is for looking at UI. Simple, and no extra secrets to manage.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use Protection Bypass for Automation.&lt;/strong&gt; Vercel supports a bypass secret sent as a header or as a query parameter named &lt;code&gt;x-vercel-protection-bypass&lt;/code&gt;, and its docs specifically mention the query parameter for services like Stripe that can't send custom headers. Your test endpoint URL becomes something like &lt;code&gt;https://&amp;lt;project&amp;gt;-git-staging-&amp;lt;scope&amp;gt;.vercel.app/api/webhooks/stripe?x-vercel-protection-bypass=&amp;lt;secret&amp;gt;&lt;/code&gt;. Two caveats: that bypass secret works for the whole project until you revoke it, so treat that endpoint URL as sensitive; and if you regenerate the bypass secret, Vercel says you need to redeploy, and you'll need to update the Stripe endpoint URL too.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Production domains aren't covered by Standard Protection, so your live endpoint on your own domain is reachable by default. If you've switched the project to &lt;strong&gt;All Deployments&lt;/strong&gt; protection, production is protected too, and Stripe will be blocked there as well.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two redirects that silently break production
&lt;/h2&gt;

&lt;p&gt;Since Stripe counts any &lt;code&gt;3xx&lt;/code&gt; as a failure (Stripe's fix is to "set the webhook endpoint destination to the URL resolved by the redirect"), check these before going live:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Domain redirects.&lt;/strong&gt; If &lt;code&gt;example.com&lt;/code&gt; redirects to &lt;code&gt;www.example.com&lt;/code&gt; (or the other way), register the final URL in Stripe.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Auth middleware.&lt;/strong&gt; If your &lt;code&gt;middleware.ts&lt;/code&gt; (renamed &lt;code&gt;proxy.ts&lt;/code&gt; in Next.js 16) redirects signed-out requests to &lt;code&gt;/login&lt;/code&gt;, make sure it skips the webhook route. Stripe never has a session cookie. One way is a matcher that excludes it:
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// middleware.ts (or proxy.ts on Next.js 16)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;config&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;matcher&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"/((?!api/webhooks|_next/static|_next/image|favicon.ico).*)"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A quick test: &lt;code&gt;curl -i -X POST https://your-domain.com/api/webhooks/stripe&lt;/code&gt;. You want a &lt;code&gt;400&lt;/code&gt; from your own handler (no signature), not a &lt;code&gt;301&lt;/code&gt;, &lt;code&gt;307&lt;/code&gt;, &lt;code&gt;401&lt;/code&gt;, or a Vercel login page.&lt;/p&gt;

&lt;h2&gt;
  
  
  Raw body: the other half of signature verification
&lt;/h2&gt;

&lt;p&gt;The right secret isn't enough if the body has changed. Stripe signs the exact bytes it sent, and its docs say "any manipulation to the raw body of the request causes the verification to fail." In an App Router route handler, read the body with &lt;code&gt;await req.text()&lt;/code&gt; and pass that string straight to &lt;code&gt;constructEvent&lt;/code&gt;, which is the same approach as Stripe's official Next.js App Router example in the stripe-node repo. Don't call &lt;code&gt;req.json()&lt;/code&gt; first.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/webhooks/stripe/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"stripe"&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;stripe&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;STRIPE_SECRET_KEY&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;secret&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;STRIPE_WEBHOOK_SECRET&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;secret&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Webhook secret not set"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="c1"&gt;// raw string, not req.json()&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;signature&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"stripe-signature"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;

  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Event&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;constructEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;signature&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;secret&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Invalid signature"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// Hand off to your idempotent sync code, then return 2xx quickly.&lt;/span&gt;
  &lt;span class="c1"&gt;// await handleStripeEvent(event)&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two debugging tips from Stripe's signature guide. Some deliveries include optional &lt;code&gt;secret=whsec_****...&lt;/code&gt; and &lt;code&gt;destination=we_...&lt;/code&gt; entries in the &lt;code&gt;Stripe-Signature&lt;/code&gt; header, a redacted hint of which endpoint secret Stripe signed with. Comparing the last few characters to yours is a quick way to spot a mix-up. Those entries aren't signed, so never use them to verify anything. And check your environment variable for stray whitespace from copy-pasting.&lt;/p&gt;

&lt;p&gt;What to do &lt;em&gt;after&lt;/em&gt; the signature passes (dedupe events, handle them out of order, return 2xx at the right time) is its own topic. I covered it in &lt;a href="https://shipember.com/blog/stripe-webhook-idempotency-nextjs.html" rel="noopener noreferrer"&gt;Stripe Webhooks in Next.js: Idempotency, Out-of-Order Events, and Retries&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  A first live test checklist
&lt;/h2&gt;

&lt;p&gt;Here's the order I go through the first time real money moves:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Create the live endpoint.&lt;/strong&gt; Switch the Dashboard to live mode, create a webhook endpoint for your final production URL (no redirects), and select only the events your handler uses.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Copy the live secret.&lt;/strong&gt; Reveal the endpoint's &lt;code&gt;whsec_&lt;/code&gt; and put it in Vercel's &lt;strong&gt;Production&lt;/strong&gt; scope as &lt;code&gt;STRIPE_WEBHOOK_SECRET&lt;/code&gt;, along with your &lt;code&gt;sk_live_&lt;/code&gt; key and live Price IDs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Redeploy Production.&lt;/strong&gt; New env values only reach new deployments.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Curl the endpoint.&lt;/strong&gt; &lt;code&gt;curl -i -X POST https://your-domain.com/api/webhooks/stripe&lt;/code&gt; should return your handler's &lt;code&gt;400&lt;/code&gt;, not a redirect or a login page.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Buy your own product.&lt;/strong&gt; Use a real card on your live Checkout.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check Event deliveries.&lt;/strong&gt; In Workbench, open the live endpoint's &lt;strong&gt;Event deliveries&lt;/strong&gt; tab and confirm &lt;code&gt;200&lt;/code&gt;s. If something fails, the status code tells you a lot: &lt;code&gt;3xx&lt;/code&gt; is a redirect, &lt;code&gt;401&lt;/code&gt;/&lt;code&gt;403&lt;/code&gt; is an access restriction, &lt;code&gt;400&lt;/code&gt; from your handler usually means the wrong secret or a changed body.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check your database.&lt;/strong&gt; The user should be on Pro because the webhook said so, not because they landed on the success page.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Undo it.&lt;/strong&gt; Refund yourself in the Dashboard and cancel the subscription (or cancel through the customer portal) and confirm the downgrade lands too.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;One timing note: Stripe retries failed live-mode deliveries for up to three days with exponential backoff, but sandbox deliveries are only retried three times over a few hours. If you fix a test setup the next morning, those old test events may be gone. Resend or re-trigger them.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;None of this needs a product. It's environment hygiene, and if you'd rather wire it up yourself, the table and checklist above should get you there. I built &lt;a href="https://shipember.com/" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt; because I kept redoing this exact setup, plus the auth, billing, and gating around it, for every new project.&lt;/p&gt;

&lt;p&gt;ShipEmber is a Next.js App Router starter with that loop already working: Auth.js v5 sign-in (Google, GitHub, and email magic links), Stripe Checkout, a customer portal route, a raw-body, signature-verified, idempotent webhook route that keeps Free/Pro in the database, Prisma with Postgres, and a dashboard that checks the plan on the server. You still create your own Stripe endpoints and paste in your own secrets (no kit can do that part for you), but the code on the other end is done.&lt;/p&gt;

&lt;p&gt;To be honest about where it doesn't fit: if you need teams, organizations, per-seat billing, or role-based permissions from day one, a bigger kit will serve you better. In my &lt;a href="https://shipember.com/blog/best-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;October 30 comparison&lt;/a&gt;, those kits were listed at $199 to $349 and up (ShipFast from $199, Makerkit Pro $349, supastarter Solo $349). ShipEmber is deliberately small, built for one product with a Free plan and a Pro plan.&lt;/p&gt;

&lt;p&gt;It's a one-time payment, &lt;strong&gt;$49&lt;/strong&gt; right now on the site (shown there as the launch price, with $79 listed as the regular price), and you can use it in unlimited personal and client projects. You get 14 days to ask for a refund if it doesn't work as described.&lt;/p&gt;

&lt;p&gt;Prefer watching over reading? There's a short walkthrough:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the ShipEmber walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;See pricing&lt;/a&gt; or &lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/stripe-webhook-idempotency-nextjs.html" rel="noopener noreferrer"&gt;Stripe Webhooks in Next.js: Idempotency, Out-of-Order Events, and Retries&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-stripe-authjs-setup-checklist.html" rel="noopener noreferrer"&gt;Next.js + Stripe + Auth.js setup checklist&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-free-vs-pro-feature-gating.html" rel="noopener noreferrer"&gt;Free vs Pro Feature Gating in Next.js App Router&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Doc note: CLI vs endpoint secrets, per-endpoint and per-mode secrets, raw-body guidance, the Stripe-Signature debug entries, redirect and 4xx delivery failures, and retry windows checked on docs.stripe.com/webhooks and docs.stripe.com/webhooks/signature; &lt;code&gt;stripe listen&lt;/code&gt; behavior on docs.stripe.com/cli/listen; env var scoping, redeploy behavior, &lt;code&gt;vercel env&lt;/code&gt; usage, generated URLs, Deployment Protection, and Protection Bypass for Automation checked on vercel.com/docs. All on November 12, 2026.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/stripe-webhook-secrets-local-vercel.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>stripe</category>
      <category>vercel</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Free vs Pro Feature Gating in Next.js App Router (2026): Pages, Server Actions, and API Routes</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Tue, 10 Nov 2026 16:28:31 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/free-vs-pro-feature-gating-in-nextjs-app-router-2026-pages-server-actions-and-api-routes-2f7k</link>
      <guid>https://dev.to/jakemcdonald/free-vs-pro-feature-gating-in-nextjs-app-router-2026-pages-server-actions-and-api-routes-2f7k</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 10, 2026 · About a 9-minute read · Checked against the Next.js, Auth.js, and Stripe docs&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. Once a SaaS has a Free plan and a Pro plan, every new feature comes with the same quiet question: &lt;em&gt;who is allowed to use this, and where do I check?&lt;/em&gt; The first answer most of us reach for is to hide the button for Free users and maybe add a redirect in middleware. It looks done. It isn't.&lt;/p&gt;

&lt;p&gt;This post is the gating setup I use in &lt;strong&gt;Next.js App Router&lt;/strong&gt; apps: one server-only helper that reads the plan from the database, a &lt;code&gt;requirePro()&lt;/code&gt; wrapper for pages and Server Actions, a 401/403 check for route handlers, and a short list of places where a check looks like protection but isn't. Everything here was checked against the &lt;a href="https://nextjs.org/docs/app/guides/authentication" rel="noopener noreferrer"&gt;Next.js authentication guide&lt;/a&gt;, the &lt;a href="https://authjs.dev/getting-started/session-management/protecting" rel="noopener noreferrer"&gt;Auth.js protecting resources docs&lt;/a&gt;, and &lt;a href="https://docs.stripe.com/checkout/fulfillment" rel="noopener noreferrer"&gt;Stripe's fulfillment docs&lt;/a&gt; on November 10, 2026.&lt;/p&gt;

&lt;h2&gt;
  
  
  The rule: every entry point checks for itself
&lt;/h2&gt;

&lt;p&gt;A Next.js app has more doors than it looks like. A Pro feature can be reached through:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The page&lt;/strong&gt; that renders it (a Server Component).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The Server Action&lt;/strong&gt; that a form or button on that page calls.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The route handler&lt;/strong&gt; under &lt;code&gt;app/api/...&lt;/code&gt; that a client component, a script, or &lt;code&gt;curl&lt;/code&gt; can hit directly.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The Next.js docs say it plainly: treat Server Actions and Route Handlers "with the same security considerations as public-facing API endpoints." Hiding a button doesn't stop anyone from calling the action behind it, and a page redirect doesn't protect an API route that lives at a different URL. So the rule I follow is simple: &lt;strong&gt;each of those three entry points checks the plan itself, on the server, using the same helper.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Read the plan from your database, not from the session cookie
&lt;/h2&gt;

&lt;p&gt;The plan should live in your database, written by your Stripe webhook handler, and be read fresh on the server whenever you make a decision with it. Two reasons:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Plans change without the user doing anything.&lt;/strong&gt; A card fails, a subscription is canceled in the customer portal, a trial ends. Stripe tells your webhook, your webhook updates the row, and the very next request should see it. If you copied the plan into a JWT or cookie at sign-in, the user keeps Pro until that token is refreshed.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It's the one source of truth.&lt;/strong&gt; If the page, the action, and the API route all read the same row through the same function, they can't disagree.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Here's the helper. It assumes Auth.js v5 with the &lt;code&gt;auth()&lt;/code&gt; function exported from your &lt;code&gt;auth.ts&lt;/code&gt; file, and a session callback that puts the user's ID on &lt;code&gt;session.user.id&lt;/code&gt; (with the database session strategy, that's &lt;code&gt;session.user.id = user.id&lt;/code&gt; in the &lt;code&gt;session&lt;/code&gt; callback). The schema is the usual one: a &lt;code&gt;User&lt;/code&gt; with a &lt;code&gt;plan&lt;/code&gt; of &lt;code&gt;FREE&lt;/code&gt; or &lt;code&gt;PRO&lt;/code&gt;, and an optional &lt;code&gt;Subscription&lt;/code&gt; row with the Stripe status.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/billing.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="s2"&gt;"server-only"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;cache&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"react"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@/auth"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;prisma&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/prisma"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;hasProAccess&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;plan&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="o"&gt;?:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;plan&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="s2"&gt;"PRO"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="c1"&gt;// manual grant, no Stripe subscription&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"ACTIVE"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"TRIALING"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;getViewer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;cache&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findUnique&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;select&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;plan&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;subscription&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;select&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;isPro&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;hasProAccess&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;plan&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;subscription&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few notes on why it looks like this:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;import "server-only"&lt;/code&gt; makes the build fail if a Client Component ever imports this file, which is exactly what you want for anything that touches the database.&lt;/li&gt;
&lt;li&gt;React's &lt;code&gt;cache&lt;/code&gt; means a page and its child components can all call &lt;code&gt;getViewer()&lt;/code&gt; in one render and only hit the database once. The Next.js docs point out that &lt;code&gt;cache&lt;/code&gt; only dedupes within a render pass; in Server Actions and Route Handlers it does nothing and the function just runs every time. That's fine. It's still correct, just not memoized.&lt;/li&gt;
&lt;li&gt;It returns a small object (ID, email, &lt;code&gt;isPro&lt;/code&gt;), not the whole user row. That's the "Data Transfer Object" idea from the Next.js guide: only pass along what callers need.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;PAST_DUE&lt;/code&gt; counts as Free in this version. Some apps give a grace period instead. That's a product choice, and this function is the one place to make it.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 2: A requirePro() helper for pages and Server Actions
&lt;/h2&gt;

&lt;p&gt;Pages and Server Actions want the same behavior: no session goes to login, a Free user goes to pricing, a Pro user gets through.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/billing.ts (continued)&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;redirect&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"next/navigation"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;requireUser&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;viewer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;getViewer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;viewer&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nf"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/login"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;viewer&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;requirePro&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;viewer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;requireUser&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;viewer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;isPro&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nf"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"/pricing?upgrade=1"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;viewer&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;redirect()&lt;/code&gt; from &lt;code&gt;next/navigation&lt;/code&gt; throws (a &lt;code&gt;NEXT_REDIRECT&lt;/code&gt; error) and stops rendering, and its return type is &lt;code&gt;never&lt;/code&gt;, so TypeScript knows &lt;code&gt;viewer&lt;/code&gt; is non-null after those lines. One gotcha from the Next.js docs: because it works by throwing, &lt;strong&gt;call &lt;code&gt;redirect()&lt;/code&gt; outside of any &lt;code&gt;try/catch&lt;/code&gt;&lt;/strong&gt;, or your &lt;code&gt;catch&lt;/code&gt; block will swallow it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Gating a page
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/dashboard/reports/page.tsx&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;requirePro&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/billing"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;ReportsPage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;viewer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;requirePro&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;reports&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;getReportsFor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;viewer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;ReportsTable&lt;/span&gt; &lt;span class="n"&gt;reports&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;reports&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="o"&gt;/&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Because the page calls &lt;code&gt;auth()&lt;/code&gt; (which reads cookies), it renders per request, not at build time. That matters: if Pro content ends up in a statically rendered page, it's generated once and served to everyone.&lt;/p&gt;

&lt;p&gt;If a page has Free and Pro sections, gate the Pro section instead of the whole page. An async Server Component can call &lt;code&gt;getViewer()&lt;/code&gt; and render an upgrade card instead of the Pro content. Thanks to &lt;code&gt;cache&lt;/code&gt;, it won't cost another database query.&lt;/p&gt;

&lt;h3&gt;
  
  
  Gating a Server Action
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/dashboard/reports/actions.ts&lt;/span&gt;
&lt;span class="s2"&gt;"use server"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;requirePro&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/billing"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;exportReportsCsv&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;viewer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;requirePro&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="c1"&gt;// Only reached by signed-in Pro users&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;buildCsvFor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;viewer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The check lives inside the action, not just on the page that shows the button. If the page already checked, this looks redundant. It isn't: the action is its own endpoint, and anyone with a Free account can call it without going through your UI.&lt;/p&gt;

&lt;p&gt;One related trap from the Next.js docs: &lt;strong&gt;don't rely on a layout for the check.&lt;/strong&gt; Because of partial rendering, layouts don't re-render on every navigation, and a layout that hides &lt;code&gt;{children}&lt;/code&gt; doesn't stop the nested page or its Server Actions from running. Do the check in the page, the component, and the action that actually touch the data.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Gate API routes with 401 and 403, not redirects
&lt;/h2&gt;

&lt;p&gt;Route handlers are usually called by &lt;code&gt;fetch&lt;/code&gt;, scripts, or other services, so a redirect to &lt;code&gt;/login&lt;/code&gt; is the wrong answer. Return a status code, the same two-tier way the Next.js docs show: 401 when there's no session, 403 when there is a session but not enough access.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/reports/export/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;getViewer&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@/lib/billing"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;GET&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;viewer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;getViewer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;viewer&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Sign in required"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;401&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;viewer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;isPro&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Pro plan required"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;403&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;csv&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;buildCsvFor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;viewer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;csv&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"Content-Type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"text/csv"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Your client code can then handle a 403 by showing the upgrade prompt, and nothing Pro-only is ever sent to a Free user.&lt;/p&gt;

&lt;p&gt;The one route that should &lt;strong&gt;not&lt;/strong&gt; have this check is your Stripe webhook. It's called by Stripe, not by a signed-in user, and it proves itself with a signature instead of a session. Keep it out of your auth checks and out of your proxy matcher, or Stripe will get redirects and count them as failed deliveries.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why middleware (proxy) and UI-only checks aren't enough
&lt;/h2&gt;

&lt;p&gt;As of Next.js 16, &lt;code&gt;middleware.ts&lt;/code&gt; has been renamed to &lt;code&gt;proxy.ts&lt;/code&gt;. Auth.js supports it directly: &lt;code&gt;export { auth as proxy } from "@/auth"&lt;/code&gt;, or &lt;code&gt;export { auth as middleware }&lt;/code&gt; on older Next.js versions. It's a nice way to bounce signed-out users away from &lt;code&gt;/dashboard&lt;/code&gt; before anything renders. I use it. But both the Next.js docs and the Auth.js docs say not to rely on it alone, and there are concrete reasons:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It's meant for optimistic checks.&lt;/strong&gt; Proxy runs on every matching route, including prefetches, so the Next.js docs recommend reading only the session cookie there and skipping database checks. That means it can tell "signed in" from "signed out," but it's the wrong place to decide "Pro" from "Free" against fresh data.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Matchers have gaps.&lt;/strong&gt; Common matchers exclude &lt;code&gt;/api&lt;/code&gt; on purpose. That's correct for your webhook, but it also means your API routes are not covered by the proxy at all.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It has been bypassed before.&lt;/strong&gt; CVE-2025-29927 let attackers skip middleware entirely by sending an internal &lt;code&gt;x-middleware-subrequest&lt;/code&gt; header, which bypassed any auth check that lived only in middleware. It was fixed in Next.js 15.2.3, 14.2.25, 13.5.9, and 12.3.5, and Vercel-hosted apps weren't affected. But apps that also checked on the server were fine either way. Defense in depth is the real lesson.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;UI-only checks are weaker still. &lt;code&gt;{isPro &amp;amp;&amp;amp; &amp;lt;ExportButton /&amp;gt;}&lt;/code&gt; is good UX, so keep it. But it's a display choice, not access control. The Next.js docs say it directly: client-side UI restrictions alone aren't sufficient, and Server Actions called from those components need their own checks.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Checkout success URL is not a receipt
&lt;/h2&gt;

&lt;p&gt;This is the gating mistake I see most often in Stripe tutorials: the success page reads &lt;code&gt;?success=true&lt;/code&gt; (or just the fact that the user landed there) and flips them to Pro. Anyone can type that URL.&lt;/p&gt;

&lt;p&gt;Stripe's docs are clear that webhooks are required: "You can't rely on triggering fulfillment only from your Checkout landing page, because it's not guaranteed customers visit that page." Someone can pay and lose their connection before the page loads. And for subscriptions specifically, Stripe says webhook fulfillment is required because the subscription's state keeps changing after Checkout.&lt;/p&gt;

&lt;p&gt;So the flow I use is:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Your webhook handler (verified signature, idempotent) is the thing that writes &lt;code&gt;plan&lt;/code&gt; and &lt;code&gt;subscription.status&lt;/code&gt;. That's covered in my &lt;a href="https://shipember.com/blog/stripe-webhook-idempotency-nextjs.html" rel="noopener noreferrer"&gt;Stripe webhook idempotency post&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;The success page is just a page. It calls &lt;code&gt;getViewer()&lt;/code&gt; like every other page and shows "You're on Pro" if the database says so, or "Payment received, activating your account..." if the webhook hasn't landed yet.&lt;/li&gt;
&lt;li&gt;If you want instant activation, Stripe's docs also recommend triggering fulfillment from the landing page: put &lt;code&gt;{CHECKOUT_SESSION_ID}&lt;/code&gt; in your &lt;code&gt;success_url&lt;/code&gt;, retrieve that Checkout Session &lt;strong&gt;on the server&lt;/strong&gt; with your secret key, check it belongs to the signed-in user and is actually paid, and then call the &lt;strong&gt;same&lt;/strong&gt; idempotent sync function your webhook uses. Never trust the query string by itself.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Worth knowing: with a webhook endpoint listening for &lt;code&gt;checkout.session.completed&lt;/code&gt;, Stripe's docs say Checkout waits up to 10 seconds for your server to respond before redirecting the customer (that wait doesn't apply to endpoints registered in a Stripe organization account). With a fast webhook, the plan is often already updated by the time they land. (When testing locally with the Stripe CLI, Checkout redirects immediately, so you'll see the "activating" state more often in dev.)&lt;/p&gt;

&lt;h2&gt;
  
  
  A quick test plan
&lt;/h2&gt;

&lt;p&gt;Before you ship a new Pro feature, run these. They take ten minutes:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Signed out:&lt;/strong&gt; open the Pro page in a private window. You should land on &lt;code&gt;/login&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Free user:&lt;/strong&gt; open the Pro page. You should land on &lt;code&gt;/pricing?upgrade=1&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;API, no cookie:&lt;/strong&gt; &lt;code&gt;curl -i https://your-app.com/api/reports/export&lt;/code&gt;. You should get a &lt;code&gt;401&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;API, Free user:&lt;/strong&gt; call the same route from the browser console while signed in as a Free user. You should get a &lt;code&gt;403&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Server Action as Free:&lt;/strong&gt; temporarily render the Pro button for everyone and click it as a Free user. You should get redirected and nothing should be exported. Then remove the temporary change.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Downgrade:&lt;/strong&gt; cancel a test subscription in the customer portal. Once the webhook lands, the next request should treat the user as Free. No sign-out needed.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fake success:&lt;/strong&gt; visit your success URL by hand with a made-up &lt;code&gt;session_id&lt;/code&gt;. Nothing should change.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;None of this needs a library. It's a few dozen lines, and if you want to own every one of them, this post should get you there. I built &lt;a href="https://shipember.com/" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt; because I kept rewriting this same plan helper, webhook sync, and gated dashboard for every project.&lt;/p&gt;

&lt;p&gt;ShipEmber is a Next.js App Router starter with that loop already working: Auth.js v5 sign-in (Google, GitHub, and email magic links), Stripe Checkout, a customer portal route, signed and idempotent webhooks that keep Free/Pro in the database, Prisma with Postgres, and a dashboard that checks the plan on the server. You rename it, add your keys, and spend your time on the Pro features themselves instead of the plumbing around them.&lt;/p&gt;

&lt;p&gt;To be honest about where it doesn't fit: if you need teams, organizations, per-seat billing, or role-based permissions from day one, a bigger kit will serve you better. ShipEmber is deliberately small, built for one product with a Free plan and a Pro plan.&lt;/p&gt;

&lt;p&gt;It's a one-time payment, &lt;strong&gt;$49&lt;/strong&gt; right now on the site (shown there as the launch price, with $79 listed as the regular price), and you can use it in unlimited personal and client projects. You get 14 days to ask for a refund if it doesn't work as described.&lt;/p&gt;

&lt;p&gt;Prefer watching over reading? There's a short walkthrough:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the ShipEmber walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;See pricing&lt;/a&gt; or &lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/stripe-webhook-idempotency-nextjs.html" rel="noopener noreferrer"&gt;Stripe Webhooks in Next.js: Idempotency, Out-of-Order Events, and Retries&lt;/a&gt; · &lt;a href="https://shipember.com/blog/stripe-customer-portal-nextjs.html" rel="noopener noreferrer"&gt;Stripe Customer Portal in Next.js&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-stripe-authjs-setup-checklist.html" rel="noopener noreferrer"&gt;Next.js + Stripe + Auth.js setup checklist&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Doc note: authorization guidance, &lt;code&gt;redirect()&lt;/code&gt; behavior, &lt;code&gt;cache&lt;/code&gt; scope, and the proxy rename checked on nextjs.org; &lt;code&gt;auth()&lt;/code&gt; and proxy usage checked on authjs.dev; landing-page and webhook fulfillment guidance checked on docs.stripe.com/checkout/fulfillment; CVE-2025-29927 versions checked on the GitHub advisory GHSA-f82v-jwr5-mffw. All on November 10, 2026.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/nextjs-free-vs-pro-feature-gating.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>stripe</category>
      <category>saas</category>
      <category>security</category>
    </item>
    <item>
      <title>Stripe Webhooks in Next.js: Idempotency, Out-of-Order Events, and Retries (2026)</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Thu, 05 Nov 2026 16:09:41 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/stripe-webhooks-in-nextjs-idempotency-out-of-order-events-and-retries-2026-2md0</link>
      <guid>https://dev.to/jakemcdonald/stripe-webhooks-in-nextjs-idempotency-out-of-order-events-and-retries-2026-2md0</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 5, 2026 · About a 10-minute read · Checked against Stripe's webhook docs&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. Most first Stripe webhook handlers look about the same: verify the signature, flip the user to Pro, return 200. Fifteen lines, and it works fine in test mode. Then you read the "Event delivery behaviors" section of Stripe's docs and notice three assumptions hiding in those fifteen lines that aren't true: that each event arrives once, that events arrive in order, and that if your code fails, nothing bad happens.&lt;/p&gt;

&lt;p&gt;This post is the version I wish I'd read first. It covers the three delivery behaviors you have to design for in a &lt;strong&gt;Next.js App Router&lt;/strong&gt; route handler (duplicates, out-of-order events, and retries), plus the signature check that has to come before all of it. Everything here was checked against &lt;a href="https://docs.stripe.com/webhooks" rel="noopener noreferrer"&gt;Stripe's webhook docs&lt;/a&gt; on November 5, 2026.&lt;/p&gt;

&lt;h2&gt;
  
  
  The three things Stripe tells you up front
&lt;/h2&gt;

&lt;p&gt;Straight from Stripe's docs, in plain words:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Duplicates happen.&lt;/strong&gt; "Webhook endpoints might occasionally receive the same event more than once." Stripe's advice is to log the event IDs you've processed and skip ones you've already handled. In some cases Stripe even generates two separate Event objects for the same thing, so the event ID alone won't catch everything.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Order isn't guaranteed.&lt;/strong&gt; "Stripe doesn't guarantee the delivery of events in the order that they're generated." Creating a subscription can fire &lt;code&gt;customer.subscription.created&lt;/code&gt;, &lt;code&gt;invoice.created&lt;/code&gt;, &lt;code&gt;invoice.paid&lt;/code&gt;, and &lt;code&gt;charge.created&lt;/code&gt;, and you can receive them in any order. Stripe also says not to use the event's &lt;code&gt;created&lt;/code&gt; timestamp to figure out order, because it's in seconds and different events can share it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Failures get retried.&lt;/strong&gt; In live mode, Stripe keeps trying to deliver an event for &lt;strong&gt;up to three days&lt;/strong&gt; with exponential backoff. In a sandbox, it retries three times over a few hours. You can also resend events by hand from the Dashboard (up to 15 days after the event) or with the Stripe CLI (up to 30 days).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Put those together and you get the real job of a webhook handler: &lt;strong&gt;applying the same event twice, or getting events in the wrong order, has to leave your database in the right state.&lt;/strong&gt; Everything below is about making that true.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Verify the signature on the raw body
&lt;/h2&gt;

&lt;p&gt;Before anything else, prove the request came from Stripe. Without that check, anyone who finds your endpoint URL can POST a fake &lt;code&gt;customer.subscription.updated&lt;/code&gt; and give themselves Pro.&lt;/p&gt;

&lt;p&gt;Stripe signs every event in the &lt;code&gt;Stripe-Signature&lt;/code&gt; header, and its docs are blunt about one thing: verification needs the &lt;strong&gt;raw body&lt;/strong&gt;, exactly as it was sent. If anything parses and re-serializes the JSON first, the signature check fails.&lt;/p&gt;

&lt;p&gt;In the App Router this is easy, because a route handler gets a standard Web &lt;code&gt;Request&lt;/code&gt;. Read the body with &lt;code&gt;await request.text()&lt;/code&gt;, not &lt;code&gt;request.json()&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/stripe/webhook/route.ts (signature check only)&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;runtime&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;nodejs&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="c1"&gt;// raw body, untouched&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sig&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe-signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;sig&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Missing signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;

  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Event&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;constructEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;sig&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;STRIPE_WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Bad signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// ...handle the event (full route in Step 3)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few things that commonly trip people up:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Each endpoint has its own secret.&lt;/strong&gt; The &lt;code&gt;whsec_...&lt;/code&gt; from &lt;code&gt;stripe listen&lt;/code&gt;, your sandbox endpoint, and your live endpoint are all different. If it works locally and fails in production, check this first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Don't turn off the timestamp check.&lt;/strong&gt; The Stripe libraries reject events whose signed timestamp is more than 5 minutes off by default, which protects you from replayed requests. Stripe's docs specifically say not to set the tolerance to &lt;code&gt;0&lt;/code&gt;, because that disables the check.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Redirects count as failures.&lt;/strong&gt; Stripe treats a &lt;code&gt;3xx&lt;/code&gt; response as a failed delivery. If your middleware (renamed &lt;code&gt;proxy.ts&lt;/code&gt; in Next.js 16) redirects unauthenticated requests to &lt;code&gt;/login&lt;/code&gt;, or your domain redirects &lt;code&gt;example.com&lt;/code&gt; to &lt;code&gt;www.example.com&lt;/code&gt;, your webhook will fail even though your code is fine. Exclude the webhook path from auth middleware and register the final URL.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;If you run on the Edge runtime,&lt;/strong&gt; use &lt;code&gt;constructEventAsync&lt;/code&gt; instead. I keep this route on the Node.js runtime, which is the default for route handlers anyway.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 2: An event table that actually prevents double processing
&lt;/h2&gt;

&lt;p&gt;The usual idempotency advice is "store &lt;code&gt;event.id&lt;/code&gt; and skip events you've seen." That's right, but the obvious way to write it has a gap. In my own &lt;a href="https://shipember.com/blog/nextjs-stripe-authjs-setup-checklist.html" rel="noopener noreferrer"&gt;setup checklist&lt;/a&gt;, I showed the simple version: look up the event ID, do the work, then insert the ID. If two deliveries of the same event land at the same time, both lookups can come back empty and both do the work. For "set plan to Pro" that's harmless. For "send a welcome email" or "add 100 credits," it isn't.&lt;/p&gt;

&lt;p&gt;The fix is to let the database decide. Make the Stripe event ID a primary key and &lt;strong&gt;claim&lt;/strong&gt; the event inside the same transaction as the work:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;model StripeEvent {
  id        String   @id // the evt_... ID from Stripe
  type      String
  createdAt DateTime @default(now())
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/stripe-events.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Prisma&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@prisma/client&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/db&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;processOnce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Event&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;work&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;TransactionClient&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="k"&gt;void&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;$transaction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Postgres: INSERT ... ON CONFLICT DO NOTHING&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;claimed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeEvent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createMany&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
      &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="p"&gt;}],&lt;/span&gt;
      &lt;span class="na"&gt;skipDuplicates&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;})&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;claimed&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;count&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;duplicate&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="kd"&gt;as const&lt;/span&gt;

    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;work&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;processed&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="kd"&gt;as const&lt;/span&gt;
  &lt;span class="p"&gt;})&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Why this works:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;If the event was already processed, the insert does nothing, &lt;code&gt;count&lt;/code&gt; is &lt;code&gt;0&lt;/code&gt;, and you skip the work.&lt;/li&gt;
&lt;li&gt;If two deliveries race, Postgres makes the second insert wait for the first transaction. If the first commits, the second sees a conflict and skips. If the first fails and rolls back, the second one claims the event and does the work.&lt;/li&gt;
&lt;li&gt;If your work throws, the whole transaction rolls back, &lt;strong&gt;including the event row&lt;/strong&gt;. So a failed event isn't marked as handled, and Stripe's retry gets a real second chance.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That last point is the one people miss. If you record the event ID first and commit it separately, a crash halfway through leaves you with an event you've "seen" but never actually applied, and every retry will skip it.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;skipDuplicates&lt;/code&gt; isn't supported on every database Prisma talks to, so check your provider. On Postgres (which is what I use) it's fine.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 3: Make out-of-order events boring
&lt;/h2&gt;

&lt;p&gt;Here's the bug out-of-order delivery causes. A customer upgrades, then cancels a minute later. You receive the cancel's &lt;code&gt;customer.subscription.updated&lt;/code&gt; first and the upgrade's second. If your handler copies &lt;code&gt;event.data.object&lt;/code&gt; straight into your database, the stale event wins and they're back on an active plan they canceled.&lt;/p&gt;

&lt;p&gt;You could compare timestamps, but Stripe's docs say not to use &lt;code&gt;created&lt;/code&gt; for ordering. What I do instead is treat the event as a &lt;strong&gt;notification, not the data&lt;/strong&gt;. When anything subscription-related arrives, I fetch the subscription's current state from Stripe and write that. It doesn't matter which event shows up first, because both handlers end up writing whatever is true right now. Stripe's docs suggest this too: use the API to retrieve the objects you need.&lt;/p&gt;

&lt;p&gt;Here's the whole route, with the signature check from Step 1 and &lt;code&gt;processOnce&lt;/code&gt; from Step 2:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/stripe/webhook/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;processOnce&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe-events&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;runtime&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;nodejs&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;subscriptionIdFrom&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Event&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;switch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;checkout.session.completed&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;object&lt;/span&gt;
      &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;mode&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;subscription&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscription&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscription&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;string&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
        &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscription&lt;/span&gt;
        &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscription&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.created&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.updated&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.deleted&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;object&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
    &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sig&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe-signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;sig&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Missing signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;

  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Event&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;constructEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;sig&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;STRIPE_WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Bad signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;subscriptionId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;subscriptionIdFrom&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;subscriptionId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ignored&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;

  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Fetch current state *before* opening the DB transaction,&lt;/span&gt;
    &lt;span class="c1"&gt;// so a slow network call doesn't hold a transaction open.&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscriptions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;retrieve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;subscriptionId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;customerId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
      &lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customer&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;string&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customer&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;isPro&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;active&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;trialing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;processOnce&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
        &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;customerId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="na"&gt;plan&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;isPro&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;pro&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;free&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="na"&gt;stripeSubscriptionId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="na"&gt;subscriptionStatus&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="na"&gt;cancelsAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;cancel_at&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;cancel_at&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;},&lt;/span&gt;
      &lt;span class="p"&gt;})&lt;/span&gt;
    &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Stripe webhook failed&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Try again later&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ok&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few notes on this:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The work is "set," never "add."&lt;/strong&gt; Writing &lt;code&gt;plan: "pro"&lt;/code&gt; twice gives the same result as writing it once. That's what makes the "two separate Event objects" case from Stripe's docs harmless too. Anything that increments, sends email, or calls another API needs to go through &lt;code&gt;processOnce&lt;/code&gt; and nothing else.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A missing user is a retry, not a crash.&lt;/strong&gt; I create the Stripe customer before Checkout and save its ID on the user (with &lt;code&gt;stripeCustomerId&lt;/code&gt; marked &lt;code&gt;@unique&lt;/code&gt;), so every event can be matched by customer ID. If an event somehow arrives before that row exists, &lt;code&gt;update&lt;/code&gt; throws, the route returns 500, and Stripe tries again later. That's what you want.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Retrieving a canceled subscription still works,&lt;/strong&gt; so &lt;code&gt;customer.subscription.deleted&lt;/code&gt; goes through the same path and lands the user on Free.&lt;/li&gt;
&lt;li&gt;Whether &lt;code&gt;past_due&lt;/code&gt; keeps Pro is a product decision. I treat only &lt;code&gt;active&lt;/code&gt; and &lt;code&gt;trialing&lt;/code&gt; as Pro, but a short grace period is reasonable.&lt;/li&gt;
&lt;li&gt;Two different events for the same subscription can still run at nearly the same time. Both fetch fresh state from Stripe, so for a Free/Pro app the last write is fine. If you're doing something heavier, lock the user row.&lt;/li&gt;
&lt;li&gt;Only subscribe your endpoint to the event types you actually handle. Stripe recommends this too, and it keeps the noise down.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This post uses snapshot events (the &lt;code&gt;Stripe.Event&lt;/code&gt; objects &lt;code&gt;constructEvent&lt;/code&gt; returns). Stripe's docs also describe newer "thin" events. I'm not covering those here, but the duplicate and ordering rules above still apply.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: Return 2xx quickly, but not too early
&lt;/h2&gt;

&lt;p&gt;Stripe's docs say your endpoint should "quickly return a successful status code (&lt;code&gt;2xx&lt;/code&gt;) before any complex logic that could cause a timeout." That's easy to misread as "always return 200 right away, then do the work."&lt;/p&gt;

&lt;p&gt;Here's the trap. Once you return 2xx, Stripe considers the event delivered and stops retrying. If you return 200 and then do the real work afterward, for example in Next.js's &lt;code&gt;after()&lt;/code&gt; (stable since 15.1), a database error at that point is silent. Stripe won't retry, and that customer stays on Free even though they paid. You've thrown away three days of automatic retries.&lt;/p&gt;

&lt;p&gt;So I think of it like this:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Small, fast work (most Free/Pro apps):&lt;/strong&gt; do it inline like the route above, a single Stripe read and one short transaction. Return 200 only after it commits. Return 500 if it fails so Stripe retries.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Slow or heavy work (generating files, calling several APIs, sending lots of email):&lt;/strong&gt; inside the request, only verify the signature and &lt;strong&gt;durably save&lt;/strong&gt; the event, for example a row with a &lt;code&gt;processedAt&lt;/code&gt; column left empty, or a message on a real queue. Then return 200, and process it in a background job that can retry on its own. Stripe recommends an async queue for exactly this, especially for spikes like the start of the month when renewals all hit at once.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;after()&lt;/code&gt; is fine for extras you can afford to lose,&lt;/strong&gt; like logging or analytics. It isn't a substitute for a durable queue.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 5: Prove it before real customers do
&lt;/h2&gt;

&lt;p&gt;Here's the test run I'd do in a sandbox before launch:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Run &lt;code&gt;stripe listen --forward-to localhost:3000/api/stripe/webhook&lt;/code&gt;, put the &lt;code&gt;whsec_...&lt;/code&gt; it prints in your local env, and subscribe with a test card. Confirm the user becomes Pro and one &lt;code&gt;StripeEvent&lt;/code&gt; row appears per event.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Duplicates:&lt;/strong&gt; deploy to a sandbox endpoint, then resend one of those events from the event's page in the Dashboard (or &lt;code&gt;stripe events resend &amp;lt;event_id&amp;gt; --webhook-endpoint=&amp;lt;endpoint_id&amp;gt;&lt;/code&gt;). The second delivery should return 200, and nothing else in your database should change.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Failures:&lt;/strong&gt; make the handler throw on purpose (for example, point it at a user that doesn't exist) and check the endpoint's Event deliveries tab. You should see failed attempts and a scheduled retry. Remember that sandbox retries only happen three times over a few hours, while live mode retries for up to three days.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Order:&lt;/strong&gt; cancel and reactivate quickly in the customer portal. Whatever order the &lt;code&gt;customer.subscription.updated&lt;/code&gt; events land in, the final row should match what the Dashboard shows.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Bad signature:&lt;/strong&gt; &lt;code&gt;curl -X POST&lt;/code&gt; your endpoint with a junk body. You should get a 400 and no database change.&lt;/li&gt;
&lt;li&gt;Do a real purchase in &lt;strong&gt;live mode&lt;/strong&gt; with your own card and refund it. The live endpoint has its own signing secret, and that's the one people forget.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;None of this is secret knowledge. It's all in Stripe's docs, and if you want to own every line, this post should get you there. I built &lt;a href="https://shipember.com/" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt; because I got tired of rebuilding this same webhook, plan sync, and gating loop for every project.&lt;/p&gt;

&lt;p&gt;ShipEmber is a Next.js App Router starter that already has it working: Auth.js sign-in (Google, GitHub, magic links), Stripe Checkout, a customer portal route, signed and idempotent webhooks that keep Free/Pro in sync, Prisma with Postgres, and a dashboard gated on the server. You rename it, add your Stripe keys, and spend the weekend on the thing your customers actually pay for.&lt;/p&gt;

&lt;p&gt;To be honest about where it doesn't fit: if you need multi-tenant teams, organizations, and per-seat billing from day one, a bigger kit will be a better fit. ShipEmber is deliberately small, built for one product with a Free plan and a Pro plan.&lt;/p&gt;

&lt;p&gt;It's a one-time payment, &lt;strong&gt;$49&lt;/strong&gt; right now on the site, and you can use it in unlimited personal and client projects. You get 14 days to ask for a refund if it doesn't work as described.&lt;/p&gt;

&lt;p&gt;Prefer watching over reading? There's a short walkthrough:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the ShipEmber walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;See pricing&lt;/a&gt; or &lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/nextjs-stripe-authjs-setup-checklist.html" rel="noopener noreferrer"&gt;Next.js + Stripe + Auth.js setup checklist&lt;/a&gt; · &lt;a href="https://shipember.com/blog/stripe-customer-portal-nextjs.html" rel="noopener noreferrer"&gt;Stripe Customer Portal in Next.js&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;How to add Stripe subscriptions to a Next.js App Router app&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/stripe-webhook-idempotency-nextjs.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>stripe</category>
      <category>webdev</category>
      <category>saas</category>
    </item>
    <item>
      <title>Stripe Customer Portal in Next.js: Skip Building Cancel and Upgrade UI (2026)</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Tue, 03 Nov 2026 16:11:41 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/stripe-customer-portal-in-nextjs-skip-building-cancel-and-upgrade-ui-2026-ko9</link>
      <guid>https://dev.to/jakemcdonald/stripe-customer-portal-in-nextjs-skip-building-cancel-and-upgrade-ui-2026-ko9</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 3, 2026 · About a 9-minute read · Checked against Stripe's customer portal docs&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. The first SaaS I wired up, I spent most of a weekend building a "Manage subscription" page: a cancel button, an "are you sure?" modal, a card update form, a plan switcher, and an invoice list. Then I found out Stripe already hosts all of that for you. It's called the &lt;strong&gt;customer portal&lt;/strong&gt;, and for most indie SaaS apps it's the right call.&lt;/p&gt;

&lt;p&gt;This post covers how I set it up in a &lt;strong&gt;Next.js App Router&lt;/strong&gt; app: what to switch on in the Stripe Dashboard, the small route that creates a portal session, deep links for "Cancel" and "Change plan" buttons, and the webhooks you still need so your database stays in sync. Everything here was checked against &lt;a href="https://docs.stripe.com/customer-management/integrate-customer-portal" rel="noopener noreferrer"&gt;Stripe's customer portal docs&lt;/a&gt; on November 3, 2026.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the portal does for you
&lt;/h2&gt;

&lt;p&gt;The customer portal is a Stripe-hosted, co-branded page. You send a signed-in user there, they manage their billing, and they click back to your app. Depending on how you configure it, they can:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Cancel their subscription (and optionally tell you why)&lt;/li&gt;
&lt;li&gt;Switch plans (upgrade or downgrade between prices you choose)&lt;/li&gt;
&lt;li&gt;Update their payment method&lt;/li&gt;
&lt;li&gt;Update billing details like name, email, address, and tax ID&lt;/li&gt;
&lt;li&gt;See and download their invoice history&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;What it &lt;strong&gt;doesn't&lt;/strong&gt; do: it doesn't change anything in your database. It updates the subscription in Stripe and Stripe tells you about it through webhooks. That part is still on you, and it's where most bugs show up.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 1: Configure the portal in the Stripe Dashboard
&lt;/h2&gt;

&lt;p&gt;Open the customer portal settings in the Stripe Dashboard. The defaults are a reasonable start, but here's what I look at (defaults per Stripe's &lt;a href="https://docs.stripe.com/customer-management/configure-portal" rel="noopener noreferrer"&gt;configure the portal&lt;/a&gt; page):&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Cancel subscription:&lt;/strong&gt; on by default. You also choose whether cancel happens right away or at the end of the billing period. For a Free/Pro SaaS I pick end of period, because people paid for the month.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cancellation reason:&lt;/strong&gt; on by default. Leave it on. It's free customer research.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Switch plan:&lt;/strong&gt; off by default. If you have more than one paid price (monthly and yearly, or Pro and Team), turn this on and add those products to the portal's product catalog. Stripe requires the catalog if you allow upgrades or downgrades.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Prorations:&lt;/strong&gt; off by default. Decide on purpose instead of finding out from a confused customer email.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Payment methods:&lt;/strong&gt; on by default. Keep it on. This is what saves you from failed-card churn.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Invoice history:&lt;/strong&gt; visible by default.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Default redirect link and terms of service link:&lt;/strong&gt; set these to your dashboard and your terms page.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Then go to the branding settings and upload your logo and colors so the portal doesn't feel like a different product.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Gotcha #1:&lt;/strong&gt; Stripe keeps separate portal configurations for live mode and each sandbox. Changing one doesn't change the other. I've shipped with a perfect test configuration and a default live one more than once. When you go live, configure it again in live mode and add your live webhook endpoint.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 2: The portal session route
&lt;/h2&gt;

&lt;p&gt;A portal session is a short-lived URL for one customer. You create it on the server, after you've checked who the user is, then redirect them. Stripe's docs suggest a form POST, which works well with an App Router route handler:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/billing/portal/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next/server&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;auth&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/auth&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/db&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/login`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;303&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findUniqueOrThrow&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Never bought anything: send them to pricing instead&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/pricing`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;303&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;portal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;billingPortal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sessions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;return_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/dashboard`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;})&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;portal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;303&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And the button in your dashboard:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;form&lt;/span&gt; &lt;span class="na"&gt;method&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"POST"&lt;/span&gt; &lt;span class="na"&gt;action&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"/api/billing/portal"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
  &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;button&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"submit"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;Manage billing&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;button&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;form&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few things that matter here:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Always look up the customer ID from your own database&lt;/strong&gt; using the signed-in user's ID. Never accept a &lt;code&gt;customer&lt;/code&gt; ID from the request body. Otherwise anyone could open someone else's billing page.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Create a new session on every click.&lt;/strong&gt; Portal URLs are short-lived, so don't store them or email them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;return_url&lt;/code&gt;&lt;/strong&gt; is where the "Return to your app" link goes. Stripe requires it unless you've set a default redirect link in the Dashboard.&lt;/li&gt;
&lt;li&gt;I use a &lt;strong&gt;303&lt;/strong&gt; redirect so the browser follows the POST with a GET.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 3: Deep links for "Cancel" and "Change plan" buttons
&lt;/h2&gt;

&lt;p&gt;Sometimes you want a specific button, like "Upgrade to yearly" or "Cancel plan," instead of the whole portal. Stripe calls these &lt;strong&gt;portal flows&lt;/strong&gt;. You pass &lt;code&gt;flow_data&lt;/code&gt; when you create the session, and the customer lands right on that one action with the rest of the portal navigation hidden.&lt;/p&gt;

&lt;p&gt;The flow types right now are &lt;code&gt;payment_method_update&lt;/code&gt;, &lt;code&gt;subscription_cancel&lt;/code&gt;, &lt;code&gt;subscription_update&lt;/code&gt;, &lt;code&gt;subscription_update_confirm&lt;/code&gt;, and &lt;code&gt;customer_update&lt;/code&gt;. Here's a cancel flow that sends the user back to a page of yours when they're done:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;portal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;billingPortal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sessions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
  &lt;span class="na"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;return_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/dashboard`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;flow_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;subscription_cancel&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;subscription_cancel&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;subscription&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeSubscriptionId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;after_completion&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;redirect&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;return_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/dashboard?canceled=1`&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;})&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The top-level &lt;code&gt;return_url&lt;/code&gt; is the "never mind" link. The &lt;code&gt;after_completion&lt;/code&gt; redirect is where they go after they actually finish. That's a nice place for a short "Sorry to see you go, here's how to export your data" message.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;payment_method_update&lt;/code&gt; is the one I'd add first. If a renewal fails, link the "Update your card" banner in your app straight to that flow. It's one click for the user and it saves revenue you'd otherwise lose.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 4: The webhooks that keep your app honest
&lt;/h2&gt;

&lt;p&gt;This is the part people skip. The portal changes the subscription in Stripe and &lt;strong&gt;your app finds out from webhooks&lt;/strong&gt;. Here's the list I care about, from Stripe's portal integration guide:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;customer.subscription.updated&lt;/code&gt;&lt;/strong&gt;: upgrades, downgrades, quantity changes, scheduled cancellations, and reactivations. Check &lt;code&gt;subscription.items.data[0].price&lt;/code&gt; to see which price they're on now.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;customer.subscription.deleted&lt;/code&gt;&lt;/strong&gt;: the subscription actually ended. Revoke Pro.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;customer.updated&lt;/code&gt;&lt;/strong&gt;: billing info changed, including the default payment method.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;payment_method.attached&lt;/code&gt; / &lt;code&gt;payment_method.detached&lt;/code&gt;&lt;/strong&gt;: cards added or removed.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Here's the plan-sync part of a webhook handler. It assumes you already verify the signature on the raw body and skip duplicate event IDs (I go through that in my &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;Stripe subscriptions guide&lt;/a&gt;):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.updated&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
&lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.deleted&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;object&lt;/span&gt; &lt;span class="kd"&gt;as &lt;/span&gt;&lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Subscription&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;priceId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]?.&lt;/span&gt;&lt;span class="nx"&gt;price&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;isActive&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;active&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;trialing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customer&lt;/span&gt; &lt;span class="kd"&gt;as &lt;/span&gt;&lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;plan&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;isActive&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;priceId&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;STRIPE_PRICE_PRO&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;pro&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;free&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="c1"&gt;// "Your plan ends on..." banner&lt;/span&gt;
      &lt;span class="na"&gt;cancelsAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;cancel_at&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;cancel_at&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="k"&gt;break&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Gotcha #2: canceling isn't the same as canceled.&lt;/strong&gt; If you set cancellations to happen at period end, clicking "Cancel" in the portal does &lt;strong&gt;not&lt;/strong&gt; send &lt;code&gt;customer.subscription.deleted&lt;/code&gt; right away. You get &lt;code&gt;customer.subscription.updated&lt;/code&gt; now, and &lt;code&gt;deleted&lt;/code&gt; when the period actually ends. If you revoke access on the first event, you've taken away something the customer already paid for. Stripe's docs say to check &lt;code&gt;cancel_at_period_end&lt;/code&gt; on classic billing mode subscriptions, and &lt;code&gt;cancel_at&lt;/code&gt; on the newer flexible billing mode. That's why I store a date and show a banner instead of flipping the plan early.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Gotcha #3: people change their minds.&lt;/strong&gt; If they reactivate before the period ends, you get another &lt;code&gt;customer.subscription.updated&lt;/code&gt;, with &lt;code&gt;cancel_at&lt;/code&gt; back to &lt;code&gt;null&lt;/code&gt; (or &lt;code&gt;cancel_at_period_end&lt;/code&gt; back to &lt;code&gt;false&lt;/code&gt;). If you only handle the cancel direction, your "Your plan ends Nov 30" banner stays up forever.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Gotcha #4: trials end on plan switch.&lt;/strong&gt; Stripe notes that if a customer upgrades or downgrades in the portal during a trial, the trial ends right away when they switch to the new price. If you offer trials, mention that in your UI so it isn't a surprise.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Gotcha #5: billing email isn't login email.&lt;/strong&gt; Customers can change their email in the portal. Stripe's docs say to treat &lt;code&gt;customer.updated&lt;/code&gt; as billing information only and not to use the billing email as a login credential. Key everything on your own user ID and the Stripe customer ID.&lt;/p&gt;

&lt;h2&gt;
  
  
  Step 5: Test it before real customers do
&lt;/h2&gt;

&lt;p&gt;My pre-launch run through, all in a sandbox first:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;In the Stripe Dashboard, open a test customer, click &lt;strong&gt;Actions → Open customer portal&lt;/strong&gt;, and click around. Stripe also has a read-only &lt;strong&gt;Preview&lt;/strong&gt; button in portal settings.&lt;/li&gt;
&lt;li&gt;Run &lt;code&gt;stripe listen --forward-to localhost:3000/api/stripe/webhook&lt;/code&gt; and watch the events while you test.&lt;/li&gt;
&lt;li&gt;Subscribe with a test card, open the portal from your app, and &lt;strong&gt;cancel&lt;/strong&gt;. Confirm you still have Pro and the "ends on" banner shows up.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reactivate&lt;/strong&gt; in the portal. Confirm the banner goes away.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Switch plans&lt;/strong&gt; (if enabled). Confirm the price ID in your database changed.&lt;/li&gt;
&lt;li&gt;Use Stripe's test clocks or cancel immediately from the Dashboard to trigger &lt;code&gt;customer.subscription.deleted&lt;/code&gt;. Confirm you're back on Free.&lt;/li&gt;
&lt;li&gt;Do all of it again in &lt;strong&gt;live mode&lt;/strong&gt; with a real card and refund yourself. Live config and live webhook secrets are separate. That's the one people forget.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;You can build everything above in an afternoon or two, and if you want to own every line, this post should get you there. I built &lt;a href="https://shipember.com/" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt; because I was tired of rebuilding this same loop for every project.&lt;/p&gt;

&lt;p&gt;ShipEmber is a Next.js App Router starter that already has it working: Auth.js sign-in (Google, GitHub, magic links), Stripe Checkout, a customer portal route, signed and idempotent webhooks that keep Free/Pro in sync, Prisma with Postgres, and a dashboard gated on the server. You rename it, add your Stripe keys, and spend the weekend on the thing your customers actually pay for.&lt;/p&gt;

&lt;p&gt;To be honest about where it doesn't fit: if you need multi-tenant teams, organizations, and per-seat billing from day one, a bigger kit will be a better fit. ShipEmber is deliberately small, built for one product with a Free plan and a Pro plan.&lt;/p&gt;

&lt;p&gt;It's a one-time payment: &lt;strong&gt;$49 for launch week&lt;/strong&gt;, which ends Wednesday, Nov 4. It goes to $79 on Thursday, Nov 5. You can use it in unlimited personal and client projects, and you get 14 days to ask for a refund if it doesn't work as described.&lt;/p&gt;

&lt;p&gt;Prefer watching over reading? There's a short walkthrough:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the ShipEmber walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;See pricing&lt;/a&gt; or &lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/nextjs-stripe-authjs-setup-checklist.html" rel="noopener noreferrer"&gt;Next.js + Stripe + Auth.js setup checklist&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;How to add Stripe subscriptions to a Next.js App Router app&lt;/a&gt; · &lt;a href="https://shipember.com/blog/free-vs-paid-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;Free vs paid Next.js boilerplates&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/stripe-customer-portal-nextjs.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>stripe</category>
      <category>webdev</category>
      <category>saas</category>
    </item>
    <item>
      <title>ShipFast Alternative for Next.js App Router (2026): Honest Comparison</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Mon, 02 Nov 2026 21:00:24 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/shipfast-alternative-for-nextjs-app-router-2026-honest-comparison-3p45</link>
      <guid>https://dev.to/jakemcdonald/shipfast-alternative-for-nextjs-app-router-2026-honest-comparison-3p45</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 2, 2026 · About a 9-minute read · Prices checked on vendor sites today&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. I sell &lt;a href="https://shipember.com/index.html" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt;, so take this with that in mind — and check every competitor claim against their own site. A lot of people searching "ShipFast alternative" want the same outcome ShipFast is famous for (a Next.js kit with auth, payments, and marketing pieces) without paying $199–$249, or they want a smaller App Router + Postgres path. This page is that comparison.&lt;/p&gt;

&lt;p&gt;ShipFast prices and features below were verified on &lt;a href="https://shipfa.st" rel="noopener noreferrer"&gt;shipfa.st&lt;/a&gt; on November 2, 2026. ShipEmber prices match our live &lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;pricing&lt;/a&gt; page the same day.&lt;/p&gt;

&lt;h2&gt;
  
  
  ShipFast vs ShipEmber at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;ShipFast&lt;/th&gt;
&lt;th&gt;ShipEmber&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Price (one-time)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Starter $199 / All-in $249 (bundle with CodeFast $299)&lt;/td&gt;
&lt;td&gt;$49 launch week, then $79&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Stack&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Next.js; JS or TS; App or Pages Router&lt;/td&gt;
&lt;td&gt;Next.js App Router + TypeScript&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Auth&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Google OAuth and magic links&lt;/td&gt;
&lt;td&gt;Auth.js v5 — Google, GitHub, magic links&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Payments&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Stripe or Lemon Squeezy&lt;/td&gt;
&lt;td&gt;Stripe Checkout, portal, signed idempotent webhooks&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Database&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;MongoDB or Supabase&lt;/td&gt;
&lt;td&gt;Prisma + Postgres&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Extras&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Emails, SEO/blog helpers, UI components; All-in adds Discord + partner discounts&lt;/td&gt;
&lt;td&gt;Gated dashboard, marketing pages, one-file rebrand, tests/CI&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Best for&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Indie SaaS + community / marketing extras&lt;/td&gt;
&lt;td&gt;Minimal solo MVP on App Router + Stripe + Postgres&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  What ShipFast is (from their site)
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://shipfa.st" rel="noopener noreferrer"&gt;ShipFast&lt;/a&gt; is Marc Lou's Next.js boilerplate for shipping a SaaS, AI tool, or web app. On the pricing section of shipfa.st today:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Starter — $199&lt;/strong&gt; (shown with a $100-off promo framing on the page)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;All-in — $249&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;ShipFast + CodeFast&lt;/strong&gt; path mentioned at &lt;strong&gt;$299&lt;/strong&gt; (PayPal FAQ also lists $199 / $249 / $299)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The FAQ says you get the Next.js starter with payment system, database, login, blog, and UI components, in JavaScript and TypeScript, and in both &lt;code&gt;/app&lt;/code&gt; and &lt;code&gt;/pages&lt;/code&gt; routers. Docs cover setup and shipping. The higher plan adds Discord access (they cite 5,000+ makers), Leaderboards, and partner discounts (they list $1,210 worth). Stack flexibility called out on the site includes Stripe or Lemon Squeezy, and MongoDB or Supabase. Refunds: once you have repo access, they say it can't be refunded.&lt;/p&gt;

&lt;p&gt;Their FAQ also says the last update was &lt;strong&gt;9 months ago&lt;/strong&gt; when I checked today. Buy for the code and docs you get now — not for a rapid public changelog.&lt;/p&gt;

&lt;h2&gt;
  
  
  What ShipEmber is
&lt;/h2&gt;

&lt;p&gt;ShipEmber is the kit I built for myself: Next.js App Router + TypeScript, Auth.js v5, Stripe subscriptions (Checkout, customer portal, signature-verified idempotent webhooks), Prisma + Postgres, a Free/Pro gated dashboard, marketing pages, one-file rebrand, tests, and CI. One-time payment. Instant download after checkout. Lifetime updates to v1. 14-day refund if it doesn't work as described.&lt;/p&gt;

&lt;p&gt;Live price today: &lt;strong&gt;$49 launch week, then $79&lt;/strong&gt; — see &lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;pricing&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;It does &lt;em&gt;not&lt;/em&gt; ship a big Discord, Lemon Squeezy, MongoDB, Pages Router variants, or a large component marketplace. Intentionally small.&lt;/p&gt;

&lt;h2&gt;
  
  
  When ShipFast is the better pick
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;You want the larger indie ecosystem — Discord, leaderboards, partner discounts on the All-in tier.&lt;/li&gt;
&lt;li&gt;You need &lt;strong&gt;Lemon Squeezy&lt;/strong&gt; or prefer &lt;strong&gt;MongoDB&lt;/strong&gt; over Prisma/Postgres.&lt;/li&gt;
&lt;li&gt;You still use the &lt;strong&gt;Pages Router&lt;/strong&gt;, or you want JS and TS variants in one purchase.&lt;/li&gt;
&lt;li&gt;You value ShipFast's landing/SEO/blog helpers and don't mind paying $199–$249 for that surface area.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If those match what you're building, buy ShipFast from &lt;a href="https://shipfa.st" rel="noopener noreferrer"&gt;shipfa.st&lt;/a&gt;. I mean that.&lt;/p&gt;

&lt;h2&gt;
  
  
  When ShipEmber is the better pick
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Budget under ~$100 and you still need auth + Stripe subscriptions + a gated dashboard.&lt;/li&gt;
&lt;li&gt;You're standardized on &lt;strong&gt;App Router + TypeScript + Prisma + Postgres + Stripe&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;You want a small codebase you can read in an afternoon, not a wide template with every indie extra.&lt;/li&gt;
&lt;li&gt;You want a &lt;strong&gt;14-day refund&lt;/strong&gt; and an instant zip download (no waiting on a GitHub invite).&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;Here's the honest pitch — the same points I'd tell a friend on a call.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Price without pretending we're the same product
&lt;/h3&gt;

&lt;p&gt;ShipFast starts at $199. ShipEmber is $49 during launch week, then $79. We're not "ShipFast but cheaper with every feature." We're the core loop: login, Stripe, Postgres, gated Pro page. If you need their community and multi-payment/database options, pay for ShipFast.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. App Router + Stripe webhooks done carefully
&lt;/h3&gt;

&lt;p&gt;Checkout, raw-body signature verification, idempotent event handling, plan state in your database, and server-side gating are wired together. I also wrote a longer walkthrough: &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;How to add Stripe subscriptions to a Next.js App Router app&lt;/a&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Ships the same day
&lt;/h3&gt;

&lt;p&gt;Pay once. Download starts on the confirmation page. Drop in keys, migrate, deploy to Vercel. The boring path is paved so you can spend the evening on your product.&lt;/p&gt;

&lt;h2&gt;
  
  
  If this sounds like your stack
&lt;/h2&gt;

&lt;p&gt;Get the zip, add your keys, and build the part that matters.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;Pricing details&lt;/a&gt; · &lt;a href="https://shipember.com/features.html" rel="noopener noreferrer"&gt;What's inside&lt;/a&gt; · &lt;a href="https://shipember.com/blog/best-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;Full boilerplate comparison&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/shipped-alternative.html" rel="noopener noreferrer"&gt;Shipped.club alternative&lt;/a&gt; · &lt;a href="https://shipember.com/blog/free-vs-paid-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;Free vs paid&lt;/a&gt; · &lt;a href="https://shipember.com/blog/makerkit-alternative.html" rel="noopener noreferrer"&gt;Makerkit alternative&lt;/a&gt; · &lt;a href="https://shipember.com/blog/supastarter-alternative.html" rel="noopener noreferrer"&gt;supastarter alternative&lt;/a&gt; · &lt;a href="https://shipember.com/blog/why-i-built-shipember.html" rel="noopener noreferrer"&gt;Why I built ShipEmber&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Price note: ShipFast figures verified on shipfa.st on November 2, 2026. Vendor pages change — trust the vendor site if a number looks off later.&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>saas</category>
      <category>webdev</category>
      <category>javascript</category>
    </item>
    <item>
      <title>Free vs Paid Next.js SaaS Boilerplates (2026): What You Actually Get</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Mon, 02 Nov 2026 21:00:14 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/free-vs-paid-nextjs-saas-boilerplates-2026-what-you-actually-get-5dm7</link>
      <guid>https://dev.to/jakemcdonald/free-vs-paid-nextjs-saas-boilerplates-2026-what-you-actually-get-5dm7</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber · November 2, 2026 · About an 11-minute read · Free kits checked against their GitHub repos today&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. I sell a paid Next.js starter (&lt;a href="https://shipember.com/index.html" rel="noopener noreferrer"&gt;ShipEmber&lt;/a&gt;), so this page has a conflict of interest. I'm still going to say this clearly: &lt;strong&gt;free open-source starters are often the right first move&lt;/strong&gt;. The question is what "free" actually includes — and what you still have to wire yourself before the first paid customer.&lt;/p&gt;

&lt;p&gt;I verified the free options below against their public repos or sites on November 2, 2026. Paid prices match each vendor's live page the same day (or our own &lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;pricing&lt;/a&gt; for ShipEmber).&lt;/p&gt;

&lt;h2&gt;
  
  
  Free vs paid at a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Kit&lt;/th&gt;
&lt;th&gt;Price&lt;/th&gt;
&lt;th&gt;Auth&lt;/th&gt;
&lt;th&gt;Stripe subscriptions&lt;/th&gt;
&lt;th&gt;Best for&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;nextjs/saas-starter&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Free (MIT)&lt;/td&gt;
&lt;td&gt;Email/password + JWT cookies&lt;/td&gt;
&lt;td&gt;Checkout + Customer Portal (basic)&lt;/td&gt;
&lt;td&gt;Learning the shape of a SaaS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;create-t3-app&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Free (MIT)&lt;/td&gt;
&lt;td&gt;Auth.js optional&lt;/td&gt;
&lt;td&gt;No — bring your own&lt;/td&gt;
&lt;td&gt;Typesafe scaffold, not a SaaS kit&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;ixartz/SaaS-Boilerplate&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Free (MIT)&lt;/td&gt;
&lt;td&gt;Clerk&lt;/td&gt;
&lt;td&gt;Not the focus of the public README&lt;/td&gt;
&lt;td&gt;Multi-tenant + i18n learning&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;ShipEmber&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;$49 launch week, then $79&lt;/td&gt;
&lt;td&gt;Auth.js v5 (Google, GitHub, magic links)&lt;/td&gt;
&lt;td&gt;Checkout, portal, signed idempotent webhooks&lt;/td&gt;
&lt;td&gt;Minimal solo Free→Pro MVP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;ShipFast / Makerkit / etc.&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;~$157–$1,499&lt;/td&gt;
&lt;td&gt;Varies&lt;/td&gt;
&lt;td&gt;Usually yes&lt;/td&gt;
&lt;td&gt;Broader indie or B2B surface&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  What "free" actually means
&lt;/h2&gt;

&lt;p&gt;Free usually means MIT code you can clone. It does &lt;em&gt;not&lt;/em&gt; mean:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;OAuth providers configured for production,&lt;/li&gt;
&lt;li&gt;webhook idempotency and plan gating you can trust under retries,&lt;/li&gt;
&lt;li&gt;marketing pages ready to rebrand,&lt;/li&gt;
&lt;li&gt;or someone answering Discord questions when Stripe returns a weird event.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;You still pay with time. Sometimes that trade is correct.&lt;/p&gt;

&lt;h2&gt;
  
  
  nextjs/saas-starter (Vercel / Next.js)
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Verified:&lt;/strong&gt; &lt;a href="https://github.com/nextjs/saas-starter" rel="noopener noreferrer"&gt;github.com/nextjs/saas-starter&lt;/a&gt; — MIT, ~16k stars when I checked today. Demo linked from the README: next-saas-start.vercel.app.&lt;/p&gt;

&lt;p&gt;From the README, you get:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Next.js + Postgres + Drizzle + Stripe + shadcn/ui&lt;/li&gt;
&lt;li&gt;Marketing landing page and a pricing page wired to Stripe Checkout&lt;/li&gt;
&lt;li&gt;Dashboard CRUD, basic Owner/Member RBAC&lt;/li&gt;
&lt;li&gt;Stripe Customer Portal for subscription management&lt;/li&gt;
&lt;li&gt;Email/password auth with JWTs in cookies&lt;/li&gt;
&lt;li&gt;Middleware to protect logged-in routes; activity logging&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; This is the best free reference I know for "what a clean Next.js + Stripe + Postgres app looks like." Gaps vs a commercial kit: no Google/GitHub OAuth out of the box, no polished one-file rebrand, and you will harden webhook/idempotency patterns yourself for production. Start here if you're learning. Graduate when the missing pieces cost more evenings than a cheap paid kit.&lt;/p&gt;

&lt;h2&gt;
  
  
  create-t3-app
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Verified:&lt;/strong&gt; &lt;a href="https://create.t3.gg/" rel="noopener noreferrer"&gt;create.t3.gg&lt;/a&gt; and the &lt;a href="https://github.com/t3-oss/create-t3-app" rel="noopener noreferrer"&gt;t3-oss/create-t3-app&lt;/a&gt; repo (MIT). Install with &lt;code&gt;npm create t3-app@latest&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Their own copy is clear: it is &lt;em&gt;not&lt;/em&gt; an all-inclusive SaaS template. It scaffolds the pieces you opt into — Next.js, TypeScript, Tailwind, Prisma (or others), tRPC, and Auth.js (NextAuth) — with strong opinions about type safety. No Stripe. No pricing page. No customer portal.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; Perfect when you want a typesafe app shell and you &lt;em&gt;intend&lt;/em&gt; to own billing. Terrible if you expected "clone and charge cards tomorrow." Pair it with Stripe docs (or a kit) when you need subscriptions.&lt;/p&gt;

&lt;h2&gt;
  
  
  ixartz/SaaS-Boilerplate
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Verified:&lt;/strong&gt; &lt;a href="https://github.com/ixartz/SaaS-Boilerplate" rel="noopener noreferrer"&gt;github.com/ixartz/SaaS-Boilerplate&lt;/a&gt; — MIT, demo at react-saas.com. README lists Next.js, Tailwind, shadcn/ui, Clerk auth, multi-tenancy with teams/roles, Drizzle, i18n, landing, dashboard, tests, and CI. Stripe is not the headline feature of the public README.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; Useful if you want to study multi-tenant patterns and you're fine with Clerk (their free tier has limits; paid Clerk is a separate bill). If your requirement is "Auth.js + Stripe subscriptions on Postgres with no third-party auth vendor," this is the wrong free kit.&lt;/p&gt;

&lt;h2&gt;
  
  
  When free is the better pick
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;You're learning App Router, Drizzle/Prisma, or Stripe for the first time.&lt;/li&gt;
&lt;li&gt;You have a weekend and a high tolerance for wiring env vars and webhook secrets yourself.&lt;/li&gt;
&lt;li&gt;Your product is not ready to charge anyone — scaffolding beats buying.&lt;/li&gt;
&lt;li&gt;You specifically want create-t3-app's typesafe stack and will add billing later.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Related reading on that tradeoff: topic #12 in our internal notes became this page. Also see &lt;a href="https://shipember.com/blog/best-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;Best Next.js SaaS boilerplates in 2026&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  When a paid kit is the better pick
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;You've already burned a week on auth + webhooks and just want the boring path paved.&lt;/li&gt;
&lt;li&gt;You need OAuth (Google/GitHub) + magic links + Stripe Checkout + portal + server-side Free/Pro gating together.&lt;/li&gt;
&lt;li&gt;You want a small, opinionated codebase with docs aimed at shipping, not at teaching every option.&lt;/li&gt;
&lt;li&gt;Your hourly rate makes $79–$249 cheaper than two more evenings of billing bugs.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Paid kits are not equal. ShipFast, Makerkit, and supastarter buy you more surface area (and more learning). ShipEmber buys you the core loop only. I wrote separate comparisons: &lt;a href="https://shipember.com/blog/shipfast-alternative.html" rel="noopener noreferrer"&gt;ShipFast&lt;/a&gt;, &lt;a href="https://shipember.com/blog/makerkit-alternative.html" rel="noopener noreferrer"&gt;Makerkit&lt;/a&gt;, &lt;a href="https://shipember.com/blog/supastarter-alternative.html" rel="noopener noreferrer"&gt;supastarter&lt;/a&gt;, &lt;a href="https://shipember.com/blog/shipped-alternative.html" rel="noopener noreferrer"&gt;Shipped.club&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber (if you buy anything)
&lt;/h2&gt;

&lt;p&gt;Here's the honest pitch — same points I'd tell a friend.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Paid for the gap free kits leave
&lt;/h3&gt;

&lt;p&gt;ShipEmber is Auth.js v5 + Stripe subscriptions (Checkout, customer portal, signature-verified idempotent webhooks) + Prisma/Postgres + a gated dashboard + marketing pages + one-file rebrand. That's the gap between "I cloned saas-starter" and "I can charge Pro tonight."&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Price stays near free-kit territory
&lt;/h3&gt;

&lt;p&gt;Live price: &lt;strong&gt;$49 launch week, then $79&lt;/strong&gt; — see &lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;pricing&lt;/a&gt;. One-time. Instant zip download. 14-day refund if it doesn't work as described. Lifetime updates to v1.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Intentionally small
&lt;/h3&gt;

&lt;p&gt;No orgs, no i18n, no five payment providers. If you need those, buy Makerkit or supastarter — or start from nextjs/saas-starter and grow into them.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you want the paid core loop
&lt;/h2&gt;

&lt;p&gt;Get the zip, add your keys, and build the product part.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;Pricing details&lt;/a&gt; · &lt;a href="https://shipember.com/features.html" rel="noopener noreferrer"&gt;What's inside&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-stripe-authjs-setup-checklist.html" rel="noopener noreferrer"&gt;Auth.js + Stripe checklist&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://shipember.com/blog/best-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;Full boilerplate comparison&lt;/a&gt; · &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;Stripe subscriptions deep dive&lt;/a&gt; · &lt;a href="https://shipember.com/blog/why-i-built-shipember.html" rel="noopener noreferrer"&gt;Why I built ShipEmber&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Verification note: nextjs/saas-starter and ixartz/SaaS-Boilerplate READMEs and licenses checked on GitHub on November 2, 2026. create-t3.gg checked the same day. Vendor pages and READMEs change.&lt;/p&gt;

&lt;p&gt;— Jake Mcdonald, Springfield, IL&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>saas</category>
      <category>webdev</category>
      <category>opensource</category>
    </item>
    <item>
      <title>Best Next.js SaaS boilerplates in 2026</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Fri, 30 Oct 2026 15:18:11 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/best-nextjs-saas-boilerplates-in-2026-35n8</link>
      <guid>https://dev.to/jakemcdonald/best-nextjs-saas-boilerplates-in-2026-35n8</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber Â· Updated October 30, 2026 Â· About a 10-minute read Â· Prices checked against vendor sites this week&lt;/p&gt;

&lt;p&gt;If you're about to build a SaaS on Next.js, you will eventually ask: do I wire auth and Stripe myself, use a free starter, or buy a boilerplate? This comparison covers six options that keep coming up in 2026 â€” including ShipEmber, which I sell. Prices below were verified from each product's own site (or GitHub for free kits) around October 30, 2026. If a figure couldn't be confirmed live, I say so.&lt;/p&gt;

&lt;h2&gt;
  
  
  What actually matters in a Next.js SaaS starter
&lt;/h2&gt;

&lt;p&gt;Feature checklists get long fast. For a first paid product, these five things decide whether you ship this month or next quarter:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Auth that works on the server.&lt;/strong&gt; Sessions you can trust in Route Handlers and Server Components.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Stripe subscriptions done right.&lt;/strong&gt; Checkout, signed webhooks with a raw body, idempotency, and plan state in your own database.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A gated dashboard.&lt;/strong&gt; Free vs Pro checked where the data lives, not only behind a hidden button.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A stack you already know.&lt;/strong&gt; Next.js App Router, TypeScript, and a familiar ORM beat a clever monorepo you have to relearn.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Price vs time saved.&lt;/strong&gt; A $350 kit that saves two weeks is cheap. A $350 kit that forces you to unlearn patterns is not.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  At a glance
&lt;/h2&gt;

&lt;p&gt;Prices are one-time unless noted. "See site" means I couldn't lock a single current number from the vendor page at write time.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Kit&lt;/th&gt;
&lt;th&gt;Price (verified)&lt;/th&gt;
&lt;th&gt;Auth + Stripe&lt;/th&gt;
&lt;th&gt;Best for&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;ShipEmber&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;$49 launch week, then $79&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Minimal, fast solo MVP&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;ShipFast&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Starter $199 / All-in $249&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Indie SaaS + marketing extras&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Makerkit&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Pro $349 / Teams $649&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Multi-tenant B2B&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;supastarter&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Solo $349 / Startup $799 / Agency $1,499&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;Full B2B / agency work&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;nextjs/saas-starter&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Free (MIT)&lt;/td&gt;
&lt;td&gt;Yes (basic)&lt;/td&gt;
&lt;td&gt;Learning / reference&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;create-t3-app&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Free (MIT)&lt;/td&gt;
&lt;td&gt;Auth optional; no Stripe&lt;/td&gt;
&lt;td&gt;Typesafe scaffold only&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  ShipEmber â€” low-cost, minimal, fast to ship
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Price:&lt;/strong&gt; $49 during launch week, then $79. One-time download. Lifetime updates to v1. 14-day refund if it doesn't work as described.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What you get:&lt;/strong&gt; Next.js App Router + TypeScript, Auth.js v5 (Google, GitHub, magic links), Stripe Checkout + customer portal + signature-verified idempotent webhooks, Prisma + Postgres, a protected dashboard with Free/Pro gating, marketing pages, one-file rebrand, tests, and CI. Instant download after payment â€” no GitHub invite wait.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; ShipEmber is intentionally small. It does not ship organizations, i18n, an admin CRM, or five payment providers. If you want a weekend MVP with login, billing, and a gated Pro page, that is the point. If you need multi-tenant B2B on day one, look at Makerkit or supastarter instead.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt; &lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;See pricing details&lt;/a&gt; Â· &lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the walkthrough&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  ShipFast
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Price (verified on shipfa.st):&lt;/strong&gt; Starter &lt;strong&gt;$199&lt;/strong&gt;, All-in &lt;strong&gt;$249&lt;/strong&gt;, plus a ShipFast + CodeFast bundle listed at &lt;strong&gt;$299&lt;/strong&gt;. One-time.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What you get:&lt;/strong&gt; A popular indie Next.js boilerplate with auth (Google OAuth and magic links), Stripe or Lemon Squeezy, MongoDB or Supabase, emails, SEO/blog helpers, UI components, and JS or TS / App or Pages Router variants. The All-in tier adds Discord community access and partner discounts.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; ShipFast is still the name many makers compare against. It covers the "ship an indie SaaS" surface area well. Tradeoffs: it is several times ShipEmber's price, community extras sit behind the higher tier, and public update cadence has slowed (the FAQ on the site noted the last update months ago when we checked). Buy it for the code and docs you get today, not for a heavy roadmap.&lt;/p&gt;

&lt;h2&gt;
  
  
  Makerkit
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Price (verified on makerkit.dev/pricing):&lt;/strong&gt; Pro &lt;strong&gt;$349&lt;/strong&gt;, Teams &lt;strong&gt;$649&lt;/strong&gt;. One-time, lifetime updates. A free MIT "Lite" repo exists for evaluating the architecture.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What you get:&lt;/strong&gt; A serious multi-tenant kit â€” teams, roles, invitations, billing, super admin, marketing site, blog, docs, and AI agent rules / MCP tooling. Stack choices include Supabase, Drizzle, or Prisma variants on Next.js (and related frameworks depending on the kit).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; If you're building B2B SaaS with organizations and RBAC, Makerkit is one of the strongest options in this list. The complexity matches the price: you get more architecture, and you will spend more time learning it than a minimal kit. Freelancers building for clients should read their license terms carefully (client licensing rules differ from solo unlimited-project kits).&lt;/p&gt;

&lt;h2&gt;
  
  
  supastarter
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Price (verified on supastarter.dev):&lt;/strong&gt; Solo &lt;strong&gt;$349&lt;/strong&gt; (1 seat), Startup &lt;strong&gt;$799&lt;/strong&gt; (up to 5 seats), Agency &lt;strong&gt;$1,499&lt;/strong&gt; (up to 10 seats). One-time lifetime license. Framework options include Next.js (and others on their site).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What you get:&lt;/strong&gt; A wide production surface: auth (password, passkeys, OAuth, 2FA), organizations, billing across multiple providers, i18n, admin, email, storage, analytics hooks, E2E testing, docs, and an agent-oriented monorepo layout.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; This is the "full kitchen" kit. Agencies and teams that bill clients can justify the higher tiers. Solo founders validating a single B2C idea will pay for a lot of surface area they may never use. If you want everything production-shaped on day one and can absorb the learning curve, it belongs on your shortlist.&lt;/p&gt;

&lt;h2&gt;
  
  
  nextjs/saas-starter (Vercel / Next.js)
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Price:&lt;/strong&gt; Free, MIT. Repo: &lt;a href="https://github.com/nextjs/saas-starter" rel="noopener noreferrer"&gt;github.com/nextjs/saas-starter&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What you get:&lt;/strong&gt; Official-ish reference starter with Next.js, Postgres + Drizzle, Stripe Checkout and Customer Portal, email/password auth with JWT cookies, dashboard CRUD, basic team Owner/Member roles, and shadcn/ui.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; Excellent for learning how a clean Next.js + Stripe + Postgres app is structured. It is not a polished commercial product shell (marketing polish, OAuth providers, idempotent event tables, and rebrand tooling vary). Free is hard to beat for study; many people still graduate to a paid kit once they want production auth options and tighter billing patterns.&lt;/p&gt;

&lt;h2&gt;
  
  
  create-t3-app
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Price:&lt;/strong&gt; Free, MIT. CLI: &lt;code&gt;npm create t3-app@latest&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What you get:&lt;/strong&gt; An interactive scaffold for the T3 stack â€” Next.js, TypeScript, optional tRPC, Prisma or Drizzle, NextAuth, and Tailwind. It is intentionally not a SaaS product kit.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Honest take:&lt;/strong&gt; Perfect if you want a typesafe foundation and will wire Stripe, emails, and marketing yourself (see our &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;Stripe subscriptions guide&lt;/a&gt;). Wrong tool if your goal is "checkout and Pro gating by Friday" without writing that plumbing.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to choose
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Budget under ~$100, need auth + Stripe + dashboard now:&lt;/strong&gt; ShipEmber.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Indie SaaS with marketing extras and a big Discord:&lt;/strong&gt; ShipFast.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Multi-tenant B2B with teams and admin:&lt;/strong&gt; Makerkit (or supastarter if you want the widest feature set / multi-framework options).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Learning or forking a free reference:&lt;/strong&gt; nextjs/saas-starter.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Scaffold only; you'll build billing yourself:&lt;/strong&gt; create-t3-app.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There is no single "best" boilerplate â€” only the best fit for the product you're shipping this quarter. Expensive kits aren't automatically better for a solo MVP; free kits aren't free if you spend two weeks recreating Checkout webhooks.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you want the small paid path
&lt;/h2&gt;

&lt;p&gt;ShipEmber exists for one job: get you from empty folder to a deployable Next.js SaaS with login, Stripe subscriptions, and a gated dashboard without a $300â€“$1,500 invoice. Launch-week price is $49 (then $79). One payment, instant download, unlimited personal and client projects (don't resell the kit itself).&lt;/p&gt;

&lt;p&gt;&lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Prefer to see it first? &lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the walkthrough&lt;/a&gt; or &lt;a href="https://shipember.com/index.html#what-we-do" rel="noopener noreferrer"&gt;play the demo on the homepage&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;Price note: ShipFast prices verified on shipfa.st; Makerkit on makerkit.dev/pricing; supastarter on supastarter.dev; free kits via their GitHub licenses. Vendor pages change â€” if a number looks off later, trust the vendor site.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/best-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>saas</category>
      <category>webdev</category>
      <category>javascript</category>
    </item>
    <item>
      <title>How to add Stripe subscriptions to a Next.js App Router app (2026)</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Fri, 30 Oct 2026 15:12:18 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/how-to-add-stripe-subscriptions-to-a-nextjs-app-router-app-2026-4mb3</link>
      <guid>https://dev.to/jakemcdonald/how-to-add-stripe-subscriptions-to-a-nextjs-app-router-app-2026-4mb3</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber Â· Updated October 30, 2026 Â· About a 14-minute read&lt;/p&gt;

&lt;p&gt;Adding Stripe subscriptions to a Next.js App Router app doesn't take much code. It goes wrong in the small details: a webhook that parses the body before verifying it, a handler that runs the same event twice, or a "Pro" check that only exists in a client component. This guide covers a complete &lt;strong&gt;Next.js Stripe subscription&lt;/strong&gt; flow with stripe-node and Route Handlers, and keeps the parts that matter on the server.&lt;/p&gt;

&lt;p&gt;Here's the plan:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;A route that creates a Checkout Session in &lt;code&gt;subscription&lt;/code&gt; mode.&lt;/li&gt;
&lt;li&gt;A webhook route that reads the raw body, verifies the signature, and skips events it has already processed.&lt;/li&gt;
&lt;li&gt;Syncing subscription state into your own database.&lt;/li&gt;
&lt;li&gt;Gating a Pro page on the server, not in the browser.&lt;/li&gt;
&lt;li&gt;The customer portal for upgrades, cancellations, and card changes.&lt;/li&gt;
&lt;li&gt;Separate webhook secrets for local, test, and production (including Vercel).&lt;/li&gt;
&lt;li&gt;The pitfalls that cost people an afternoon.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The examples assume TypeScript, Prisma with Postgres, and some kind of server-side &lt;code&gt;auth()&lt;/code&gt; helper (Auth.js v5 has one). Swap in your own ORM or auth setup as needed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Setup
&lt;/h2&gt;

&lt;p&gt;Install the SDK and create one shared client. Use the server-only package so a careless import can't pull your secret key into a client bundle.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm &lt;span class="nb"&gt;install &lt;/span&gt;stripe server-only
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/stripe.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;server-only&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;STRIPE_SECRET_KEY&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Recent versions of stripe-node pin a default API version to each SDK release, so you usually don't need to pass &lt;code&gt;apiVersion&lt;/code&gt;. When you upgrade the package, read the changelog. Some response shapes change between API versions, and one of those changes is covered in the pitfalls below.&lt;/p&gt;

&lt;p&gt;In the Stripe Dashboard, create a Product with a recurring Price, for example $12/month. Copy the price ID (&lt;code&gt;price_...&lt;/code&gt;) into an env var. Don't hardcode amounts in your app. Stripe owns the price.&lt;/p&gt;

&lt;p&gt;You'll need a few columns on your user (or team) table:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;model User {
  id                   String    @id @default(cuid())
  email                String    @unique
  stripeCustomerId     String?   @unique
  stripeSubscriptionId String?   @unique
  stripePriceId        String?
  subscriptionStatus   String?   // active, trialing, past_due, canceled...
  currentPeriodEnd     DateTime?
}

model StripeEvent {
  id        String   @id      // the evt_... ID
  type      String
  createdAt DateTime @default(now())
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  1. The checkout session route
&lt;/h2&gt;

&lt;p&gt;The browser should never decide which price it pays. It only sends a request. The server looks up the user, finds or creates their Stripe customer, and returns a Checkout URL.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/checkout/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next/server&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;auth&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/auth&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/db&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Unauthorized&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;401&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findUniqueOrThrow&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;customerId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;customerId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;customer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
      &lt;span class="na"&gt;email&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;email&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="nx"&gt;customerId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;customerId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;checkout&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;checkout&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sessions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;subscription&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;customerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;client_reference_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;line_items&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[{&lt;/span&gt; &lt;span class="na"&gt;price&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;STRIPE_PRICE_PRO&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;quantity&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="p"&gt;}],&lt;/span&gt;
    &lt;span class="na"&gt;subscription_data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;metadata&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;success_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/dashboard?checkout=success`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;cancel_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/pricing`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;checkout&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few notes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Create the customer yourself and reuse it.&lt;/strong&gt; If you skip &lt;code&gt;customer&lt;/code&gt;, Checkout creates a new customer every time, and soon one person has four customer records.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Put your user ID on the subscription metadata.&lt;/strong&gt; Subscription events will carry it, so the webhook doesn't need to guess which user an event belongs to.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The success page is not proof of payment.&lt;/strong&gt; Anyone can visit &lt;code&gt;?checkout=success&lt;/code&gt;. Only the webhook updates the plan.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;On the client, a button POSTs to this route and then runs &lt;code&gt;window.location.href = url&lt;/code&gt;. A Server Action that calls &lt;code&gt;redirect(checkout.url!)&lt;/code&gt; also works.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Stripe webhooks in a Next.js App Router route handler
&lt;/h2&gt;

&lt;p&gt;This is the route people get wrong most often when wiring &lt;strong&gt;Stripe webhooks for Next.js App Router&lt;/strong&gt;. Stripe signs the &lt;em&gt;exact bytes&lt;/em&gt; it sends. If you parse the JSON and stringify it again, the signature check fails. In the App Router you don't need to disable a body parser. Just read the body with &lt;code&gt;request.text()&lt;/code&gt; (or &lt;code&gt;req.text()&lt;/code&gt;) and don't call &lt;code&gt;req.json()&lt;/code&gt; before &lt;code&gt;constructEvent&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/stripe/webhook/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;headers&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next/headers&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Prisma&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@prisma/client&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/db&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;syncSubscription&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/billing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;runtime&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;nodejs&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Request&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;text&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="c1"&gt;// raw body. Do not use req.json().&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;signature&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;()).&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;stripe-signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;signature&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Missing signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Event&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;event&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;webhooks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;constructEvent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="nx"&gt;body&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;signature&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;STRIPE_WEBHOOK_SECRET&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;
    &lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Invalid signature&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// Idempotency: record the event ID first. A duplicate hits the unique constraint.&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeEvent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;e&lt;/span&gt; &lt;span class="k"&gt;instanceof&lt;/span&gt; &lt;span class="nx"&gt;Prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;PrismaClientKnownRequestError&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;code&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;P2002&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Already processed&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;switch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;checkout.session.completed&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;object&lt;/span&gt; &lt;span class="kd"&gt;as &lt;/span&gt;&lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Checkout&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;mode&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;subscription&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscription&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;syncSubscription&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscription&lt;/span&gt; &lt;span class="kd"&gt;as &lt;/span&gt;&lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;break&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.created&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.updated&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;customer.subscription.deleted&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;object&lt;/span&gt; &lt;span class="kd"&gt;as &lt;/span&gt;&lt;span class="nx"&gt;Stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;Subscription&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;syncSubscription&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="k"&gt;break&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Let Stripe retry: un-record the event and return a 500.&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeEvent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;delete&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;event&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="k"&gt;catch&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{});&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Handler failed&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;500&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;ok&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;200&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Why this shape works:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Verify the signature before you trust anything.&lt;/strong&gt; &lt;code&gt;constructEvent&lt;/code&gt; checks the HMAC and the timestamp tolerance. Without it, anyone who finds your URL can send a fake &lt;code&gt;customer.subscription.updated&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Stripe delivers at least once.&lt;/strong&gt; Retries, timeouts, and replays from the Dashboard all mean the same event can arrive more than once. A table keyed by &lt;code&gt;event.id&lt;/code&gt; with a unique constraint is the simplest dedupe that holds up under concurrent deliveries.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Handle &lt;code&gt;checkout.session.completed&lt;/code&gt; plus &lt;code&gt;customer.subscription.updated&lt;/code&gt; / &lt;code&gt;deleted&lt;/code&gt;.&lt;/strong&gt; Checkout grants the first subscription; subscription events keep status in sync when the customer upgrades, cancels, or fails a renewal.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Return a 500 on real failures&lt;/strong&gt; and remove the dedupe row so the retry can run. If you return 200 after a failure, Stripe considers the event delivered and won't retry.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use &lt;code&gt;runtime = "nodejs"&lt;/code&gt;.&lt;/strong&gt; stripe-node can verify on edge runtimes with &lt;code&gt;constructEventAsync&lt;/code&gt;, but the Node runtime has fewer surprises.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  3. Syncing plan state into your own DB
&lt;/h2&gt;

&lt;p&gt;Don't build state from event payloads one field at a time. Events can arrive out of order. An &lt;code&gt;updated&lt;/code&gt; event can show up before &lt;code&gt;created&lt;/code&gt;. The reliable approach is to &lt;strong&gt;treat the event as a signal and fetch the current subscription from Stripe&lt;/strong&gt;, then write the whole thing:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/billing.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;server-only&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/db&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;syncSubscription&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;subscriptionId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscriptions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;retrieve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;subscriptionId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;item&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;data&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;customerId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customer&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;string&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customer&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;customerId&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="na"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;stripeSubscriptionId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;stripePriceId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;item&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;price&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;subscriptionStatus&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;sub&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="c1"&gt;// On recent API versions, period dates are on the subscription item.&lt;/span&gt;
      &lt;span class="na"&gt;currentPeriodEnd&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;item&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;current_period_end&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Matching on &lt;code&gt;stripeCustomerId&lt;/code&gt; works because you created the customer in step 1. The &lt;code&gt;userId&lt;/code&gt; in metadata is a backup if you ever need it.&lt;/p&gt;

&lt;p&gt;Then define in one place what "paid" means:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// lib/plan.ts&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;PRO_PRICES&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Set&lt;/span&gt;&lt;span class="p"&gt;([&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;STRIPE_PRICE_PRO&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;]);&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;isPro&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;u&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;subscriptionStatus&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nl"&gt;stripePriceId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;u&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscriptionStatus&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;active&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;u&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;subscriptionStatus&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;trialing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
    &lt;span class="o"&gt;!!&lt;/span&gt;&lt;span class="nx"&gt;u&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripePriceId&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nx"&gt;PRO_PRICES&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;u&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripePriceId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Whether &lt;code&gt;past_due&lt;/code&gt; still gets access is a business decision. Many apps allow a grace period while Stripe's Smart Retries try the card again. Whatever you choose, decide it here and nowhere else.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Gating a Pro page server-side
&lt;/h2&gt;

&lt;p&gt;Hiding a button in a client component is UI, not access control. The check has to run on the server, right next to the data or action it protects. In the App Router, that means Server Components, Server Actions, and Route Handlers.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight tsx"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/dashboard/reports/page.tsx&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;redirect&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next/navigation&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;auth&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/auth&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/db&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;isPro&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/plan&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;ReportsPage&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nf"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;/login&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findUniqueOrThrow&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nf"&gt;isPro&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="nf"&gt;redirect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;/pricing&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Reports&lt;/span&gt; &lt;span class="na"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;=&lt;/span&gt;&lt;span class="si"&gt;{&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="si"&gt;}&lt;/span&gt; &lt;span class="p"&gt;/&amp;gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Put the same check in every Server Action and API route that does paid work. A small &lt;code&gt;requirePro()&lt;/code&gt; helper that throws or redirects keeps this short.&lt;/p&gt;

&lt;p&gt;Why not middleware? Middleware is fine for cheap redirects, but it's a poor place to do the only access check. It runs separately from the code it protects, matchers are easy to get wrong, and a database call there adds latency to every request. Also, in March 2025 Next.js patched a vulnerability (CVE-2025-29927) that let a crafted header skip middleware entirely. Check access where the data is read.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. The customer portal
&lt;/h2&gt;

&lt;p&gt;Don't build your own screens for cancel, upgrade, and update card. Stripe's customer portal handles all of them. Turn on the features you want under Settings â†’ Billing â†’ Customer portal, then create a session on the server:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app/api/portal/route.ts&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;next/server&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;auth&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/auth&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/stripe&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;@/lib/db&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;POST&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Unauthorized&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;401&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findUniqueOrThrow&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;id&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;No customer&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;portal&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;stripe&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;billingPortal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;sessions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;customer&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stripeCustomerId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;return_url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;APP_URL&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;/dashboard/billing`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;NextResponse&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;url&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;portal&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Anything the user changes in the portal sends a &lt;code&gt;customer.subscription.updated&lt;/code&gt; or &lt;code&gt;.deleted&lt;/code&gt; event. Your existing webhook handles it, so there's no extra code to write. If you allow plan switching in the portal, add those prices to the portal configuration and to &lt;code&gt;PRO_PRICES&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. Separate webhook secrets: local, test, and production on Vercel
&lt;/h2&gt;

&lt;p&gt;Each Stripe webhook endpoint has its own signing secret (&lt;code&gt;whsec_...&lt;/code&gt;). Mixing them up is the most common reason &lt;code&gt;constructEvent&lt;/code&gt; fails in production after it worked on your laptop.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Local:&lt;/strong&gt; &lt;code&gt;stripe listen --forward-to localhost:3000/api/stripe/webhook&lt;/code&gt; prints a CLI secret. Put that in &lt;code&gt;.env.local&lt;/code&gt; only.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Test mode Dashboard endpoint:&lt;/strong&gt; Create an endpoint pointing at your staging URL (or a temporary tunnel). Use that secret in your Preview / test env vars.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Live mode production:&lt;/strong&gt; Create a separate Live endpoint for &lt;code&gt;https://yourdomain.com/api/stripe/webhook&lt;/code&gt;. Copy its secret into Vercel Production env as &lt;code&gt;STRIPE_WEBHOOK_SECRET&lt;/code&gt;. Do not reuse the CLI secret or the test-mode secret.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;On Vercel, set Production and Preview env vars separately. Redeploy after changing secrets. In the Stripe Dashboard, subscribe the endpoint to at least &lt;code&gt;checkout.session.completed&lt;/code&gt;, &lt;code&gt;customer.subscription.updated&lt;/code&gt;, and &lt;code&gt;customer.subscription.deleted&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  7. Common pitfalls
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Parsing the body before verifying it.&lt;/strong&gt; &lt;code&gt;req.json()&lt;/code&gt; then &lt;code&gt;JSON.stringify&lt;/code&gt; doesn't give you back the same bytes. Use &lt;code&gt;req.text()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Using the wrong webhook secret.&lt;/strong&gt; CLI, test, and live secrets are three different values. See section 6.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Granting access on the success URL.&lt;/strong&gt; Users can close the tab, refresh the page, or type the URL. Only the webhook should grant access.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Not handling duplicate events.&lt;/strong&gt; Two deliveries of the same event shouldn't send two welcome emails or grant credits twice. Store &lt;code&gt;event.id&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Trusting event order.&lt;/strong&gt; Fetch the subscription again instead of applying event payloads one after another.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reading &lt;code&gt;current_period_end&lt;/code&gt; from the subscription.&lt;/strong&gt; In recent API versions it moved to subscription items. If you upgraded stripe-node and the field is now &lt;code&gt;undefined&lt;/code&gt;, this is why.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Creating duplicate customers.&lt;/strong&gt; Always pass &lt;code&gt;customer&lt;/code&gt; to Checkout once you have one.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Middleware or redirects intercepting &lt;code&gt;/api/stripe/webhook&lt;/code&gt;.&lt;/strong&gt; Auth middleware that redirects the webhook to &lt;code&gt;/login&lt;/code&gt; breaks it. So does a trailing-slash redirect, because Stripe doesn't follow redirects.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Doing slow work inside the handler.&lt;/strong&gt; Stripe expects a quick 2xx. If you send emails or call other APIs, queue that work or keep it short.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Checking the plan only on the client.&lt;/strong&gt; See section 4.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Testing it locally
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;stripe login
stripe listen &lt;span class="nt"&gt;--forward-to&lt;/span&gt; localhost:3000/api/stripe/webhook
&lt;span class="c"&gt;# in another terminal&lt;/span&gt;
stripe trigger customer.subscription.updated
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For a full run-through, use test card &lt;code&gt;4242 4242 4242 4242&lt;/code&gt; in Checkout, check that the database row changes, open the portal, cancel, and check that access goes away when the subscription ends. Replay one event from the Dashboard to confirm the dedupe table catches it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Or skip the wiring with ShipEmber
&lt;/h2&gt;

&lt;p&gt;Full disclosure: I sell a starter kit that already does all of this. &lt;strong&gt;ShipEmber&lt;/strong&gt; is a Next.js App Router + TypeScript starter with Stripe Checkout, the customer portal, and signature-verified, idempotent webhooks (a &lt;code&gt;StripeEvent&lt;/code&gt; table records processed event IDs, as shown above). It also includes a protected dashboard with server-side plan gating (&lt;code&gt;auth()&lt;/code&gt; on the server, no middleware-only checks), Auth.js v5 (Google, GitHub, email magic links), Prisma + Postgres, Tailwind, marketing pages, a one-file rebrand config, tests, and GitHub CI.&lt;/p&gt;

&lt;p&gt;It's a one-time download: $49 for launch week, then $79. You get lifetime v1 updates, can use it in unlimited personal and client projects, and have 14 days to ask for a refund.&lt;/p&gt;

&lt;p&gt;Prefer watching over reading? There's a short walkthrough:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Watch the ShipEmber walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;If you'd rather build it yourself, everything above should get you there. If you'd rather start from working code, &lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;see pricing&lt;/a&gt; or &lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>stripe</category>
      <category>saas</category>
      <category>typescript</category>
    </item>
    <item>
      <title>Why I built ShipEmber (and why it's $49, not $299)</title>
      <dc:creator>Jake Mcdonald</dc:creator>
      <pubDate>Fri, 30 Oct 2026 15:12:03 +0000</pubDate>
      <link>https://dev.to/jakemcdonald/why-i-built-shipember-and-why-its-49-not-299-493e</link>
      <guid>https://dev.to/jakemcdonald/why-i-built-shipember-and-why-its-49-not-299-493e</guid>
      <description>&lt;p&gt;By Jake Mcdonald, founder of ShipEmber Â· October 30, 2026 Â· About an 8-minute read&lt;/p&gt;

&lt;p&gt;I'm Jake Mcdonald. I build software in Springfield, IL, and ShipEmber is the Next.js starter I wish I'd had the last few times I spun up a SaaS.&lt;/p&gt;

&lt;p&gt;This isn't a manifesto. It's the short version of why the kit exists, what's in it, who should buy it, who shouldn't, and why I priced launch week at $49 instead of joining the $199â€“$349 pack.&lt;/p&gt;

&lt;h2&gt;
  
  
  The weeks you don't get back
&lt;/h2&gt;

&lt;p&gt;Every serious side project starts the same way. You open a fresh Next.js app. Then you spend days on things that are not the product:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Auth that works in Server Components and Route Handlers, not only in a client provider.&lt;/li&gt;
&lt;li&gt;Stripe Checkout in &lt;code&gt;subscription&lt;/code&gt; mode, with a customer you reuse instead of creating four of them.&lt;/li&gt;
&lt;li&gt;A webhook that reads the &lt;em&gt;raw&lt;/em&gt; body, verifies the signature, and doesn't double-grant Pro when Stripe retries.&lt;/li&gt;
&lt;li&gt;Plan state in your own database, because the success URL is not proof of payment.&lt;/li&gt;
&lt;li&gt;A dashboard page that actually redirects Free users, on the server.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;None of that is hard once you've done it. The first time â€” or the third time across three abandoned repos â€” it eats a weekend, then another. I kept rewriting the same glue. Eventually I packaged the version I trust and made it downloadable.&lt;/p&gt;

&lt;h2&gt;
  
  
  What ShipEmber includes
&lt;/h2&gt;

&lt;p&gt;One zip. One-time payment. Instant download after checkout. Inside:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Next.js App Router + TypeScript&lt;/strong&gt; â€” the stack most of us already use.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Auth.js v5&lt;/strong&gt; â€” Google, GitHub, and email magic links, with a Prisma adapter.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Stripe billing&lt;/strong&gt; â€” Checkout, the customer portal, and signed, idempotent webhooks that sync status into Postgres.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Prisma + Postgres&lt;/strong&gt; â€” schema and seed so you're not inventing tables at 1 a.m.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A gated dashboard&lt;/strong&gt; â€” Free vs Pro checked where the data lives.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Marketing pages&lt;/strong&gt; â€” landing, pricing, legal stubs, sitemap-friendly structure.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;One-file rebrand&lt;/strong&gt; â€” name, copy, plans without hunting through forty components.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Tests and CI&lt;/strong&gt; â€” so a broken webhook fails in GitHub before it fails for a customer.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you want the long feature list, it's on the &lt;a href="https://shipember.com/features.html" rel="noopener noreferrer"&gt;features&lt;/a&gt; page. If you want to see it run, watch this:&lt;/p&gt;

&lt;p&gt;  &lt;iframe src="https://www.youtube.com/embed/telI3nHd9Tg" width="710" height="399"&gt;
  &lt;/iframe&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a href="https://www.youtube.com/watch?v=telI3nHd9Tg" rel="noopener noreferrer"&gt;Open the walkthrough on YouTube&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Who it's for
&lt;/h2&gt;

&lt;p&gt;ShipEmber is for indie builders and freelancers who want a paid MVP without spending two weeks on plumbing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;You know Next.js well enough to customize, not learn it from scratch.&lt;/li&gt;
&lt;li&gt;You need login, Stripe subscriptions, and a Pro-gated page working the same day you buy.&lt;/li&gt;
&lt;li&gt;You want code you can read â€” not a monorepo that takes a day to map.&lt;/li&gt;
&lt;li&gt;You're fine owning the product after download. No subscription to the kit itself.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Who it's not for
&lt;/h2&gt;

&lt;p&gt;I'd rather you don't buy if this isn't the fit:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Multi-tenant B2B on day one.&lt;/strong&gt; Organizations, invites, RBAC, seat billing â€” look at Makerkit or supastarter. ShipEmber is intentionally smaller.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You want five frameworks and every payment provider.&lt;/strong&gt; I ship one opinionated Next.js path with Stripe.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You only need a typesafe scaffold.&lt;/strong&gt; Use create-t3-app for free and wire billing yourself (I wrote a &lt;a href="https://shipember.com/blog/nextjs-stripe-subscription-starter.html" rel="noopener noreferrer"&gt;guide for that&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You expect me to build your product.&lt;/strong&gt; This is a starter kit, not a studio engagement.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why choose ShipEmber
&lt;/h2&gt;

&lt;p&gt;Here's the honest pitch â€” the same points I'd tell a friend on a call.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Low price on purpose
&lt;/h3&gt;

&lt;p&gt;Launch week is &lt;strong&gt;$49&lt;/strong&gt;, then &lt;strong&gt;$79&lt;/strong&gt;. One payment. Compare that to kits we checked recently: ShipFast from &lt;strong&gt;$199&lt;/strong&gt;, Makerkit Pro at &lt;strong&gt;$349&lt;/strong&gt;, supastarter Solo at &lt;strong&gt;$349&lt;/strong&gt; (higher tiers for teams). Those products include more surface area â€” communities, multi-tenancy, agency seats. If you need that, pay for it. If you need auth + Stripe + a dashboard, you shouldn't have to.&lt;/p&gt;

&lt;p&gt;I priced ShipEmber so the decision is easy. If it doesn't work as described, you have 14 days to email me for a refund.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Minimal, readable code
&lt;/h3&gt;

&lt;p&gt;Big kits earn their price by covering every SaaS edge case. They also take longer to learn. ShipEmber stays small: routes you recognize, a webhook you'd write yourself after reading my Stripe post, plan checks next to the page they protect. You should be able to open the zip and find the billing file in a minute.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Ships the same day
&lt;/h3&gt;

&lt;p&gt;Pay once. The confirmation page starts the download. Drop in your Stripe, database, and auth keys. Run migrations. Deploy to Vercel. The boring path is already paved so you can spend the evening on the feature that makes the product yours.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Free to Pro works out of the box
&lt;/h3&gt;

&lt;p&gt;Checkout, webhook sync, and server-side gating are wired together. A Free user hits the upgrade path. A Pro user sees the dashboard. You shouldn't ship a SaaS where "Pro" is a CSS class.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why not $299?
&lt;/h2&gt;

&lt;p&gt;Because the category drifted that way, and I think a lot of first-time founders only need the core loop. Charging $299 for what is essentially "auth, Stripe, dashboard, deploy" would feel like padding. I'd rather sell the kit people actually finish with than the kit that impresses a comparison table.&lt;/p&gt;

&lt;p&gt;That also means I'm not pretending ShipEmber replaces a full B2B platform. Read the "not for" list. Then decide.&lt;/p&gt;

&lt;h2&gt;
  
  
  If this sounds like your stack
&lt;/h2&gt;

&lt;p&gt;Get the zip, add your keys, and build the part that matters.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://buy.stripe.com/00weVc3I4fgmdBJcie3ks00" rel="noopener noreferrer"&gt;Get ShipEmber, $49&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://shipember.com/pricing.html" rel="noopener noreferrer"&gt;Pricing details&lt;/a&gt; Â· &lt;a href="https://shipember.com/features.html" rel="noopener noreferrer"&gt;What's inside&lt;/a&gt; Â· &lt;a href="https://shipember.com/blog/best-nextjs-saas-boilerplates.html" rel="noopener noreferrer"&gt;How it compares&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;â€” Jake Mcdonald, Springfield, IL&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published on &lt;a href="https://shipember.com/blog/why-i-built-shipember.html" rel="noopener noreferrer"&gt;shipember.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>nextjs</category>
      <category>saas</category>
      <category>startup</category>
      <category>webdev</category>
    </item>
  </channel>
</rss>
