Billing
Stripe-hosted runtime plans, entitlements, and operator setup.
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
| Plan | Monthly | Annual | Default machine | Included machines |
|---|---|---|---|---|
| Starter | $14 | $140 | Hetzner CPX22, 2 vCPU, 4 GB RAM, 80 GB disk | 1 |
| Builder | $19 | $190 | Hetzner CPX32, 4 vCPU, 8 GB RAM, 160 GB disk | 1 |
| Max | $49 | $490 | Hetzner CPX52, 12 vCPU, 24 GB RAM, 480 GB disk | 1 |
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:
| Variable | Notes |
|---|---|
MATRIX_BILLING_PROVIDER=stripe or MATRIX_STRIPE_BILLING_ENABLED=true | Enables Stripe-backed entitlement enforcement. |
STRIPE_SECRET_KEY | Restricted key with checkout, portal, customer, subscription, and webhook needs. |
STRIPE_WEBHOOK_SECRET | Webhook signing secret for /billing/webhooks/stripe. |
STRIPE_PRICE_MATRIX_STARTER_MONTHLY / STRIPE_PRICE_MATRIX_STARTER_ANNUAL | Starter Price IDs. |
STRIPE_PRICE_MATRIX_BUILDER_MONTHLY / STRIPE_PRICE_MATRIX_BUILDER_ANNUAL | Builder Price IDs. |
STRIPE_PRICE_MATRIX_MAX_MONTHLY / STRIPE_PRICE_MATRIX_MAX_ANNUAL | Max Price IDs. |
STRIPE_PRICE_EXTRA_RUNTIME_MONTHLY / STRIPE_PRICE_EXTRA_RUNTIME_ANNUAL | Optional extra-machine add-on Price IDs. |
PLATFORM_PUBLIC_URL | Used to build checkout and portal return URLs. |
Production Cloud Run deployments read the Price IDs from Secret Manager. The required secret names are:
| Environment variable | Secret Manager name |
|---|---|
STRIPE_PRICE_MATRIX_STARTER_MONTHLY | stripe-price-matrix-starter-monthly |
STRIPE_PRICE_MATRIX_STARTER_ANNUAL | stripe-price-matrix-starter-annual |
STRIPE_PRICE_MATRIX_BUILDER_MONTHLY | stripe-price-matrix-builder-monthly |
STRIPE_PRICE_MATRIX_BUILDER_ANNUAL | stripe-price-matrix-builder-annual |
STRIPE_PRICE_MATRIX_MAX_MONTHLY | stripe-price-matrix-max-monthly |
STRIPE_PRICE_MATRIX_MAX_ANNUAL | stripe-price-matrix-max-annual |
STRIPE_PRICE_EXTRA_RUNTIME_MONTHLY | stripe-price-extra-runtime-monthly |
STRIPE_PRICE_EXTRA_RUNTIME_ANNUAL | stripe-price-extra-runtime-annual |
The signed-in pre-VPS path defaults to Builder monthly checkout. Missing price secret access should block deployment rather than letting new users reach a broken billing gate.
Webhook events to subscribe:
customer.subscription.createdcustomer.subscription.updatedcustomer.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.
How is this guide?