Skip to content

docs: add Plans & Upgrading guide - #684

Open
eseidel wants to merge 2 commits into
mainfrom
docs/plans-and-upgrading
Open

eseidel wants to merge 2 commits into
mainfrom
docs/plans-and-upgrading

Conversation

@eseidel

@eseidel eseidel commented Sep 22, 2026

Copy link
Copy Markdown
Contributor

Summary

We had no guide on how to upgrade an account. The only instructions were a two-sentence FAQ entry (pointing at /subscriptions/create and "email billing@ for yearly") plus a one-liner in Organizations, and the FAQ's cancel steps (Manage Plan -> Edit -> Cancel Subscription) no longer match the console.

This adds Account → Plans & Upgrading (/account/plans/) covering:

  • Who can change the plan (plans belong to the account; org owner has to upgrade)
  • Upgrade from Free (Stripe checkout)
  • Pro → Business (immediate, prorated)
  • Monthly ↔ annual (monthly→annual immediate; annual→monthly scheduled)
  • Business → Pro (scheduled for period end, "Keep current plan" to undo)
  • Cancel (runs to period end, then Free; "Resume plan" to undo)
  • Enterprise / negotiated plans → sales
  • Troubleshooting: "I upgraded but my org still shows the old plan", "Change plan is disabled" (past due)

The FAQ, Organizations, and Billing pages now link to it, and the sidebar order in Account is Organizations → Plans & Upgrading → Billing → the rest.

Button labels and the immediate-vs-scheduled rules come from the console source (account.plan.tsx, plan-selection-modal.tsx, plan-actions.tsx, cancel-plan-dialog.tsx, classifyPlanChange in stripe.server.ts).

Things to check before publishing

  • I couldn't click through the live console, so the step sequences are from source; worth a sanity click-through.
  • The FAQ previously said monthly→yearly needs an email to billing@. The console now offers it self-serve (Switch to Pro annual), so I dropped that. Confirm that's the intended path.
  • view_billing_portal.png on the Billing page shows the old "Edit" dropdown (Upgrade to Pro (monthly) etc.), which no longer exists. Not touched here — a new screenshot would help.
  • The console's plan picker lists "Viewer & App Manager roles" under Business, but orgs.mdx says App Manager is Enterprise-only. One of them is wrong; not touched here.

Test plan

  • npx astro build passes, including starlight-links-validator
  • cspell clean on the new page

Adds account/plans.mdx describing how to upgrade from Free, move between
Pro and Business, switch billing intervals, cancel, and reach sales for
Enterprise, based on the console's current Plan page. Points the FAQ,
Organizations, and Billing pages at it and retires the stale
"Manage Plan -> Edit -> Cancel Subscription" instructions.
Plan names are proper nouns, so allow them in headings, and use link
text for the billing address so the Terms rule does not read it as a
lowercase Shorebird.
@eseidel
eseidel requested a review from easymac September 22, 2026 04:11
@eseidel
eseidel marked this pull request as ready for review September 22, 2026 04:11
@eseidel

eseidel commented Sep 22, 2026

Copy link
Copy Markdown
Contributor Author

This was all claude. Seems to be right. I read through it all.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant