Epicure/STRIPE_PLAN.md

Stripe Integration Plan

Status: planning only — nothing in this doc is implemented yet

This plan builds on infrastructure that already exists in the repo (from an earlier security-audit pass), not a blank slate. Before touching anything, know what's already there:

Already built:

• users.tier enum column (free | pro | family), packages/db/src/schema/users.ts:33
• users.stripeCustomerId (nullable, unique), users.ts:34 — migration 0013_damp_richard_fisk.sql
• processed_stripe_events table (webhook dedup log), packages/db/src/schema/billing.ts:7-11 — migration 0024_moaning_roughhouse.sql
• tierDefinitions table (per-tier numeric limits), packages/db/src/schema/tiers.ts:14-20, admin-editable via /admin/tiers + TierLimitsForm
• A hand-rolled inbound webhook at apps/web/app/api/webhooks/stripe/route.ts — manual HMAC-SHA256 signature verification (t=/v1= parsing, crypto.timingSafeEqual, 300s tolerance window), handling exactly two event types (checkout.session.completed, customer.subscription.deleted), everything else silently ignored
• STRIPE_WEBHOOK_SECRET env var, read directly via process.env, not through site-settings.ts
• apps/web/app/api/v1/admin/users/[id]/route.ts — a second, independent path that can set users.tier (manual admin override), which will need to coexist with Stripe-driven tier changes without fighting them

Not built at all:

• The stripe npm package — nothing in the repo imports it; the existing webhook route re-implements signature verification instead of using stripe.webhooks.constructEvent
• Checkout Session creation, Customer Portal, Price/Product IDs anywhere, lib/stripe.ts, a Billing admin page, handling for subscription.updated / invoice.payment_failed / trial events

The plan below fills those gaps and asks you to make a handful of product decisions before code starts (marked DECISION NEEDED).

---

1. Scope & product decisions (answer before implementation starts)

These aren't engineering choices — they change what gets built. Flagging rather than guessing:

• Pricing amounts — recommended, see §1c. Pro €4.99/mo (€39/yr), Family €8.99/mo (€69/yr). Still a decision to confirm, not locked — §1c has the full reasoning.
• Family tier is multi-user, confirmed. One subscription, shared by several app accounts (Netflix/Spotify-Family model) — not one-tier-per-payer like Pro. This needs a new schema concept (§1a) and changes how a member's effective tier gets resolved. See below.
• DECISION NEEDED — Family member cap. How many accounts per family subscription? (Netflix Family = 5, Spotify Family = 6.) A flat number, enforced app-side — recommend 5 as a default, easy to change later since it's just a constant, not a schema value.
• DECISION NEEDED — Downgrade/cancellation behavior. Cancel immediately (lose Pro/Family features now) or at period end (keep access until the paid period runs out, matching what Stripe bills)? Recommend at period end — standard SaaS expectation, and Stripe's Customer Portal defaults to this. For Family specifically, also decide: if the owner cancels, do members lose access immediately at that point, or also ride out the period end? Recommend the latter for consistency.
• DECISION NEEDED — Trial period? None, or e.g. 14 days no card required? Affects Checkout Session config (subscription_data.trial_period_days) and whether tier should flip to pro optimistically before payment or wait for checkout.session.completed.
• Proration — Stripe handles this automatically on plan-switch (Pro↔Family); no schema work needed, just don't fight it by writing custom proration logic. Doesn't apply to adding/removing family members, since that's flat-price (§1a), not quantity-based.

Everything else below assumes: monthly + optional annual price per paid tier, flat-price Family (not per-seat billing), cancel-at-period-end, and trial handling deferred until the above is answered (the plumbing supports adding it later without further schema changes).

---

1a. Family groups — the multi-user piece (Netflix-style, decided)

This is genuinely new scope, not just a billing detail — Stripe only ever bills one Customer per subscription; grouping several app accounts under that one subscription is something Epicure has to model itself.

Decided: flat price, capped membership, no per-seat billing — one Stripe Price for "Family" regardless of exact member count up to the cap (§1, default 5), same shape as Netflix/Spotify Family. No Stripe API calls on join/leave — membership is purely an app-side concern; Stripe only ever sees the owner's one subscription. (Ruled out: per-seat/quantity-based billing, where the subscription's quantity tracks member count and every join/leave calls stripe.subscriptions.update — more correct if you wanted to charge per head, but that's not what "Family" means here.)

