Billing & plans

Billing (/billing) is where you manage your workspace’s subscription: pick a plan, watch your quota usage, top up a USD wallet, attach add-ons, review invoices, change your payment method, and cancel. It’s an account-level page managed by the workspace owner — everything lives on one screen so you never leave to a separate billing portal. The billing backend is live: checkout, wallet, add-ons, invoices, and cancellation all run against real providers.

Change your plan, step by step

1. In the Compare plans section, toggle Monthly or Annual (annual takes −8% off the monthly rate).
2. Pick a payment provider in the Pay with row — the picker is filtered to what’s available in your region (a card rail like Polar or Stripe, or a local rail like VNPay / Alipay / WeChat Pay). Providers shown with a soon badge aren’t enabled yet.
3. Click Upgrade (or Downgrade) on the plan column you want.
4. You’re redirected to the provider’s hosted checkout. On success you land back on /billing and your new plan + quota apply once the provider’s webhook confirms the payment.

Upgrade vs downgrade timing

Upgrades take effect as soon as the payment clears. A downgrade applies at the end of the current period — you keep the higher quota until then.

Plans & quotas

Plan	Price	VPS	Sites	Operators	Highlights
Free	$0	1	Unlimited	1	Site CRUD, basic SSL, local backups, web terminal
Plus	$8/mo	3	Unlimited	2	+ Offsite backup (S3 / B2 / GDrive), Cloudflare, +1 teammate
Pro	$22/mo	10	Unlimited	5	+ Customer share-host, monitoring, Docker apps, staging + Git deploy
Max	$49/mo	25	Unlimited	Unlimited	+ Priority support, public API access, audit-log export, white-label

Sites are unlimited on every plan — tiers differ on how many servers you can connect and which features unlock. The Usage panel on the current-plan card shows ring gauges for VPS and Operators, turning amber near the limit and red at it.

Annual billing (−8%) works out to:

Plan	Effective /mo	Billed yearly
Plus	$7.36	$88.32
Pro	$20.24	$242.88
Max	$45.08	$540.96

See Tiers & quotas for how the limits are enforced.

What else you can do

• Top up the wallet — click Top up on the wallet card, pick a rail, and choose a pack: $10, $25 (+$1 bonus), $50 (+$4), or $100 (+$12). The wallet is a plain USD balance that funds add-ons and local-rail plan renewals.
• Attach add-ons — extend capacity beyond your plan; each is billed monthly and paid from your wallet:
  • Extra server slot — $3/mo per slot (Plus and up)
  • Operator seat — $3/mo per seat (Pro and up)
  • Offsite backup +100 GB — $2/mo (Plus and up)
  • White-label / reseller — $29/mo (Pro and up) Use the − / + stepper to set the quantity, then Attach. Remove one anytime.
• Manage payment method — opens your provider’s hosted portal (Manage payment method) to change or remove the card. Card details never touch MZPanel.
• Review invoices — the Invoices card lists each invoice with its status and a PDF link, attributed to the provider that issued it.
• Read the wallet ledger — Wallet activity shows every top-up, bonus, add-on charge, and auto-debit so the balance always reconciles.
• Cancel — in the danger zone, Cancel plan → Cancel at period end. You keep your plan until the period ends, then the workspace drops to Free.

How it works

The page is backed by /v1/billing/* on the control plane, and all entitlement reads come straight from MZPanel’s own database (never from a provider), so the panel keeps working even if a provider is slow or draining:

Action	Route	What happens
Load the page	GET /billing/overview	Plan, status, usage (real active-server + operator counts), payment method
Wallet balance / ledger	GET /billing/wallet, /billing/transactions	Live balance + last 50 ledger rows
Invoices	GET /billing/invoices	Synced back from the provider via webhook
Provider picker	GET /billing/providers?action=subscribe|topup	Region- + capability-filtered rails
Upgrade / change plan	POST /billing/checkout	Returns a provider checkout URL to redirect to
Top up	POST /billing/topup	Returns a provider payment URL
Attach / remove add-on	POST /billing/addons, DELETE /billing/addons/:id	Debits the wallet atomically; 402 if the balance is too low
Payment method	GET /billing/portal	Hosted card portal (409 for local rails that have none)
Cancel	POST /billing/cancel	Marks the subscription to cancel at period end

Provider adapters cover Polar (Merchant of Record), Stripe and PayPal (direct), and the VNPay / Alipay / WeChat Pay local rails. Entitlement only ever changes in one place — the webhook handler — so a subscription activation, renewal, cancellation, or wallet top-up is applied idempotently no matter how many times the provider retries the delivery.

Renewals split by rail: card-on-file subscriptions (Polar / Stripe) are renewed by the provider’s own webhook, while wallet-funded local rails are auto-debited from your balance by a background worker each period — if the wallet can’t cover the renewal the subscription goes past due until you top up.

Quota enforcement

Your plan sets your VPS quota, enforced at the API layer when an agent connects — not on the box. Over quota, the control plane refuses the agent’s WebSocket and it retries in about an hour; existing servers keep running. Feature gates (Docker, staging, offsite backup, share-host, …) are checked server-side by tier. See Tiers & quotas for the full flow and the offline grace.

API & automation

Billing is a control-plane feature, not something on a single box, so the on-box mz CLI does not apply here. Programmatic access to your account (including billing reads) is available via the MZPanel API on the Max plan — see the API reference.

Gotchas & troubleshooting

• “Payments are not enabled yet.” If no provider is configured for your region, the page shows an inline banner and checkout is blocked. In that state, a wallet top-up is credited optimistically and labelled “(demo)” so you can preview the flow — it is not a real charge. Real top-ups only happen once a provider is live.
• Sites usage reads 0. The current-plan card intentionally shows only VPS and Operators gauges; a fleet-wide site count isn’t summed here yet, so don’t read the billing page as your site inventory — use Sites for that.
• No “Manage payment method” button on a local rail. VNPay / Alipay / WeChat Pay have no hosted card portal. Opening the portal returns a clear message; renew these by topping up your wallet instead of managing a card.
• A plan change looks like it didn’t apply. Checkout redirects out to the provider; your new tier only lands after the provider’s webhook confirms payment. Give it a moment and refresh — the overview reads from MZPanel’s DB, updated by that webhook.
• Cancelling keeps your servers running. Cancellation only affects the control-plane subscription. Your VPSes and sites keep serving traffic; you just can’t add new ones above the Free quota until you’re back under the limit.

Related

• Tiers & quotas — what each plan unlocks and how limits are enforced.
• API reference — programmatic access (Max plan).
• Dashboard tour — where Billing sits in the account menu.