Billing

Matrix OS hosted runtime billing is backed by Stripe Billing. Clerk remains the identity provider, but subscription checkout, coupons, tax, the customer portal, and webhooks are handled by Stripe.

Hosted Runtime Plans

There are no hosted runtime trials. A signed-in user can explore account surfaces, but a hosted Matrix computer requires active billing before provisioning.

Entitlements

Stripe subscription webhooks project every subscription independently into billing_subscriptions. Each row carries the Clerk user id and runtime slot from signed Stripe metadata. Provisioning and routing authorize that exact (clerk_user_id, runtime_slot) projection rather than a user-wide slot count. billing_entitlements remains a derived coarse summary for legacy and account-level views; it is not the authorization source for one computer.

The platform allows runtime proxying and provisioning while that computer's subscription is active, and during a three-day grace period after a recoverable billing failure. After grace ends, Matrix blocks only that runtime slot without deleting owner data or machines. Other computers and subscriptions remain unaffected.

Internal engineers can receive a production or staging override entitlement for testing plan changes without paying. Overrides are audit records with an expiry or revocation path; they must not delete, downgrade, or recreate a user's existing machines.

Machine resize uses the same entitlement allowlist as provisioning. A running VPS may move only to a server type currently allowed by the effective entitlement. The resize path changes the Hetzner server type in place with disk growth disabled, so billing downgrades can move CPU/RAM down without replacing the machine or deleting owner data.

Additional Computers

Every additional computer purchases one standard Starter, Builder, or Max subscription through Stripe Checkout under the user's existing Stripe customer. Checkout and subscription metadata include clerk_user_id, matrix_runtime_slot, and the selected region. The Customer Portal manages existing subscriptions but does not purchase another computer.

Do not configure an extra-runtime Price or a focused Customer Portal subscription-update flow. Storage and future Hetzner-backed add-ons remain separate product decisions. Do not hardcode Hetzner prices into Stripe plan names; keep provider cost data in the Matrix runtime catalog so Hetzner price changes can be updated without renaming public plans.

Stripe Setup

Create recurring monthly and yearly Stripe Prices for the three plans. The same six Prices are used for first-time and additional-computer Checkout. Configure promotion codes in Stripe for launch discounts, time-limited percentage discounts, pay-X-get-Y campaigns, and referrals.

Required platform environment:

Production Cloud Run deployments read the Price IDs from Secret Manager. The required secret names are:

Webhook events to subscribe:

• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted

Stripe Checkout uses automatic tax, promotion codes, and an idempotency key derived from the persisted checkout attempt. The customer portal should remain enabled so users can update payment methods, apply supported coupons, and manage existing subscriptions through Stripe-hosted flows.