stripe-checkout-subscriptions

Guide for creating Stripe Checkout Sessions for subscriptions in Flutter/Supabase backend. Covers flows, API preferences, and non-negotiable rules.

Stripe Checkout Subscriptions

Source of Truth: All subscription states derive from Stripe Webhooks.

Client → Create Checkout Session → Stripe → Webhook → Supabase.

Listen to profiles table in Supabase for status updates post-payment.
Flutter app NEVER updates its own is_premium flag; it only reads backend-provided state.

Use Stripe Checkout Sessions API for one-time payments and subscriptions.
Model taxes/discounts via Stripe.
For recurring revenue (SaaS-like): Prefer Billing APIs + Stripe Checkout.
Never use Charges API. Migrate to Checkout Sessions or Payment Intents if needed.
For web: Prioritize Stripe-hosted Checkout or embedded Checkout. Payment Element OK for advanced customization (pair with Checkout Sessions).
Never recommend legacy Card Element or Payment Element in card mode.
Avoid deprecated Sources API or outdated Tokens/Charges. Use Setup Intent API for saving payment methods.
For pre‑PaymentIntent rendering: Use Stripe Confirmation Tokens, not createPaymentMethod/createToken.
Turn on dynamic payment methods in dashboard (don't hardcode payment_method_types).
Default to latest API version: 2026-01-28.clover (unless user specifies otherwise).
Use env vars: STRIPE_SECRET_KEY.