Billing

Hyponema’s billing is Stripe-backed. Tenants pick a plan, optionally toggle bring-your-own provider keys, and pay only the Hyponema platform fee — provider spend (LLM / STT / TTS / PSTN) flows straight to your own provider accounts.

This guide covers the operator side. Pricing details live on the marketing site.

How the split works

Hyponema runs in a strict BYO API keys model:

• LLM, STT, TTS, and email provider keys are stored encrypted in your workspace.
• At runtime, Hyponema resolves the call against your keys.
• The provider bills you directly.
• Hyponema bills you only for the platform fee tier defined by your plan.

Some pieces (PSTN minutes when you use Hyponema-provisioned numbers, knowledge-base storage, and scheduled callbacks) still meter through Hyponema and roll up into the invoice.

Plans and entitlements

Plans expose entitlements like agents_limit, kb_storage_bytes_limit, kb_max_upload_bytes_limit, MCP-enabled, and similar caps. List the active catalog:

curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/billing/plans" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

The current plan slug is returned as current_plan_slug. Per-tenant entitlements come from:

curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/billing/entitlements" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

When you hit a limit, the API responds 402 Payment Required with a code like quota-exceeded-agents or quota-exceeded-kb-storage.

Upgrade through Stripe Checkout

Open Billing → Plans in the dashboard and pick a plan + billing interval. Hyponema mints a Stripe Checkout session and redirects.

If you wire this in your own product instead:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/billing/checkout-session" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_slug": "pro",
    "billing_interval": "monthly",
    "success_url": "https://app.example.com/billing/done",
    "cancel_url":  "https://app.example.com/billing/canceled"
  }'

The success_url and cancel_url must originate from an allowed frontend origin. Unknown plan + interval combinations return 404.

Manage subscription through the Stripe portal

POST /workspaces/{ws}/billing/portal mints a Stripe Customer Portal URL for the tenant’s Stripe customer. Use it to swap payment methods, download invoices, or cancel:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/billing/portal" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://app.example.com/settings/billing" }'

BYO toggle

Tenants on plans that support BYO can toggle whether to use their own provider keys or Hyponema-managed credentials (where available). Flip the flag from Billing → BYO, or:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/billing/byo-toggle" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

When BYO is on, the runtime requires the relevant provider credential to be present in the workspace; sessions fail with a clear MissingProviderCredentialError otherwise.

Usage and metering

Per-turn cost events accumulate into usage meters. A background worker flushes the rollup; the dashboard shows current-period usage on Billing → Usage, and:

curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/billing/usage" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

Stripe invoice events flow into Hyponema through a webhook, update the subscription row, and emit invoice.paid / invoice.failed outbound webhooks for tenants who subscribe.

What you see when things go wrong

Symptom	Likely cause
quota-exceeded-agents	Hit agents_limit for your plan.
quota-exceeded-kb-storage	KB storage cap exceeded. Delete or archive older sources.
quota-exceeded-kb-upload-size	Single upload exceeds kb_max_upload_bytes_limit.
stripe-not-configured	Host or workspace missing Stripe credentials. Contact Hyponema.
no-stripe-customer	Tenant has no associated Stripe customer yet — run Checkout first.
billing-return-url-not-allowed	success_url / cancel_url origin is not in the allowed frontend list.

Operational guidance

• Keep test and production workspaces on separate plans. Test traffic shouldn’t drain your production credits.
• Watch the usage page after publishing a persona change — token-heavy prompts can move spend materially.
• Rotate provider keys without downtime by adding the new key, swapping the workspace credential, and revoking the old key after a short overlap.