New tables (packages/db/src/schema/billing.ts, alongside processedStripeEvents), same shape as the sharing tables you already have (collectionMembers, mealPlanMembers):

export const familyGroups = pgTable("family_groups", {
  id: text("id").primaryKey(),
  ownerId: text("owner_id").notNull().references(() => users.id, { onDelete: "cascade" }),
  stripeSubscriptionId: text("stripe_subscription_id"), // the owner's subscription — billing lives here, not per-member
  createdAt: timestamp("created_at").notNull().defaultNow(),
});

export const familyMembers = pgTable("family_members", {
  id: text("id").primaryKey(),
  groupId: text("group_id").notNull().references(() => familyGroups.id, { onDelete: "cascade" }),
  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }).unique(), // a user is in at most one family group
  joinedAt: timestamp("joined_at").notNull().defaultNow(),
});

Tier resolution changes. Today apps/web/lib/tiers.ts:42-43 reads users.tier straight from the DB as the source of truth. With family groups, a member's effective tier is no longer just their own column — it's "family" if they're in a group whose owner has an active subscription, regardless of what their own users.tier sits at. checkAndIncrementTierLimit (and anywhere else users.tier is read for gating, e.g. getMessages's usage-quota-section in §7) needs a resolution step: look up group membership first, fall back to the user's own tier column if not in a group. Keep the owner's own users.tier as the real, webhook-driven value (that's what Stripe events update, per §5) — members don't get their own tier column changed at all, they're resolved dynamically through the group.

Invite flow — an owner needs a way to invite people into their family group (email invite or a shareable link, similar to the existing invites table/flow used for beta signups — apps/web/lib/invites.ts is a close precedent for the invite-token mechanics, though that system is signup-time only and would need adapting for "join an existing user into a group"). New endpoints: POST /api/v1/family/invite, POST /api/v1/family/join/{token}, DELETE /api/v1/family/members/{userId} (owner removes someone, or a member leaves).

What happens if the owner's subscription lapses (customer.subscription.deleted webhook) — every member in that group loses "family" status simultaneously, purely as a side effect of the tier-resolution fallback above (no per-member cleanup needed, since membership rows aren't what grants tier — the group's subscription status is). The group row itself can stay (in case they resubscribe) or get cleaned up — low-stakes choice, doesn't affect billing correctness either way.

---

1b. Promotions/discounts

Stripe already has this fully built (Coupons + Promotion Codes) — no custom discount logic needed. Two layers, both worth doing:

• Checkout-side (do this, it's one flag): pass allow_promotion_codes: true when creating the Checkout Session (§5). Stripe then shows a "Add promotion code" field on the hosted Checkout page itself — percent-off, fixed-amount-off, free trial extension, redemption limits, expiry dates, first-time-customer-only, all handled by Stripe, none of it built by us.
• Creating/managing codes: done in the Stripe Dashboard, not Epicure's admin — Stripe's Coupon/Promotion-code UI already covers this well, and duplicating it would be pure rebuild-the-wheel. No API integration required for this part at all.
• Optional — admin visibility page: if you want to see active promotions without leaving Epicure, a read-only /admin/billing widget can list them via stripe.promotionCodes.list({ active: true }) (a few lines, uses the same lib/stripe.ts client from §2). This is display-only, reading Stripe's data — it does not need its own schema, table, or write path. Nice-to-have, not required for promotions to work.

So: promotions work the moment allow_promotion_codes: true ships with Checkout — everything else here is optional polish.

---

1c. Recommended pricing (resolves the §1 "pricing amounts" decision)

A starting recommendation, not a locked-in number — see the "adjust after launch" note at the end.

Tier	Monthly	Annual	Annual discount
Free	€0	—	—
Pro	€4.99	€39	~35% off (39 vs 59.88)
Family	€8.99	€69	~36% off (69 vs 107.88)

Why these numbers, not round-trip guesses:

• Stripe's fee floor makes very cheap pricing inefficient. Domestic EEA rate is 1.5% + €0.25 (§10). At €0.99/month that flat €0.25 alone is >25% of revenue before the percentage even applies — pricing has to clear roughly €3–4 before the fixed component stops dominating. €4.99 clears it comfortably.
• Priced against the AI cost the tier actually permits, not against competitors. tierDefinitions already caps Pro at 500 AI calls/month, Family at 2000 (packages/db/src/schema/tiers.ts). Those calls cost real money once they leave OpenRouter's free tier — €4.99 needs to cover the realistic per-user AI spend plus Stripe's cut plus margin, not just "feel competitive." The actual per-call cost depends on which model users end up on (admin-configured default, or BYOK bypasses this entirely per aiConfig.isByok skip-quota logic already in withAiQuota) — this is the part most likely to be wrong before you have real usage data, not the psychology of the price itself.
• Annual discount (~35%) is the standard SaaS anchor — enough to visibly reward committing, not so steep it cannibalizes monthly revenue or makes monthly pricing look like a rip-off by comparison. Also improves cash flow (a year of revenue upfront) and reduces monthly churn-management overhead (11 fewer renewal events per converted customer per year).
• Family priced below 2× Pro on purpose. €8.99 vs €9.98 (2 × €4.99) — the whole pitch of a household plan is "cheaper than everyone buying Pro separately." If Family cost the same or more than 2 individual Pro subscriptions, nobody rational picks it over just having each person subscribe individually (or one person subscribing and not sharing at all, which the member cap in §1a doesn't prevent — sharing outside the app isn't something billing can stop, only the in-app group feature needs pricing that makes joining the group the obviously better option over each member paying separately).
• Family's 4× AI-call allowance (2000 vs Pro's 500) for less than 2× the price is intentional generosity, not an oversight — it's the concrete value-per-euro reason to pick Family over "everyone just buys their own Pro," beyond the flat convenience of one payment.

Adjust after launch, and adjust the price — not the AI-call limits. Limits are what users plan around; changing them after people are used to a number reads as a downgrade even if the price stays flat. Price is the variable meant to absorb reality once you have actual OpenRouter spend-per-active-user data — if real costs run higher than assumed here, raise Pro/Family prices (existing subscribers keep their price until they actively resubscribe/change plans, per Stripe's normal behavior — see §8's note on the admin manual-override path for edge cases), don't quietly shrink what €4.99 already promised someone.

---

2. Package & client setup

• Add stripe (server SDK) to apps/web/package.json. Do not add @stripe/stripe-js/@stripe/react-stripe-js — Checkout/Portal are hosted redirects, no Stripe Elements needed for v1 (see §7 for why hosted over custom).
• New apps/web/lib/stripe.ts — single Stripe client instance (mirrors the existing provider-factory pattern in lib/ai/factory.ts: one place that constructs the third-party client from a resolved secret key, everything else imports from here).
• Replace the hand-rolled verifier in apps/web/app/api/webhooks/stripe/route.ts with stripe.webhooks.constructEvent(rawBody, signature, secret). Same security properties (timing-safe compare, timestamp tolerance), less code to maintain, and gives typed Stripe.Event/Stripe.Checkout.Session/etc. instead of the current loosely-typed inline interface at route.ts:71. Keep the processed_stripe_events dedup insert exactly as-is — it's correct and SDK-agnostic.

---

3. Secrets & config

Follow the existing site-settings.ts pattern (apps/web/lib/site-settings.ts) rather than plain env vars — it already does AES-256-GCM encryption for exactly this kind of admin-managed secret (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.), and it's the mechanism the admin UI in §6 will read/write.

• Add to SiteSettingKey union: "STRIPE_SECRET_KEY", "STRIPE_PUBLISHABLE_KEY", "STRIPE_WEBHOOK_SECRET".
• Add "STRIPE_SECRET_KEY" and "STRIPE_WEBHOOK_SECRET" to SECRET_KEYS (encrypted at rest). Publishable key is not secret — store it plain, same as the VAPID public key is treated today.
• lib/stripe.ts's client construction calls getSiteSetting("STRIPE_SECRET_KEY") (DB → env fallback, exactly like every other provider key already does) instead of reading process.env directly.
• Update .env.example's existing # Stripe (optional — webhook stub only) section: keep STRIPE_WEBHOOK_SECRET as the bootstrap/self-hosted fallback, add commented STRIPE_SECRET_KEY= / STRIPE_PUBLISHABLE_KEY= for the same reason. Self-hosters without the admin UI set up yet still need an env-var path — don't remove it, just make DB-stored take precedence (matches current getSiteSetting fallback order).
• Never let the secret key or webhook secret be readable from any API response, including admin ones — mirror how getAllSiteSettings presumably masks secret values today (verify this before adding Stripe keys to that list; if it doesn't mask, that's a pre-existing gap worth fixing first, not something to inherit).

---

4. Schema changes

Plus familyGroups/familyMembers from §1a — this section covers the per-tier/per-user additions:

tierDefinitions (packages/db/src/schema/tiers.ts) — add:

stripeProductId: text("stripe_product_id"),
stripePriceIdMonthly: text("stripe_price_id_monthly"),
stripePriceIdYearly: text("stripe_price_id_yearly"), // nullable if no annual option

Nullable — the free row has none. This is how a webhook event (which carries a Price ID) maps back to a tier: tierDefinitions becomes the single source of truth for "which Stripe Price = which tier," looked up once and cached in memory per request (small table, 3 rows).

users — add:

stripeSubscriptionId: text("stripe_subscription_id"),
subscriptionStatus: pgEnum("subscription_status", ["active", "trialing", "past_due", "canceled", "incomplete"])(...).nullable(),
currentPeriodEnd: timestamp("current_period_end"),

Deliberately not a separate subscriptions table — the existing model is one-tier-per-user with no subscription history requirement anywhere else in the app. A join table would be over-engineering for a product that doesn't have multi-subscription users. If that ever changes (e.g. add-ons, multiple products per user), revisit then.

subscriptionStatus matters beyond just tier: a past_due user should probably keep Pro access for a grace period (Stripe retries the card automatically) rather than being instantly downgraded on invoice.payment_failed — that's a product call, not this plan's to make, but the column needs to exist either way to display "payment failed, update your card" in the UI (§7).

Generate + apply via the existing pnpm db:generate / pnpm db:migrate flow, same as every other schema change this session.

---

5. API routes

New, under apps/web/app/api/v1/billing/:

• POST /api/v1/billing/checkout — body { tier: "pro" | "family", interval: "month" | "year" }. Looks up the matching stripePriceId* from tierDefinitions, creates a Checkout Session (mode: "subscription", customer: existing stripeCustomerId ?? create one, success_url/cancel_url back into the app, allow_promotion_codes: true — see §1b), returns { url } for the client to redirect to. Gated by requireSessionOrApiKey, rate-limited like other mutating routes (applyRateLimit).
• POST /api/v1/billing/portal — no body. Requires users.stripeCustomerId to already exist (i.e., user has been through Checkout at least once); creates a Billing Portal Session, returns { url }. This is where users self-serve cancel/upgrade/update card — don't rebuild that UI, Stripe's hosted portal already does it.
• GET /api/v1/billing/status — returns the current user's { tier, subscriptionStatus, currentPeriodEnd, hasStripeCustomer } for the client UI in §7 to render without needing a webhook round-trip on every page load.

Rewrite apps/web/app/api/webhooks/stripe/route.ts to handle the full event set instead of two:

Event	Action
checkout.session.completed	Set tier (looked up from the session's Price ID → tierDefinitions, not hardcoded to "pro" like today), stripeCustomerId, stripeSubscriptionId
customer.subscription.updated	Sync tier (plan switch), subscriptionStatus, currentPeriodEnd
customer.subscription.deleted	tier: "free", subscriptionStatus: "canceled"
invoice.payment_failed	subscriptionStatus: "past_due" — do not downgrade tier here, Stripe will retry and either recover (→ subscription.updated) or eventually cancel (→ subscription.deleted)
invoice.paid	Clear past_due back to active if it was set (belt-and-suspenders alongside subscription.updated)

Every handler writes an auditLogs row (action: "billing.<event>"), same pattern already used for admin tier edits — gives you a history for support/debugging without querying Stripe's dashboard.

---

6. Admin panel

Add one nav entry to apps/web/app/admin/layout.tsx's adminNav array → apps/web/app/admin/billing/page.tsx.

Page contents:

1. Connection status — is STRIPE_SECRET_KEY configured (DB or env)? Test-mode or live-mode key (Stripe keys are prefixed sk_test_/sk_live_ — detectable without an API call)? Link to configure, reusing the same settings-form pattern already used for AI provider keys in /admin/ai-config.
2. Price mapping — extend the existing TierLimitsForm (apps/web/components/admin/tier-limits-form.tsx) with the three new stripe* fields per tier, saved through the same PATCH /api/v1/admin/tiers/{tier} route (widen its Zod schema and NUMERIC_FIELDS→include these as string fields). Keeps one form per tier instead of a second parallel UI.
3. Insights — computed from local DB (fast, no Stripe API call, no rate-limit exposure):
   • Active subscriber count per tier (count(*) from users where tier != 'free' group by tier)
   • MRR estimate: active pro count × pro monthly price + active family count × family monthly price — price pulled from tierDefinitions or a small hardcoded display value if Stripe Prices aren't fetched live (fetching live pricing from Stripe on every admin page load is unnecessary; prices don't change often enough to justify the API call/latency)
   • Failed payments needing attention: count(*) from users where subscriptionStatus = 'past_due', listed with links to each user's admin detail page
   • Recent billing events: last N rows from auditLogs filtered to action LIKE 'billing.%'
4. Active promotions (optional, read-only) — stripe.promotionCodes.list({ active: true }), displayed as a small table (code, discount, redemption count/limit, expiry). Creating/editing codes still happens in Stripe's own dashboard (§1b) — this widget is purely so you can glance at what's live without leaving Epicure.
5. Link out to Stripe Dashboard for anything deeper (full transaction history, disputes, tax, creating/editing promotion codes) — don't rebuild Stripe's own reporting, that's what their dashboard is for.

This matches the existing admin philosophy in this codebase: local DB for fast/cheap counts (see /admin/storage, /admin/page.tsx's overview stats), external dashboard link for anything that needs Stripe's own depth.

---

7. User-facing UI/UX

New page: /settings/billing (alongside the existing /settings/ai etc. — same route-group, same layout conventions).

Sections, top to bottom:

1. Current plan card — tier name, price, renewal date (currentPeriodEnd), status badge (reuse the Badge/color-variant pattern already used for tier/visibility badges elsewhere). If past_due: a prominent warning with a "Manage billing" button (→ Portal) to fix the card — don't bury this.
2. Usage this month — this already exists! apps/web/components/settings/usage-quota-section.tsx (built earlier this session) shows AI-calls/recipes/storage against tier limits with progress bars. Reuse it verbatim on this page instead of only on /settings/ai — it's exactly the "why upgrade" nudge a billing page wants, and it's already wired to tierDefinitions/userUsage.
3. Plan comparison / upgrade cards — one card per tier (Free/Pro/Family), current plan visually distinguished (border/highlight), feature list pulled from tierDefinitions values formatted as copy ("50 recipes/month" vs "Unlimited"), monthly/annual toggle if annual pricing exists (§1), a primary button per non-current tier → POST /api/v1/billing/checkout → redirect to session.url.
4. Manage billing button (if stripeCustomerId exists) → POST /api/v1/billing/portal → redirect.
5. Family group panel (only relevant once on the Family tier): if you're the owner — member list (avatar/name), an "Invite" button (email or copyable link, per §1a), a remove button per member. If you're a member (not owner) — who owns the group, a "Leave family" action, and no billing controls (owner manages that in Portal, member has no stripeCustomerId of their own from this subscription). Reuse the member-list UI patterns already built for collectionMembers/mealPlanMembers sharing (apps/web/components/collections/*, apps/web/components/meal-plan/*) rather than inventing new list/avatar-row styling.

"Appealing and fluid" — concretely:

• No new animation library needed — this codebase already gets fluid-feeling transitions from Tailwind's transition-*/animate-in/animate-pulse utilities and Base UI's data-starting-style/data-ending-style hooks (see components/ui/sheet.tsx), consistently across every dialog/sheet/dropdown already built. Match that, don't introduce framer-motion just for this page.
• Skeleton/pulse loading state for the plan cards while GET /billing/status resolves (same animate-pulse placeholder pattern used in explore-page-content.tsx's search-loading skeleton).
• Checkout/Portal redirects are full-page navigations by design (Stripe-hosted) — the "fluid" part is the return trip: success_url should land back on /settings/billing?checkout=success, which shows an immediate optimistic "Welcome to Pro 🎉" state client-side (don't block on the webhook having landed yet — it usually beats the redirect back, but don't assume it) with a GET /billing/status poll (2–3 retries, short backoff) to confirm and clear the optimistic banner once tier actually updated server-side.
• Progress bars (usage section) and plan cards should use the same Card/Progress primitives already in components/ui/, not new one-off styling — visual consistency with the rest of Settings matters more than novelty here.

---

8. Security & correctness checklist

Carried over from patterns already established in this codebase, applied to the new surface:

• Webhook route: keep raw-body signature verification (SDK now, not hand-rolled) — never trust an unsigned request claiming to be Stripe.
• Idempotency: keep processed_stripe_events dedup insert — Stripe retries webhooks, handlers must be safe to run twice.
• Never let the client dictate tier directly for a Stripe-driven change — only the webhook handler (server-side, signature-verified) writes tier from Checkout/subscription events. The existing admin manual-override path (/api/v1/admin/users/[id]) stays as an explicit, audited escape hatch for support cases — document that using it while a Stripe subscription is active will get overwritten on the next webhook event, so support should cancel-in-Stripe-first if they want to downgrade someone.
• Rate-limit /billing/checkout and /billing/portal (session-creation abuse / accidental double-submit) — same applyRateLimit helper already used everywhere else.
• Checkout Session should set client_reference_id/metadata.userId so the webhook can resolve the user even before stripeCustomerId is set (first-time checkout).
• Test with the Stripe CLI (stripe listen --forward-to localhost:3000/api/webhooks/stripe) in dev before touching production keys — standard Stripe workflow, not specific to this app.

---

9. Rollout order

Suggested build order (each step shippable/testable on its own, matching this session's incremental-ship convention):

1. Schema migration (§4) — no behavior change yet, safe to ship alone.
2. lib/stripe.ts + site-settings keys (§2–3) — still no user-facing change.
3. Rewrite webhook route with real SDK + full event handling (§5) — testable via Stripe CLI against a manually-created test Product/Price, before any UI exists.
4. Admin price-mapping UI (§6.2) — lets you wire real test-mode Price IDs without touching code again.
5. Checkout/Portal API routes + /settings/billing page (§5, §7) — Pro works fully at this point; Family checkout works but sharing doesn't exist yet. Promotions (§1b) ship for free here too, it's the one allow_promotion_codes: true flag on the same Checkout Session call — no separate step.
6. Family groups: familyGroups/familyMembers schema, invite/join/remove endpoints, tier-resolution change in lib/tiers.ts, the family panel in Settings (§1a, §7.5) — ship after Pro is proven working end-to-end, since it's the most novel piece and easiest to get subtly wrong (tier-resolution fallback logic especially).
7. Admin insights dashboard (§6.3) — pure read-side, can land anytime after step 3.
8. Switch test-mode keys → live-mode keys as the very last step, after a full test-mode Checkout→webhook→tier-change dry run (Pro solo and Family group).

---

10. France legal/tax notes

Not legal or tax advice — this is a starting point for a conversation with an actual French accountant (expert-comptable) before real money moves through live-mode keys, not a substitute for one. Confirm the specifics for your situation before launch; figures below are current as of mid-2026 and can change.

• Business structure: for a solo launch, auto-entrepreneur (micro-entreprise) is the cheapest legal structure — no share capital, simplified accounting, charges (URSSAF) only apply to revenue actually invoiced, nothing owed at €0 revenue. Only worth moving to SASU/EURL if you want stricter personal/business asset separation, outside investment, or you exceed the auto-entrepreneur revenue ceiling.
• VAT (TVA) thresholds, 2026, SaaS/subscriptions classified as "prestation de services":
  • Franchise en base: €37,500 revenue — below this, no VAT charged on French customers.
  • Tolerance ceiling: €41,250 — crossing this mid-year means VAT applies immediately from the 1st of that month; between the two thresholds you get until the following January 1st.
  • Unchanged for 2026 (a threshold-unification reform was dropped by Parliament in late 2025).
• Open question — cross-border EU customers: the French franchise en base only covers domestic (France) sales. Selling subscriptions to customers in other EU countries falls under the EU's digital-services VAT regime (OSS — One-Stop-Shop), which has its own rules/threshold, separate from the French one above. Needs accountant confirmation before enabling billing for non-French EU customers — not resolved by this plan, flagging rather than guessing at numbers.
• Stripe fees, France-domestic: 1.5% + €0.25 per transaction (EEA cards). EEA corporate/commercial cards: 1.9% + €0.25. Non-EEA cards: +3.25% on top (~4.75% + €0.25 total). Card issued outside your Stripe account's country: +1.5%. Currency mismatch: +1–2%.
• Stripe Tax (optional automated VAT calculation/filing): 0.5% per transaction in jurisdictions where you're registered to collect tax, plus a small per-calculation API fee above the included quota. Worth it once billing spans multiple VAT jurisdictions and manual rate-tracking gets error-prone; skip it while VAT-exempt under the franchise en base.

Practical order: stay auto-entrepreneur + franchise en base (no VAT complexity) for the initial France-only launch, get the OSS/cross-border question answered before opening Checkout to other EU countries, and only evaluate Stripe Tax once that becomes relevant.