Billing & Credits
How users and teams are billed — VAG Stripe passthrough, the credit wallet, who pays, and spending limits.
Every request through Hypery is billed to a team — never an individual user directly. This page explains exactly which team pays, and the three ways that team can be charged.
Who is billed (team resolution)
Billing always debits the team resolved from whoever authenticated the request. The app id is carried for attribution only — a developer is never billed for a user's activity unless they deliberately use their own API key.
Resolution order for the active team (see resolveBillingTeam):
activeOrganizationId (OAuth) → session organization → x-hypery-active-organization-id header → personal team.
Switching your active organization changes which team is billed. In connected apps (e.g. Nihmbus), the org you pick in the app's workspace switcher is the team that pays.
Billing modes
A team's usage is charged in one of three modes. The mode is a sysadmin
setting (per-app billingMode, with a global BILLING_MODE override and a
BILLING_MODE_DEFAULT fallback). It is not an app-developer setting.
VAG passthrough (default)
This is true metered billing with no credit wallet and no held funds.
On each successful request, Hypery forwards two headers to the Vercel AI Gateway:
stripe-customer-id— the billed team's Stripe customerstripe-restricted-access-key— a Stripe restricted key (meter-event write only)
Vercel AI Gateway then emits two Stripe meter events per successful response — one for input tokens, one for output tokens — including the customer id, model, and token type. Stripe bills the customer directly against the price you configured on the meter. Hypery deducts no credits and applies no credit markup in this mode; your Stripe price defines the rate and your margin.
Requirements:
BILLING_MODE_DEFAULT=vag_passthrough(or per-appbillingMode)STRIPE_RESTRICTED_ACCESS_KEYset on the platform- The billed team has a Stripe customer on file (
billing.stripeCustomerId)
Fail-closed: if the restricted key or the team's Stripe customer is missing, the
request is rejected (402 VAG_BILLING_NOT_CONFIGURED) rather than served
un-metered.
See Vercel's
Stripe Billing for AI Gateway
for the meter setup: a Stripe billing meter with event name token-billing-tokens
and model + token_type dimension keys, plus a restricted key (rk_…) with
write Billing meter events permission. Vercel emits two events per successful
response (input + output tokens). Metering is non-blocking on Vercel's side — and
critically, if either header is missing the request is served without billing,
which is why Hypery fails closed before the request when billing identity is absent.
Metered (credit wallet)
The legacy pay-as-you-go wallet, modeled on the Vercel AI Gateway pattern: the
team keeps a small credit balance, every request deducts at provider list
price × platform markup, and when the balance crosses a threshold a saved card
is auto-charged to refill it (auto top-up). No card → PAYMENT_METHOD_REQUIRED.
Declined → PAYMENT_DECLINED. Card capture uses Stripe-hosted Checkout — no card
data touches Hypery.
Auto top-up is idempotent and rate-limited (a short cooldown) so concurrent
requests never double-charge. Defaults come from METERED_TOPUP_THRESHOLD /
METERED_TOPUP_AMOUNT unless the team configures its own.
Prepaid (credit wallet)
Same credit wallet, but manual top-up only. If a request would push the
balance below zero it is rejected with INSUFFICIENT_CREDITS before it reaches
the provider. Auto top-up runs only if the team opts in.
Credits (metered / prepaid only)
Credits are the unit of the internal wallet, priced at 100 credits = $1. They are added only by purchase, auto top-up, admin bonus, or refund — never earned from usage — and cannot be cashed out. Provider cost is passed through at list price and multiplied by the platform markup; that is Hypery's margin.
Credits do not apply in VAG passthrough mode — there is no wallet; Stripe meters the usage directly.
Top up (metered / prepaid)
- Go to Settings → Billing.
- Click Top up and choose an amount or enter a custom value.
- Pay with a saved method or add one under Settings → Billing → Add payment method.
- Credit appears in the team balance immediately.
How a request is billed (all modes)
- Resolve the paying team from the credential (see above).
- Enforce model-access rules and spending limits (chat proxy + media routes; invoice-item paths run the same app/team cap preflight even when the credit ledger is skipped).
- VAG passthrough (token APIs — chat, embeddings via Vercel): attach Stripe headers → provider → Stripe meters the usage. VAG passthrough (non-token — TTS, STT, realtime mint, Browserbase fees): Stripe invoice item on the team's customer after success (never free). Non-Vercel upstream under vag: downgraded to the credit ledger so usage cannot run unmetered. Metered/prepaid: reserve credits → provider → finalize at actual usage (refund the over-estimate).
- Record the request (model, tokens, latency, cost) for analytics. Failed or rejected requests are never billed.
Realtime WebRTC after mint is settled by the app via
POST /api/v1/usage/charge (billing:charge).
Break spend down by team, app, key, or provider on the Analytics pages. Transaction history (top-ups, deductions, refunds) is under Settings → Billing in the wallet modes.
Spending limits
Independent of billing mode, you can cap spend before a request reaches a provider — per team, per app (including per-OAuth-app), and per key. See Spending limits. Connected apps get a default per-app OAuth cap on first authorization; raise it under Authorized Apps.