How billing works

This page explains the billing machine: what a plan attaches to, how the trial decides when an app runs, when each of the four meters ticks, and what the spending cap actually guarantees. For the plan table, current prices, and where to click, see Plans & billing — this page covers the mechanics underneath it.

Plans attach to apps, payment attaches to a wallet

A plan is a property of one app, not of your account. Your account — or each workspace, which has its own separate wallet — pays one Stripe subscription per paid app, plus that app’s metered usage. There is no account-wide plan ladder: each additional paid app simply carries its own bill, so the number of paid apps you can create is unbounded. One flat operational ceiling (50 apps per wallet, counting archived apps until their 30-day deletion completes) exists as an abuse guard, not a tier — hitting it is a support conversation, never an upgrade prompt.

Exactly one app per wallet runs without a plan: the trial slot.

The trial state machine

Every app is in one of three trial states, and every surface — the deploy gate, the console banner, guuey apps get — derives the state from the same rule, so they cannot disagree:

• none — the app has an honoring paid subscription, or its trial clock hasn’t been stamped yet. The clock is stamped by the platform at its first sight of the app’s live deployment, within minutes of the first successful deploy.
• active — the app resolves to the free tier and is inside its 7-day window. It runs with the Free limits.
• expired — the window has ended and the app still has no plan. The platform pauses it: the pod scales to zero, and a redeploy is refused with 409 TRIAL_EXPIRED (a redeploy would only bring up a pod for the platform to scale back down). Conversation history, settings, configuration and domains are all kept.

Putting a plan on a paused app resumes it automatically — the platform detects the honoring subscription on its next pass and brings the pod back, no redeploy needed. The warning emails, what the paused chat surface shows, and where the trial end date is printed are on Plans & billing.

The clock is stamped for every live app, paid or not — a paid app just resolves to none while its subscription is honored. This matters when a plan lapses (below).

The slot is blocked-until-checkout, not created-then-must-pay. While any plan-less app exists on your wallet — running, paused, or archived inside its 30-day deletion window — creating another app is refused with a 409 that names the occupying app and links its billing page. This is deliberate: checkout binds a subscription to an app that already exists, so an app created first and “owing” payment later would have nothing to ever pause it. Once the occupying app takes a plan (or finishes deletion), your next create succeeds and starts its own 7-day trial.

Which plan an app gets

An app’s effective tier comes from its subscription’s Stripe status. The statuses that keep the paid tier are a closed list: active, trialing, and past_due. Any other status — canceled, unpaid, or anything Stripe invents later — makes the app plan-less: it resolves to the free tier at once for limits and cap purposes (Free limits, a $0 spending cap, no overage). The platform deliberately fails toward less free service rather than toward unmetered paid service.

Free limits are the transitional step, not the destination. Because every app’s 7-day trial clock started at its first live deploy, a plan-less app past that clock is expired — the next sweep pauses it exactly as an unpaid trial app is paused. Only an app whose lapse lands inside its original 7-day window keeps serving on Free limits: a multi-pod or larger-than-xs deployment is brought down to one xs pod once the platform has confirmed the lapse across consecutive checks, and the app pauses when the window closes. Resubscribing at any point resumes it, no redeploy.

The four meters

Paid apps meter four quantities. Each ticks at a different moment:

Meter	Ticks when	What the plan includes
Generations	Your agent produces a generative-UI render through mcp.ggui.ai	A monthly render allowance
Managed LLM	The model runs on a Guuey-supplied key	A monthly dollar credit
Pod unit-hours	A pod beyond the first runs for an hour, weighted by size	The first always-on pod
Storage	The app holds bytes above its included allowance, per GiB per hour	An always-included byte allowance

Details worth relying on:

• Generations come in three kinds — a fresh (cold) render, a cached blueprint reuse, and a bring-your-own-key render — each with its own overage rate (cold is the most expensive; the others bill substantially less). Your included allowance is allocated across kinds most-expensive-first: the free quota covers your cold renders before your cheap ones, which is the customer-favorable reading when counts carry no timestamps.
• Managed-LLM usage is priced from provider token rates plus a platform margin and drawn against the plan’s dollar credit; only usage past the credit meters. The Free (trial) tier carries no monthly managed-LLM credit. Instead, a new account gets a small one-time managed-LLM trial credit on its wallet, and a Free app’s managed-model turns draw on it; once that lifetime credit is spent, a Free app’s managed-LLM requests are refused with 429 MANAGED_SPEND_CAP (the message names the credit and what was spent) until the app takes a plan. Bring-your-own-key models are unaffected — see BYOK.
• Pod time is billable-only at the source: the always-on first pod never enters the counter. Extra pods multiply by their size’s billing units (xs = 1 up to xl = 16 — table in Plans & billing).
• The storage allowance is a standing entitlement, not a monthly grant: your app may hold its included bytes at every moment of the month, so the free GiB-hours grow with the period. Only the time-integral above that line bills. Durable app storage is rolling out per environment and has not yet reached production; until it reaches your app, files are pod-local and the storage meter has nothing above the allowance to bill (see the note on Plans & billing).

