Stripe Subscription Billing for Healthcare SaaS: What I Learned Building MealCircle

Why I Delayed Billing Too Long

When I built MealCircle — the retention-first nutrition SaaS for dietitians — I put off integrating Stripe billing for three months. I told myself it was an MVP decision. It was actually procrastination. The integration complexity was the same whether I did it in month 1 or month 4. All I got from delaying was three months of manual invoicing and a growing pile of subscription state to reconcile when I finally built it.

If you're building a healthcare SaaS and billing is "coming later," build it now.

Per-Seat vs Flat-Rate Pricing

MealCircle uses a per-practice flat-rate model with usage-based add-ons (patient slots beyond the base tier). I considered per-seat (per-dietitian) pricing but rejected it for a specific reason: nutrition practices often have administrative staff who need read access but aren't billing clinicians. Per-seat pricing penalizes practices for appropriate access control — which is the wrong incentive for a HIPAA-compliant platform.

Flat-rate per practice + patient slot tiers aligns the pricing with actual value delivered: more patients in the system means more clinical activity, which is when the platform's retention features have impact.

The Stripe Webhook Reliability Problem

Stripe sends webhooks for every subscription event: payment succeeded, payment failed, subscription canceled, invoice finalized. The naive implementation — handle webhook → update database — fails in production because webhooks can arrive out of order and can be retried multiple times.

The pattern that works:

from fastapi import Request, HTTPException
import stripe

@app.post("/webhooks/stripe")
async def handle_stripe_webhook(request: Request):
    payload = await request.body()
    sig_header = request.headers.get("stripe-signature")

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, settings.STRIPE_WEBHOOK_SECRET
        )
    except stripe.error.SignatureVerificationError:
        raise HTTPException(status_code=400)

    # Idempotency: check if we've already processed this event
    if await event_already_processed(event["id"]):
        return {"status": "already_processed"}

    await process_event(event)
    await mark_event_processed(event["id"])
    return {"status": "ok"}

The event_already_processed check with a database table of processed event IDs prevents duplicate processing from Stripe's retry logic — which fires if your webhook returns a non-200 response.

Failed Payment Flows

Subscription SaaS has a churn category that non-SaaS products don't: involuntary churn from failed payments. The flow needs to be:

1. Payment fails → Stripe retries per Smart Retries schedule (typically 3–4 attempts over 7 days)
2. After first failure → email to practice with "update payment method" link
3. After final failure → suspend account (read-only mode, no new patient slots)
4. 30-day grace period before deletion

In MealCircle, suspended accounts go read-only rather than fully inaccessible — practices can still view existing patient data but can't add new patients or run retention workflows. This reduces churn from payment failure because practices retain access to their clinical history while resolving billing issues.

HIPAA and Payment Data

Payment card data (PAN, CVV) is PCI-DSS scope, not HIPAA scope. Stripe handles all card data — MealCircle never touches raw card numbers. What is HIPAA-relevant is the link between a Stripe customer ID and a practice's PHI. The Stripe customer record should contain only the practice's billing identity, not any patient information. Patient data stays entirely within the application's HIPAA-compliant infrastructure.

See MealCircle's founding story for the product context, or how it works for the clinical workflow.

Custom subscription billing is a standard component of the Custom Practice Management service — designed around your pricing model from the start.