---
title: "Stripe subscriptions Supabase setup: what to sync and why"
description: "Stripe subscriptions Supabase setup for 2026: mirror billing state with the Sync Engine or Data Pipeline, use Metronome for usage, and plan for failed renewals."
url: https://zeroic.in/blog/stripe-subscriptions-supabase
---

[The Zeroic Journal](https://zeroic.in/blog)

[SaaS](https://zeroic.in/blog/topic/saas) November 4, 2026 8 min read

# Stripe subscriptions Supabase setup: sync, usage billing, dunning

Which Stripe primitive fits each pricing model, how to get billing state into Postgres, and the webhook, dunning and tax details that break first.

By Prashant Abbi Partner @ Zeroic

On this page

1. [Let Stripe own state, keep a copy](#let-stripe-own-state-keep-a-copy)
2. [Stripe subscriptions Supabase sync: three options](#stripe-subscriptions-supabase-sync-three-options)
3. [Match each pricing model to a Stripe primitive](#match-each-pricing-model-to-a-stripe-primitive)
4. [Gate features with entitlements, not plan names](#gate-features-with-entitlements-not-plan-names)
5. [Dunning, tax and webhook edge cases](#dunning-tax-and-webhook-edge-cases)
6. [How to decide](#how-to-decide)
7. [How Prompt Genie runs monthly and annual Stripe plans](#how-prompt-genie-runs-monthly-and-annual-stripe-plans)

On this page 7 sections

1. [Let Stripe own state, keep a copy](#let-stripe-own-state-keep-a-copy)
2. [Stripe subscriptions Supabase sync: three options](#stripe-subscriptions-supabase-sync-three-options)
3. [Match each pricing model to a Stripe primitive](#match-each-pricing-model-to-a-stripe-primitive)
4. [Gate features with entitlements, not plan names](#gate-features-with-entitlements-not-plan-names)
5. [Dunning, tax and webhook edge cases](#dunning-tax-and-webhook-edge-cases)
6. [How to decide](#how-to-decide)
7. [How Prompt Genie runs monthly and annual Stripe plans](#how-prompt-genie-runs-monthly-and-annual-stripe-plans)

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](https://docs.stripe.com/webhooks) 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](https://github.com/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 `2xx` before doing any slow work, and verify the `Stripe-Signature` header 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](https://supabase.com/blog/stripe-sync-engine-integration) 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](https://github.com/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](https://stripe.com/us/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.

OptionCostWho runs itBest for

Sync EngineFree, open sourceSupabase integrationMost new SaaS apps

Data Pipeline$0.0025 per row after 5,000 freeStripeTeams that want no sync code at all

Own handlerYour timeYouA few fields, custom RLS keys

Foreign data wrapperFreeStripe API on every queryAdmin 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](https://docs.stripe.com/products-prices/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](https://docs.stripe.com/billing/subscriptions/usage-based) 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](https://stripe.com/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](https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-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](https://docs.stripe.com/billing/how-metronome-works-with-stripe) 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](https://docs.stripe.com/billing/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](https://zeroic.in/blog/supabase-row-level-security-not-working) 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](https://docs.stripe.com/billing/revenue-recovery/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](https://docs.stripe.com/billing/subscriptions/webhooks) 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](https://stripe.com/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](https://zeroic.in/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](https://zeroic.in/artswrk) and Stripe milestone payments for [KeepTrack](https://zeroic.in/keeptrack).

That work is what our [payment gateway integration](https://zeroic.in/payment-gateway-integration) service covers, and it’s part of every [MVP Sprint](https://zeroic.in/services/mvp-development) 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](https://zeroic.in/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

1. [Stripe Docs - Basic usage-based billing (Metronome or Meters)](https://docs.stripe.com/billing/subscriptions/usage-based)
2. [Stripe Docs - How Metronome works with Stripe](https://docs.stripe.com/billing/how-metronome-works-with-stripe)
3. [Stripe changelog - Removes legacy usage-based billing (2025-03-31.basil)](https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-legacy-usage-based-billing)
4. [Stripe - Billing pricing](https://stripe.com/billing/pricing)
5. [Stripe Docs - Recurring pricing models](https://docs.stripe.com/products-prices/pricing-models)
6. [Stripe Docs - Using webhooks with subscriptions](https://docs.stripe.com/billing/subscriptions/webhooks)
7. [Stripe Docs - Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)
8. [Stripe Docs - Entitlements](https://docs.stripe.com/billing/entitlements)
9. [Stripe Docs - Automate payment retries (Smart Retries)](https://docs.stripe.com/billing/revenue-recovery/smart-retries)
10. [Stripe - Tax pricing](https://stripe.com/tax/pricing)
11. [Stripe - Data Pipeline pricing](https://stripe.com/us/data-pipeline/pricing)
12. [Supabase - Sync Stripe data to your Supabase database in one click](https://supabase.com/blog/stripe-sync-engine-integration)
13. [Supabase - Transferring the Stripe Sync Engine to Stripe](https://supabase.com/blog/stripe-sync-engine-transfer)
14. [Supabase - Stripe Data Pipeline now syncs real-time data to Supabase](https://supabase.com/blog/stripe-data-pipeline-now-syncs-real-time-data-to-supabase)
15. [GitHub - stripe/sync-engine](https://github.com/stripe/sync-engine)
16. [GitHub - t3dotgg/stripe-recommendations](https://github.com/t3dotgg/stripe-recommendations)

#stripe#supabase#billing#subscriptions#saas

More from the journal

[ SaaS

## [Supabase multi tenant RLS: patterns that hold up](https://zeroic.in/blog/supabase-multi-tenant-rls)

Shared schema, schema per tenant or a project per tenant: when each wins on Supabase, what fails first in each, and where the Stripe subscription belongs.

Prashant Abbi Nov 9, 2026 · 8 min read

[ Software engineering Best tools

## [Best apps built with Supabase (2026)](https://zeroic.in/blog/best-apps-built-with-supabase)

Ten live products that say they run on Supabase, from email APIs to compliance tools, grouped by market, and when building your own makes sense.

Prashant Abbi Oct 24, 2026 · 10 tools

[ SaaS

## [Is Supabase HIPAA compliant? What you still add](https://zeroic.in/blog/supabase-hipaa-compliant)

Supabase signs a BAA and offers a HIPAA add-on. Access rules, logging and the rest of the compliance work stay with you, and here's the list.

Prashant Abbi Oct 26, 2026 · 6 min read

## Hear from Prashant within 24 hours.

**Prashant Abbi** Partner @ Zeroic

Wiring Stripe billing into a Supabase app? Tell us your pricing model. We'll map it to the right Stripe primitives, set up the sync into Postgres, and handle webhooks, retries and tax before your first renewal.

[See payment integration](https://zeroic.in/payment-gateway-integration), or [book a 30-minute call](https://zeroic.in/book)

Pages [Services](https://zeroic.in/services) [Work](https://zeroic.in/work) [Blog](https://zeroic.in/blog) [About](https://zeroic.in/about) [Guide for AI](https://zeroic.in/llms.txt)

Services [Audits](https://zeroic.in/services/ai-audit) [MVP Sprint](https://zeroic.in/services/mvp-development) [Retainer](https://zeroic.in/services/senior-developers) [Code Rescue](https://zeroic.in/services/code-rescue) [AI development](https://zeroic.in/ai-development-company) [Fractional CTO](https://zeroic.in/fractional-cto-services)

Solutions [Fix AI-built apps](https://zeroic.in/code-rescue-by-tool) [AI services](https://zeroic.in/ai-services) [Migrations](https://zeroic.in/migrations) [Bubble to code](https://zeroic.in/bubble-to-code) [Build an app like](https://zeroic.in/build-an-app-like)

Industries [Marketplaces](https://zeroic.in/marketplace-app-development) [B2B SaaS](https://zeroic.in/saas-mvp-development) [FinTech](https://zeroic.in/fintech-app-development) [Telehealth](https://zeroic.in/telehealth-app-development) [EdTech](https://zeroic.in/edtech-app-development) [All industries →](https://zeroic.in/industries)

Developers [Bubble](https://zeroic.in/hire-bubble-developers) [React](https://zeroic.in/hire-react-developers) [Python](https://zeroic.in/hire-python-developers) [AI & LLMs](https://zeroic.in/hire-ai-developers) [API integrations](https://zeroic.in/api-integration-services) [All developers →](https://zeroic.in/developers)

Contact [Email](mailto:zeroic.in@gmail.com) [WhatsApp](https://wa.me/919873927225) [LinkedIn](https://www.linkedin.com/company/zeroic/) [X (Twitter)](https://x.com/PrashantAbbi) [Book a call](https://zeroic.in/book)

© 2026 Zeroic [Privacy](https://zeroic.in/privacy) [Terms](https://zeroic.in/terms)

Built in India · Shipping globally

SINCE
