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):
x-hypery-active-organization-id header (explicit picker) → activeOrganizationId
(OAuth) → session organization → personal team. App-owner exclusion applies to
OAuth/session claims only — an explicit header that selects the app-owning team
still bills that team when the caller is an active member.
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.
Locked production rate: $0.000015 USD per token ($15 / MTok). Invoice
math is tokens × 0.000015. Non-token invoice items (audio / usage-charge) use
a separate 2× list markup (VAG_INVOICE_MARKUP), not this per-token price.
Requirements:
BILLING_MODE_DEFAULT=vag_passthrough(or per-appbillingMode)STRIPE_RESTRICTED_ACCESS_KEY(orSTRIPE_SECRET_KEY) set on the platformSTRIPE_METERED_PRICE_IDset to a recurring metered price in the same Stripe mode as the key- The billed team has a Stripe customer (
billing.stripeCustomerId) and a default payment method
Fail-closed: if the Stripe key, metered price/subscription, or a payment method is
missing, the request is rejected (402) rather than served un-metered or
uncollectible.
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.
In VAG passthrough mode a team's credits (and app subscription grants) are
spent first; Stripe meters only what they don't cover, on the team's card.
A team without a card pays from its credits alone — never asked for a card
while credits remain. With nothing left to pay with (no card, no credits, no
app grants) it gets PAYMENT_METHOD_REQUIRED, as before ("add a card or buy
credits"); a team that still has some credits or grants, but not enough for the
request, gets INSUFFICIENT_CREDITS. Long answers are shortened to what the
balance covers rather than refused. A few things can only be billed to a card
(realtime voice sessions, video generation, and models the catalog can't price
on the credit ledger); without one they return PAYMENT_METHOD_REQUIRED.
Paying from credits only (x-hypery-payment-source)
An app can ask, per request, that it be paid from credits only:
POST /api/v1/ai/language-model
Authorization: Bearer <user's OAuth token>
x-hypery-payment-source: creditsWith credits, Hypery pays for the request from the team's app grants and
credit balance and never charges a card for it — even when the team has one
on file: no gateway metering, no invoice for an overflow, no auto top-up. When
the credits run out the request returns 402 INSUFFICIENT_CREDITS, and the error
carries no link to buy credits elsewhere. Anything that can only be billed to
a card (realtime sessions, video, unpriced models) returns
402 PAYMENT_METHOD_REQUIRED, and Hypery's own top-up endpoints
(/api/wallet/topup, /api/wallet/topup/checkout) refuse the request with
403 CREDITS_ONLY.
Any other value is treated as default. The header only ever narrows how a
request may be paid; it can't make Hypery charge anyone it otherwise wouldn't.
Browsers may send it cross-origin (it is in every Hypery CORS allowlist).
Apps in the App Store or Google Play must sell digital goods (subscriptions,
credits, pay-as-you-go usage) through the store's own billing. Send
x-hypery-payment-source: credits on every AI request from your store
builds, so usage there is paid from what the user already has — credits bought
through your In-App Purchases, or bought on the web — and never billed to a
card they saved elsewhere. Keep sending nothing (or default) from your web and
direct-download builds. Show your own In-App Purchase offer when you get
INSUFFICIENT_CREDITS, not a link to Hypery.
How to send it is up to the app: set it wherever you build the request (your server's call to Hypery, or the browser's). If your app calls Hypery from its own server on the user's behalf, forward the decision from the client — for example, the client tells your server it is a store build and your server adds the header.
App Store In-App Purchases themselves (plans and credit packs) are applied with the App Store endpoints.
Top up
- Go to Settings → Billing → Add credits.
- Choose an amount or enter a custom value.
- Pay with your saved card, or on Stripe's checkout page with Apple Pay, Google Pay or a card — no saved card needed (up to $500 at a time).
- Credit appears in the team balance as soon as the payment succeeds.
Credits bought this way can be spent in every app on Hypery, including apps a user runs from the App Store (see above).
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 sessions, 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 voice sessions (WebSocket, via the Vercel AI Gateway) are billed by
duration: the app reports the length to
POST /api/v1/realtime/sessions/{id}/settle
on disconnect (credits first, the rest invoiced). Other third-party costs are charged at 1× the
reported amount 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.