App Paywall

Once Stripe or RevenueCat is syncing, every active price lands on the built-in paywall without further work. This page is about the parts you do have to decide: the copy on the cards, the two recovery surfaces around them, one-time "lifetime" plans, and how to switch the whole thing off.

Access itself is gated by hasActiveSubscription in lib/core/presentation/utils/access_gate.dart; see Apps without a paywall to remove the gate entirely.

Plan descriptions

Descriptions come from your payment provider by default. To override them, for localization, or just for better copy, edit the descriptions map already passed to PriceListView in AppPaywall.

Keys are plan names, matched exactly (plan.name, case sensitive). A plan with no entry falls back to the provider's own description.

PriceListView(
  descriptions: const <String, String>{
    'Basic': 'Perfect for getting started.',
    'Premium': 'Best for growing startups and growth companies.',
  },
  // ...
)

Plan features

Same widget, same keys: features maps a plan name to the bullet list rendered under its price.

PriceListView(
  features: const <String, List<FeatureCard>>{
    'Basic': [
      FeatureCard(
        icon: LucideIcons.timer,
        description: 'Access to basic features',
      ),
      FeatureCard(
        icon: LucideIcons.lock,
        description: 'Secure your account',
      ),
    ],
    'Premium': [
      FeatureCard(
        icon: LucideIcons.infinity,
        description: 'Unlimited access to all features',
      ),
      FeatureCard(
        icon: LucideIcons.zap,
        description: 'Premium performance boost',
      ),
    ],
  },
  // ...
)

FeatureCard takes a required description and an optional icon (lib/features/payments/presentation/views/widgets/price_card.dart). Your project ships with example maps for Basic and Premium already filled in; replace them with your own plan names rather than adding a second map.

Both maps are constructor arguments, not global configuration. The billing page mounts its own bare PriceListView() (lib/features/payments/presentation/views/widgets/billing_content.dart), so pass your maps there too if you want the same copy when a subscriber changes plan.

The free-trial badge

A price whose trial_days is greater than zero gets a Free trial 🎉 badge pinned to the right of the card title, and its call to action changes from "Get started with …" to "Start 7 days free trial".

The badge is deliberately quiet. PriceCard suppresses it unless every one of these holds:

• The user holds no manageable subscription. Anyone already subscribed sees plan-switching copy instead.
• The user has never trialled this specific price before.
• The user is not globally trial-ineligible (trialIneligibleSince is unset).
• trial_days > 0 on the price.

Everything behind the badge (how trial_days gets set, eligibility, the trial-ending notifications, and how to let someone trial twice) is on the Free Trials page.

The payment recovery banner

When a card is declined, Stripe does not end the subscription: it moves it to past_due (then unpaid) and keeps retrying. Subscription.isActive() accepts only active and a live trialing, so from the app's point of view the user is instantly gated, and a paywall that offers nothing but "subscribe again" is a dead end for someone who already pays you.

PaymentRecoveryBanner (lib/features/payments/presentation/views/widgets/payment_recovery_banner.dart) is the way out. It renders above the price cards, so it is read first.

It appears when needsPaymentMethodRecovery is true, which means both of:

• the subscription's status is past_due or unpaid, and
• the subscription came from Stripe.

RevenueCat subscriptions are excluded on purpose: their payment method lives in the App Store or Play Store account, not in any portal this app can open.

Its button, UpdatePaymentMethodButton, opens the Stripe billing portal straight onto its add-a-card screen (PaymentActionType.paymentMethodUpdate) and returns the user to the page they were on.

Restore purchases

Store purchases can outlive the account row that recorded them, so Restore purchases reconciles the store receipt against the account. It appears on the built-in paywall, in Account settings, and on RevenueCat's own paywall, wherever context.canRestorePurchases is true. See Restore purchases on the RevenueCat page for the full explanation, including what each outcome means.

Lifetime subscriptions

A "lifetime" plan is a one-time payment wearing a subscription's clothes: the app grants access by reading public.subscriptions, so a one-time purchase has to leave a row there too.

UPDATE prices
SET interval = 'lifetime'
WHERE id = '<lifetime_price_id>';

// The session carries no price of its own; it is on the line items.
const lineItems = await getStripe().checkout.sessions.listLineItems(
  session.id,
  { limit: 1 },
);
const priceId = lineItems.data[0]?.price?.id;
if (!priceId) throw new Error(`No price on session ${session.id}`);

const subscription: TablesInsert<"subscriptions"> = {
  // The session id keeps webhook retries idempotent.
  id: session.id,
  user_id: user.id,
  price_id: priceId,
  status: "active",
  current_period_start: new Date().toISOString(),
  // Far enough out that it never expires in practice.
  current_period_end: new Date(
    new Date().setFullYear(new Date().getFullYear() + 100),
  ).toISOString(),
  cancel_at_period_end: false,
};

const { error } = await supabase.from("subscriptions").insert(subscription);

if (error) {
  console.error(`DB: Error creating subscription ${subscription.id}:`, error.message);
  throw error;
}

The 100-year current_period_end is what makes it work: app.has_entitlement requires status IN ('active','trialing') and current_period_end > now(), and Subscription.isActive() on the client requires the same window. On the paywall itself, a lifetime plan the user already owns shows "Current plan" with no action; there is nothing to manage.

Apps without a paywall

If your app is free, or monetized somewhere other than a subscription, edit one function: hasActiveSubscription in lib/core/presentation/utils/access_gate.dart.

/// Whether [user] holds a subscription that is currently active.
///
/// This app is free, so nobody is ever gated behind the paywall.
bool hasActiveSubscription(User? user) {
  return true;
}

That single edit propagates everywhere the gate is consulted:

• _inactiveSubscriptionRedirect returns null for every route, so no navigation is bounced to /paywall.
• defaultPostAuthPath sends users to the home page after sign-in.
• isGated becomes false, so the nav bar, account settings and keyboard shortcuts stop hiding the app shell from unsubscribed users.

Two loose ends worth tidying:

• test/core/presentation/utils/access_gate_test.dart asserts the old behaviour. Update its hasActiveSubscription group.
• /paywall still resolves if someone types it. Drop the route from PaymentsRouter.routes (lib/features/payments/presentation/router/payments_router.dart) if you want it gone entirely.