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 into Matrix billing entitlements. The platform allows runtime proxying and provisioning while the subscription is active, and during a three-day grace period after a recoverable billing failure. After grace ends, Matrix blocks runtime proxying and new provisioning without deleting owner data or machines.

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.

Add-ons

Extra machines, storage, and future Hetzner-backed capacity should be modeled as separate Stripe Prices. Matrix maps those prices to entitlement fields such as additional runtime slots or allowed machine capacity. 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, plus add-on Prices as needed. Configure promotion codes in Stripe for launch discounts, time-limited percentage discounts, pay-X-get-Y campaigns, and referrals.

Required platform environment:

Webhook events to subscribe:

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

Stripe Checkout uses automatic tax and promotion codes. The customer portal should remain enabled so users can update payment methods, apply supported coupons, and manage subscriptions through Stripe-hosted flows.