On this page 7 sections
A Stripe subscriptions Supabase setup in late 2026 has three parts: Stripe owns billing state, a sync copies it into Postgres, and your app gates features from that copy. Use the Stripe Sync Engine or Data Pipeline for the copy and Metronome for new usage pricing. New Stripe accounts retry failed renewals up to 8 times over 2 weeks.
Most Stripe and Supabase tutorials still date from before three changes. Supabase made the Sync Engine a one-click dashboard integration in December 2025. Stripe took over the project in April 2026 and launched a paid sync straight into Supabase in October. And Stripe now points new usage-based integrations at Metronome, which is now part of Stripe. If you’re wiring payments into a new SaaS this quarter, the defaults have moved.
Let Stripe own state, keep a copy
Your app should never be the source of truth for whether someone has paid. Stripe is. Your job is to keep a copy close enough to Postgres that every page load can check it without calling Stripe’s API.
The hard part is keeping that copy correct. Stripe’s webhook docs say events can arrive out of order and the same event can arrive twice, so a handler that applies each event as a patch can drift: a payment fails in Stripe while your table still says “active”. The fix the widely shared t3dotgg Stripe recommendations argue for is to treat each event as a signal and refetch the customer’s full subscription state from Stripe before writing it.
Two more rules from Stripe’s docs belong in every handler:
- Return a
2xxbefore doing any slow work, and verify theStripe-Signatureheader against the raw request body. - Log event IDs and skip ones you’ve already processed. Live-mode deliveries are retried for up to 3 days if your endpoint fails.
Stripe subscriptions Supabase sync: three options
You don’t have to write that sync yourself anymore. There are three ways to get Stripe data into Supabase, plus one to avoid on the hot path.
Stripe Sync Engine. Install it from Integrations in the Supabase dashboard. Supabase’s launch post says it uses “webhooks for real-time updates and scheduled backfills for historical data”, with both configured for you. The code moved to stripe/sync-engine on April 14, 2026, stays Apache 2.0, and the dashboard integration “continues to work as before”. If you self-host it from the repo, note the README’s warning that the service “lacks tight access controls and should only be deployed internally”.
Stripe Data Pipeline. Since October 15, 2026, you can sync to a Supabase project from the Stripe Dashboard. Tables land in a schema with a stripe_sdp prefix and a dedicated role, with “no webhooks to maintain”. It isn’t free: Stripe’s Data Pipeline pricing lists the Postgres sync as public preview at $0.0025 per row synced, with 5,000 rows free per month.
Your own webhook handler. An Edge Function that writes a small subscriptions table: customer ID, status, price, current period end. Choose this when you only need a few fields, or when you want the table keyed exactly the way your row level security policies expect.
The Stripe foreign data wrapper. It translates SQL into live Stripe API calls. Supabase’s own post notes that frequent queries “hit Stripe’s rate limits”. Keep it for occasional admin queries.
| Option | Cost | Who runs it | Best for |
|---|---|---|---|
| Sync Engine | Free, open source | Supabase integration | Most new SaaS apps |
| Data Pipeline | $0.0025 per row after 5,000 free | Stripe | Teams that want no sync code at all |
| Own handler | Your time | You | A few fields, custom RLS keys |
| Foreign data wrapper | Free | Stripe API on every query | Admin and reporting only |
Whichever you pick, keep a mapping from your Supabase user ID to the Stripe customer ID, and create the customer before the first checkout. Every later event is resolved through that mapping.
Match each pricing model to a Stripe primitive
Most billing bugs start with the wrong primitive for the pricing model. Stripe’s recurring pricing models page lists four: flat rate, per-seat, tiered and usage-based. Here’s how they map in late 2026.
Flat-rate and per-seat plans: Stripe Subscriptions. For per-seat, “each pricing unit represents one user”, so the subscription’s quantity is the seat count. Update the quantity when a teammate is added and let Stripe handle proration.
New usage-based pricing: Metronome. Stripe’s usage-based billing docs now call Metronome “Stripe’s primary usage-based billing platform and the recommended starting point for all new integrations”, including prepaid credits, credit burndown and enterprise commits. Metronome lists its pricing separately from Stripe Billing.
Existing Billing Meters: stay put. The same page says the Meters API “remains fully supported for existing integrations” and offers “fuller compatibility with Connect, Checkout, Adaptive Pricing, and Workflows”. Stripe Billing pricing includes up to 100M meter events a month in its 0.7% pay-as-you-go rate. If your code still calls usage records, it’s on borrowed time: API version 2025-03-31.basil removed legacy usage-based billing, and metered prices without a meter now return an error.
Hybrid (seats plus usage): both, on one customer. Stripe’s Metronome integration guide describes running Stripe Subscriptions for seats while Metronome bills usage, with both creating invoices on the same Stripe Customer. Your customer gets two invoices, so say so on your pricing page. Metronome invoices don’t go through Checkout; that needs custom work.
Enterprise quotes: Metronome contracts or Stripe quotes. Metronome handles minimum-spend commits and true-ups. Stripe Billing itself includes quotes and multiphase subscription schedules, which cover a negotiated annual price without one-off code.
Gate features with entitlements, not plan names
Checking plan === 'pro' across your codebase means every pricing change becomes a code change. Stripe’s Entitlements let you attach features, each with a lookup_key such as ai-assistant, to products. When a customer subscribes, upgrades, downgrades or cancels, Stripe sends entitlements.active_entitlement_summary.updated with their full list.
Two details matter in a Supabase app. The summary in that event holds at most 10 entitlements, so fetch the full list when there are more. And Stripe itself recommends you “persist these entitlements internally for faster resolution”. Write them to a customer_entitlements table, and have your row level security policies check that table. If those policies are new to you, our guide to Supabase row level security mistakes covers the ones that leak data.
Dunning, tax and webhook edge cases
These are the parts that work in testing and fail on the first renewal.
Failed renewals. For new accounts, Smart Retries default to up to 8 retries within 2 weeks. After the last one, the subscription moves to whatever you chose in settings: canceled, unpaid, left past_due, or paused. Stripe’s subscription webhook guide says to notify the customer at past_due and revoke access at canceled or unpaid. Also note that Stripe doesn’t automatically retry India-issued cards, so if you sell in India, send your own reminder emails.
First payments. A new subscription stays incomplete for 23 hours while the customer completes payment or authentication. Don’t grant access until invoice.paid arrives and the subscription is active.
Renewal invoices. If your endpoint doesn’t respond successfully to invoice.created, Stripe delays finalizing invoices with automatic collection for up to 72 hours. A broken webhook endpoint delays revenue as well as leaving a stale table.
Tax. Stripe Tax pricing is 0.5% per transaction through Billing or Checkout, or 50 cents per transaction through the API, in places where you’re registered. If Stripe Tax can’t find the customer’s location, the invoice fails to finalize and can’t be paid, so collect a billing address at checkout and handle invoice.finalization_failed.
What to keep in-house. Keep seat counts, usage events and the user-to-customer mapping in your own database. Leave prices, invoices, proration and retries to Stripe. Rebuilding proration yourself is how teams end up refunding customers by hand.
How to decide
- Flat or per-seat plans, new app: Stripe Subscriptions plus the Sync Engine. Add Entitlements from day one.
- You don’t want to own any sync code: Stripe Data Pipeline, once you’ve priced it against your row volume.
- Usage-based or credit pricing, new integration: Metronome. Keep Stripe Subscriptions for any seat component.
- Already on Billing Meters and happy: stay. Plan a move only if you need commits, credits or dimensional pricing.
- Still on usage records: migrate to meters before you upgrade past 2025-03-31.basil.
- Selling in India: plan your own reminders for failed renewals, since Stripe won’t retry India-issued cards.
How Prompt Genie runs monthly and annual Stripe plans
Prompt Genie is a prompt library for teams, with a free plan and paid monthly and annual plans. We built its web app and its Stripe subscriptions: checkout with Stripe Elements for both billing periods, with upgrades, downgrades, cancellations and proration handled through webhooks.
The risk every subscription app faces is a plan change that never reaches the app, leaving a customer paying for features they can’t use, or using features they no longer pay for. The safeguard we built was to drive access from the live subscription state: plan changes arrive through webhooks, and premium features turn on and off from what Stripe reports. We’ve also built Stripe Connect escrow for Artswrk and Stripe milestone payments for KeepTrack.
That work is what our payment gateway integration service covers, and it’s part of every MVP Sprint that takes payments. One fixed price, agreed before we start. Sprints start at $12,000. If you need engineers who already know this stack, our page on hiring Supabase and Next.js developers covers that route.
Frequently asked questions
- Should I use the Stripe Sync Engine or Stripe Data Pipeline with Supabase?
- Use the Sync Engine if you want a free, open-source integration you can install from the Supabase dashboard. Use Stripe Data Pipeline if you'd rather pay Stripe to run the sync with no webhooks to maintain. As of November 2026, its Postgres sync is in public preview at $0.0025 per row synced, with 5,000 rows free each month.
- Is Stripe Billing Meters deprecated in 2026?
- No. Stripe's docs say basic usage-based billing on the Meters API remains fully supported for existing integrations, and you don't need to migrate. For new usage-based integrations, Stripe recommends Metronome as the starting point. What is gone are legacy usage records and metered prices without a meter, removed in API version 2025-03-31.basil.
- When should I revoke access after a failed Stripe subscription payment?
- Revoke access when the subscription moves to canceled or unpaid, which happens after Stripe's retries run out. While it is past_due, tell the customer and ask them to update their card, but keep the account usable. For new Stripe accounts, Smart Retries default to up to 8 retries within 2 weeks before the final status is set.
- How do I gate features by plan in a Supabase app?
- Map each feature to a Stripe Entitlements feature with a lookup key, attach features to products, and store the customer's active entitlements in a Postgres table when the entitlement summary event arrives. Your app and your row level security policies then check that table instead of plan names, so a pricing change doesn't need a code change.
- Can I query Stripe directly from Supabase instead of syncing?
- You can, with the Stripe foreign data wrapper, but it turns each SQL query into Stripe API calls, so frequent queries and joins run into Stripe's rate limits. It suits occasional admin queries. For access checks on every request, keep a synced copy of subscription state in Postgres and read from that.
References
- Stripe Docs - Basic usage-based billing (Metronome or Meters)
- Stripe Docs - How Metronome works with Stripe
- Stripe changelog - Removes legacy usage-based billing (2025-03-31.basil)
- Stripe - Billing pricing
- Stripe Docs - Recurring pricing models
- Stripe Docs - Using webhooks with subscriptions
- Stripe Docs - Receive Stripe events in your webhook endpoint
- Stripe Docs - Entitlements
- Stripe Docs - Automate payment retries (Smart Retries)
- Stripe - Tax pricing
- Stripe - Data Pipeline pricing
- Supabase - Sync Stripe data to your Supabase database in one click
- Supabase - Transferring the Stripe Sync Engine to Stripe
- Supabase - Stripe Data Pipeline now syncs real-time data to Supabase
- GitHub - stripe/sync-engine
- GitHub - t3dotgg/stripe-recommendations