Subscription Management

This document explains how StratoFusion models Free, Pro, Unlimited, and trial access across Stripe, Clerk metadata, and the local Postgres projection.

Canonical Rules

• Free tier remains the default for every new account.
• Pro and Unlimited trials are opt-in and only start from explicit Start Free Trial entry points.
• Trials last 7 days.
• A user only gets the trial if Stripe, Clerk metadata, and the Postgres projection do not already show prior managed StratoFusion subscription or trial history.
• The billing page uses the same eligibility evidence before showing Start Free Trial; returning Free users with trial history see direct subscribe actions instead.
• Existing paid subscribers do not see trial UI.
• If a trial ends without payment, the user must return to Free.

State Sources

Stripe

Stripe is the source of truth for:

• customer identity.
• active subscription status.
• trial start and end timestamps.
• conversion from trialing to active.
• cancellation after a trial with no payment method.

Stripe remains the billing source of truth, but it is not the source for explicit internal testing entitlements. Internal entitlements never create or modify Stripe customers, subscriptions, invoices, or payment state.

Clerk publicMetadata

Clerk mirrors Stripe state for request-time access control and UI hydration:

• subscriptionTier.
• subscriptionStatus.
• currentPeriodEnd.
• subscriptionExpiresAt.
• stripeCustomerId.
• stripeSubscriptionId.
• .