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

The first primary computer on a Matrix account can use Stripe's native 3-day trial for subscriptions. With the product default, Checkout sends trial_period_days: 3, requires a card, and charges $0 initially. Stripe automatically attempts the selected recurring price when the trial ends unless the user cancels first. Coupons remain independent marketing discounts and never implement the trial.

The offer is limited to one trial per Matrix account and excludes previous subscribers, additional computers, and subsequent subscriptions. The persisted checkout attempt records the eligibility decision and duration so an idempotent retry sends identical Stripe parameters. The MATRIX_CARD_TRIALS_ENABLED rollout flag controls only new offers; disabling it does not alter trials already underway.

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 trialing or active. A first post-trial payment failure gates access immediately and schedules VPS suspension 24 hours later. Established paid renewal failures retain the three-day grace period. Successful recovery cancels a pending suspension or wakes an already stopped machine. Suspension powers the VPS off but does not delete its disk or owner data.

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 Stripe Prices for the three plans. New first-time and additional-computer Checkout sessions use those Prices. Keep existing yearly Price IDs configured only so legacy annual subscriptions remain recognizable. 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
• customer.subscription.trial_will_end
• checkout.session.completed
• checkout.session.expired
• invoice.paid
• invoice.payment_failed

Enable Stripe's trial-ending customer email as well. Stripe emits customer.subscription.trial_will_end three days before the deadline; Matrix uses that verified event for its reminder telemetry.

Stripe Checkout uses automatic tax, promotion codes, and an idempotency key derived from the persisted checkout attempt. Eligible trial Checkout also sets payment_method_types: ['card'] and payment_method_collection: always; immediate-payment sessions keep Stripe's normal dynamic-method behavior. Subscription and invoice webhooks remain the authorization source of truth; a Checkout redirect never grants access. The customer portal should remain enabled so users can update payment methods, apply supported coupons, and manage existing subscriptions through Stripe-hosted flows.

Billing FAQ

How long is the Matrix OS trial?

Eligible first primary computers receive a three-day, card-required trial. Stripe charges the selected monthly price when the trial ends unless the user cancels first.

Can one Matrix account receive more than one trial?

No. The offer is limited to one trial per Matrix account. Previous subscribers, additional computers, and later subscriptions are not eligible.

What happens after a payment failure?

A first post-trial payment failure gates access immediately and schedules VPS suspension 24 hours later. An established paid renewal receives a three-day grace period. Suspension powers off the VPS without deleting its disk or owner data.

Can customers manage billing without contacting support?

Yes. Stripe's customer portal lets customers update payment methods, apply supported coupons, and manage existing subscriptions. Purchasing an additional computer still uses a new Checkout session.