Matrix OSMatrix OS
Deployment

Billing

Understand Stripe-hosted Matrix runtime plans, trial eligibility, entitlements, payment failures, and the operator configuration used for billing.

Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.

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

PlanMonthly list priceIncluded machines
Starter$201
Builder$1001
Max$2001

The first primary computer on a Matrix account can use Stripe's native 14-day trial for subscriptions. For the advertised 14-day offer, configure MATRIX_CARD_TRIAL_DAYS=14; Checkout then sends trial_period_days: 14, requires a card, and charges $0 initially. The runtime source fallback remains trial_period_days: 3 when no duration override is configured. 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:

VariableNotes
MATRIX_BILLING_PROVIDER=stripe or MATRIX_STRIPE_BILLING_ENABLED=trueEnables Stripe-backed entitlement enforcement.
MATRIX_CARD_TRIALS_ENABLED=trueEnables the card-required trial for eligible first primary computers.
MATRIX_CARD_TRIAL_DAYS=14Matches the advertised 14-day offer. The runtime source fallback is 3 days; the accepted range is 1 through 30.
STRIPE_SECRET_KEYRestricted key with checkout, portal, customer, subscription, and webhook needs.
STRIPE_WEBHOOK_SECRETWebhook signing secret for /billing/webhooks/stripe.
STRIPE_PRICE_MATRIX_STARTER_MONTHLY / STRIPE_PRICE_MATRIX_STARTER_ANNUALStarter Price IDs.
STRIPE_PRICE_MATRIX_BUILDER_MONTHLY / STRIPE_PRICE_MATRIX_BUILDER_ANNUALBuilder Price IDs.
STRIPE_PRICE_MATRIX_MAX_MONTHLY / STRIPE_PRICE_MATRIX_MAX_ANNUALMax Price IDs.
PLATFORM_PUBLIC_URLUsed to build checkout and portal return URLs.

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

Environment variableSecret Manager name
STRIPE_PRICE_MATRIX_STARTER_MONTHLYstripe-price-matrix-starter-monthly
STRIPE_PRICE_MATRIX_STARTER_ANNUALstripe-price-matrix-starter-annual
STRIPE_PRICE_MATRIX_BUILDER_MONTHLYstripe-price-matrix-builder-monthly
STRIPE_PRICE_MATRIX_BUILDER_ANNUALstripe-price-matrix-builder-annual
STRIPE_PRICE_MATRIX_MAX_MONTHLYstripe-price-matrix-max-monthly
STRIPE_PRICE_MATRIX_MAX_ANNUALstripe-price-matrix-max-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.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 fourteen-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.

Purchase and Trial Measurement

Hosted checkout uses the Matrix landing GTM container (GTM-5D8ZT4HF). Stripe returns a session_id token; the authenticated platform verifies ownership, final payment status and the purchased Price before returning tracking data. The browser then adds currency, plan, interval, amount, transaction_id and trial to the success URL. Those query fields are for inspection; GTM conversions should use the verified Data Layer event.

A completed free trial emits trial_started, with zero paid amount. A positive, confirmed checkout emits purchase. GA4 ecommerce.value is discounted item revenue excluding tax; amount_paid is the customer's total including tax. Adaptive Pricing uses the customer's presentment currency and amount. Its localized tax allocation is proportional because Stripe exposes a localized total rather than a separate localized tax breakdown.

The first positive invoice.paid for a subscription also queues a server purchase. A subscription that began with a trial carries trial_converted=true. This reaches GA4 even when the app is closed. Renewals do not create another acquisition conversion. Browser and server purchases share the Stripe invoice transaction ID and original GA client ID, allowing GA4 to deduplicate the purchase. Browser receipts and removal of the session token prevent refreshes from firing another event.

Configure these platform-only environment variables:

  • GOOGLE_TAG_MANAGER_ID: the shared GTM container ID.
  • GOOGLE_ANALYTICS_MEASUREMENT_ID: the Matrix GA4 web stream, G-JJS1LJGEBS.
  • GOOGLE_ANALYTICS_API_SECRET: a private GA4 Measurement Protocol secret. Store it in the project credential vault and deployment secret store; never use a NEXT_PUBLIC_ variable.

Reuse the existing landing Google tag (Matrix, AW-18486552087), with the Matrix GA4 stream connected as another destination. In GTM, use a GA4 event tag with measurement ID G-JJS1LJGEBS, event name {{Event}}, Send ecommerce data → Data Layer, and a Custom Event trigger matching ^(purchase|trial_started)$ with regex matching enabled. Register plan, billing_interval and trial_converted as event dimensions when needed. For direct Google Ads tracking, map ecommerce.value, ecommerce.currency and ecommerce.transaction_id to the conversion tag. Use one primary purchase conversion route for bidding; importing GA4 purchases and counting a direct Ads purchase as another primary conversion would overcount.

The landing page shares its explicit, expiring consent choice with Matrix subdomains through a secure cookie. Without accepted consent and the existing GA client cookie at checkout, the platform does not send background Measurement Protocol events. New subscriptions preserve that consent/identity snapshot in Stripe metadata; old subscriptions are not retroactively attributed. Later consent expiry prevents server delivery. The server records the paid invoice independently of the browser return and retries temporary delivery failures. Configure background tracking before launching campaigns, and validate it in GA4 DebugView and GTM Preview.

Deploy the platform/app-shell service and updated customer VPS shell bundle together. A host bundle alone does not update the pre-VPS checkout surface. Deploy the landing consent update as well. Test a paid checkout, a trial, a first post-trial charge with no browser open, refreshes, discounts, tax, local currency and duplicate webhooks before counting the purchase as a primary Ads conversion.

Interpreting campaign journeys

The website records public page views only after optional analytics consent. A marketing funnel should start from the actual landing URL, including blog articles, rather than assuming every campaign enters at the homepage. marketing_landing_viewed records the current public page and its category after consent; repeated consent notifications do not repeat that mounted page event. Auth, admin, dashboard and tool pages remain excluded from this custom event.

Check recorded landing visitors separately from CTA clicks, account creation, trial starts and collected revenue. An advertising-platform click is not a confirmed browser page load or a unique visitor. A rejected consent choice, blocked request or closed page can leave no observed visit. Missing analytics records must remain unknown rather than being reported as zero real conversions. Test journeys should use separate campaign tags and be excluded from customer results.

How is this guide?

On this page