All four counters reset with the calendar month (UTC) — billing cycles are anchored to month starts, so “this month’s usage” means the same thing on every surface.

The spending cap

Every paid app has a spending cap — the plan default, adjustable per app (see where billing is managed). What it guarantees:

• The cap bounds the usage-driven meters: generations, managed LLM, and storage. Their metered overage in a month cannot exceed the cap.
• Pod-hours bill outside the cap. Pod spend is bounded by something you configure explicitly — the extra pods you allow with --max-pods, at their size’s billing units times the flat unit-hour rate (the same rate on every plan — see Plans & billing) — not by usage that can run away on its own. The cap exists for the unbounded class; your worst-case month is base fee + cap + the pod spend you configured.
• Hard mode (the default): once cap-relevant spend reaches the cap, requests that would spend more are refused — a generation request with 429 QUOTA_EXCEEDED (its message says when other metered overage shrank the month’s render allowance), a managed-LLM request with 429 MANAGED_SPEND_CAP — and a multi-pod app is clamped back to one pod so no further pod capacity rides on a capped app. Serving resumes when the month rolls over or you raise the cap.
• Soft mode: serving continues past the cap and the overage bills.
• A $0 cap means no overage at all on the usage-driven meters — the Free tier’s standing state, and available on any plan. Setting the cap to unlimited is an explicit act; no default is uncapped.
• You get an in-app notice and an email at 80% and 100% of the cap, quoting the same cap-relevant figure the enforcement compares. Pure pod spend never triggers these notices, because it never counts toward the cap.

Storage gets one extra, physical guarantee: an app with no cap headroom cannot write past its allowance — the write fails with a disk-full error instead of accruing a bill. On a paid app with headroom, writes past the allowance succeed and meter.

One formula everywhere

Every surface that states a money number — the usage panel on the app’s billing page, the 80%/100% notices, the enforcement gates, and the Stripe invoice — computes it from the same shared formula over the same counters. The figure the panel shows is the figure the invoice bills and the figure the cap gates on; a metered invoice is never your first notice of a number no page showed you. Rounding is customer-favorable throughout: cents meters are floored, and a corrupted or backwards-running counter reads as zero rather than ever minting negative or inflated usage.

Plan changes mid-cycle

• Upgrades apply immediately, with a prorated credit/charge on the next invoice.
• Downgrades are scheduled for the end of the billing period — you keep the tier you already paid for until the cycle ends. The queued change is visible on the app’s billing page, and re-selecting your current plan before it lands cancels it.
• A mid-cycle tier change draws a metering boundary: usage before the change settles under the old tier’s rates and allowances, and the period after it starts with the new tier’s full allowance — deliberately customer-favorable rather than prorated.
• Cancelling a plan is graceful: the subscription runs to period end, accrued usage is flushed onto the final invoice, and the app then becomes plan-less — Free limits, then paused once it is past its original 7-day trial clock, as described in Which plan an app gets. Deleting an app ends its subscription immediately with a final invoice for the usage tail.

When a payment fails

A failed payment does not take your app down. It enters a grace state while Stripe retries on its own schedule:

• The app keeps serving, clamped to one pod.
• The spending cap is enforced in hard mode at no more than the plan default — a raised or unlimited cap is suspended for the duration, but a cap you lowered below the default stays in force: you asked for less exposure, not more.
• You get an email and a banner naming both restrictions and the fix path (update the payment method — a wallet-level action). Paying the invoice clears the grace state and restores your configured cap and pod count.

Failure behavior

The billing system’s two halves fail in opposite directions, on purpose:

• Serving fails open. If a billing record cannot be read at request time, your agent answers anyway — a billing-plane outage never takes a running agent down. Enforcement resumes when reads do.
• Creation fails closed. Every app you create costs real infrastructure the moment it exists, so the app-creation and deploy gates refuse when their billing reads fail, rather than minting resources nobody is paying for.