fix(billing): restore default entitlement when a Stripe cancellation …

[BruzWJ]

Summary

Stops a failed or missed Stripe cancellation from leaving a user with no entitled subscription at all.

• handleStripeSubscriptionDeleted() no longer aborts before the entitlement restore. Both settlement steps — syncSubscriptionBillingTierFromStripeSubscription() and handleSubscriptionDeleted() — are wrapped so a failure is logged, the default-tier restore still runs, and the first error is rethrown afterwards. The settled log line now carries settlementFailed.
• Adds restorePersonalEntitlement() in lib/billing/core/subscription.ts: when a personal read finds no entitled row, it calls ensureDefaultUserSubscription() to put the user back on the default tier. It is a no-op when billing is disabled, and never throws — a repair failure falls through so the original billing error surfaces instead of a new one.
• Wires that repair into getActiveSubscriptionForReference() (user references only), getEffectiveSubscription(), and getPersonalBillingSnapshot().
• Adds four tests covering restore-on-read, the billing-disabled no-op, the unrecoverable case still throwing the original error, and the webhook restoring entitlement before rethrowing a settlement failure.

Why

Personal Stripe subscriptions reuse the user's default subscription row rather than creating a separate one. So if the customer.subscription.deleted webhook is dropped, or fails part-way through settlement, that single row is left cancelled and non-entitled — the user has no subscription at all, and every billing read throws for them.

The old handler made this worse: settlement talks to Stripe (overage calculation, final invoicing) and can fail, and an exception there aborted the handler before the code that restores the default tier. A transient Stripe error during cancellation therefore cost the user their default entitlement.

The fix separates the two concerns. Restoring the default tier depends only on local state — the row is not entitling anyone, and the default tier is the floor rather than a revocation — so it runs unconditionally, and settlement failures are surfaced afterwards instead of silently taking entitlement down with them. The read-path repair covers users already stranded by cancellations that failed before this change.

Affected Areas

• apps/tradinggoose
• apps/docs
• packages/*
• Workflows / execution
• Realtime / sockets
• Market data / charting
• Dev tooling / CI / infra
• Documentation only
• Other: Billing / Stripe webhooks

Issue Links( if any )

Validation

# from apps/tradinggoose
bun run vitest run lib/billing/core/subscription.test.ts lib/billing/webhooks/subscription.test.ts
#   Test Files  2 passed (2)
#   Tests  18 passed (18)

bun run type-check
#   ✓ Types generated successfully — tsc --noEmit clean

# from repo root
bunx biome check --unsafe apps/tradinggoose/lib/billing/core/subscription.ts \
  apps/tradinggoose/lib/billing/core/subscription.test.ts \
  apps/tradinggoose/lib/billing/webhooks/subscription.ts \
  apps/tradinggoose/lib/billing/webhooks/subscription.test.ts
#   Checked 4 files in 45ms. No fixes applied.

Note: bunx biome check apps/tradinggoose/lib/billing reports 15 pre-existing formatting errors in files this PR does not touch; the four changed files are clean.

Risk / Rollout Notes

Low risk, no schema or config changes, deploy normally. Two behavior changes worth knowing about:

• customer.subscription.deleted now rethrows settlement failures, so Stripe sees a failed webhook and retries where it previously saw a success. This is intentional — the failure is now visible instead of silent — but expect webhook error alerts for cases that used to pass quietly.
• The Stripe retry is a no-op for personal subscriptions. By the time the error is rethrown, entitlement restore has already cleared stripeSubscriptionId on the reused row, so the retry's getSubscriptionByStripeSubscriptionId() lookup finds nothing and the handler returns early. That is safe (no double settlement) but it means a failed personal overage settlement will not retry itself and needs manual follow-up from the logged Failed to settle a cancelled subscription / settlementFailed: true entries. Workspace subscriptions keep their stripeSubscriptionId and do retry normally.
• Entitlement repair performs a write on a read path. It is idempotent — ensureDefaultUserSubscription() uses a deterministic default-<userId> id with onConflictDoUpdate — and only fires when the user has no entitled subscription, so it is a one-shot per stranded user, not per request.
• Backout: revert the commit. Nothing persisted by this change needs unwinding; users restored to the default tier simply stay on it.

Config / Data Changes

• Env vars added or changed: none
• Database schema or migration impact: none
• External services or provider behavior changed: Stripe customer.subscription.deleted handling only — no API surface change, but the handler's success/failure signal to Stripe is now accurate (see Risk notes)

Screenshots / Video

Checklist

• I kept the change focused and reviewed my own diff
• I validated the change locally and documented the results above
• I updated docs, examples, or copy if behavior/user-facing flows changed
• I called out any env, schema, provider, or rollout impact
• I did not include secrets, tokens, or private credentials in this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
studio (staging)	Ready	Preview, Comment	Jul 27, 2026 12:19am

[greptile-apps]

Greptile Summary

Restores personal default-tier entitlement when cancellation processing or billing reads leave a user without an entitled subscription.

• Skips final settlement when Stripe tier synchronization fails, preserving the subscription identifier for a correctly priced retry.
• Restores entitlement before rethrowing settlement failures and records the failed-settlement state.
• Adds read-path recovery through shared subscription helpers and tests cancellation, recovery, retry reachability, and billing-disabled behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the prior stale-tier pricing issue is addressed by skipping settlement after tier synchronization fails and retry reachability is preserved.

Important Files Changed

Filename	Overview
apps/tradinggoose/lib/billing/core/subscription.ts	Adds non-throwing default-entitlement repair and integrates it into personal subscription reads.
apps/tradinggoose/lib/billing/webhooks/subscription.ts	Separates tier synchronization, settlement, and entitlement restoration while preventing settlement against stale pricing.
apps/tradinggoose/lib/billing/core/subscription.test.ts	Covers successful read-path restoration, billing-disabled behavior, and preservation of the original failure.
apps/tradinggoose/lib/billing/webhooks/subscription.test.ts	Covers entitlement restoration on failure, stale-tier settlement suppression, and retry identifier preservation.

Sequence Diagram

sequenceDiagram
  participant Stripe
  participant Webhook
  participant BillingTier
  participant Settlement
  participant Entitlement
  Stripe->>Webhook: customer.subscription.deleted
  Webhook->>BillingTier: synchronize tier
  alt tier synchronization succeeds
    BillingTier-->>Webhook: verified tier
    Webhook->>Settlement: settle final overage
  else tier synchronization fails
    BillingTier-->>Webhook: error
    Webhook->>Webhook: skip stale-tier settlement
  end
  Webhook->>Entitlement: restore default personal tier
  alt settlement remains owed
    Entitlement->>Entitlement: retain Stripe subscription ID
    Webhook-->>Stripe: rethrow for retry
  else settlement succeeds
    Webhook-->>Stripe: acknowledge deletion
  end

Loading

_{Reviews (2): Last reviewed commit: "fix(billing): skip final overage settlem..." | Re-trigger Greptile}