Proration FAQ

This page answers the most common billing questions about plan changes — especially the ones that come up when you click Downgrade from your workspace's billing settings. KlyHub uses Stripe's standard proration model under the hood; this page translates that into plain English.

How does proration work when I upgrade?

When you upgrade mid-cycle (for example, Solo → Pro on day 15 of a 30-day cycle), Stripe calculates a prorated charge for the upgrade:

1. It refunds the unused portion of your Solo plan (15 days of unused service).
2. It charges you the prorated cost of Pro for the remaining 15 days.
3. The next full Pro charge happens on your normal billing date.

The two amounts are netted on your next invoice, not charged immediately. You'll see a line item like "Unused time on Solo plan" (credit) and "Remaining time on Pro plan" (charge).

How does proration work when I downgrade?

When you downgrade (Pro → Solo), KlyHub's default behavior depends on the billing-state policy the founder picked for you:

• Immediate downgrade with credit (default) — your plan switches to Solo right away. The unused portion of Pro becomes a prorated credit on your Stripe customer record, applied automatically against future invoices. You do not receive a cash refund.
• End-of-cycle downgrade — your plan stays on Pro until your current cycle ends, then drops to Solo on the next renewal date. No credits, no refunds; you keep what you paid for.

The downgrade modal in your workspace shows you which behavior is active for your tenant.

What happens to my Stripe customer credit balance?

Credits sit on your Stripe customer record (visible in the Settings → Billing → Invoice history section). On every future invoice, Stripe automatically applies available credit toward the total. You don't need to do anything; if your monthly Solo bill is $19 and you have $24 in credit, your next invoice charges $0 and your remaining credit drops to $5.

Will I get a cash refund?

KlyHub does not issue cash refunds for plan downgrades. The default policy is credit-back, which keeps the money in your account and applied automatically to future bills. If you need a cash refund for special circumstances (e.g. workspace closure), contact support.

What about feature differences after a downgrade?

Each tier has a different features_jsonb set — quotas and capabilities. After a downgrade:

• Quotas drop immediately — your entity count, storage, and MCP-query allowances move to the new tier's limits the moment the downgrade applies.
• If you're over the new tier's quota, the workspace enters read-only state until you free up enough space (delete entries) or upgrade again. Your data is never deleted automatically; we just block writes until you're back under the cap.
• Capabilities downgrade gracefully — features like the audit-log Owner UI disappear from the navigation on tiers that don't include them, but historical data is preserved if you upgrade back.

What happens to my methodology Packs after a downgrade?

If you downgrade to a tier with fewer Pack slots, your installed Packs stay enabled but you can't install new ones until you free up slots (uninstall an existing Pack) or upgrade again. We don't auto-uninstall.

Can I switch plans more than once per cycle?

Yes. Each switch triggers its own proration calculation. There's no fee for switching plans, but if you ping-pong many times in one cycle the math on your invoice can get hard to follow — we surface the running credit balance in Settings → Billing so you can sanity-check.

What if my payment fails after an upgrade?

If a prorated upgrade charge fails, KlyHub puts your workspace in a grace period (default 7 days). During grace you keep the upgraded tier; if payment is not recovered, the workspace falls back to read-only and the upgrade is reverted on your next billing date.

Anything else?

Annual plans, partner discounts, and Enterprise contracts have their own proration rules — for those, contact billing support directly. The defaults on this page cover Free / Solo / Pro / Team monthly subscriptions.

For the full billing-state state machine (active ↔ trial ↔ grace ↔ read-only ↔ scheduled-deletion), see the API reference — the billing namespace exposes the state directly.