First time here? If
iblai.envhas noARCHITECTURE=, run/iblai-vibe-startfirst (four questions; two minutes) — it decides single-org / multi-org / headless and who signs in, and every skill reads the answer.
One page that answers two questions before any billing skill is run:
- How does ibl.ai charge me (the organization)?
- How do I charge my users — and which rail?
Read this, pick a rail with the table in §2, then open the skill that wires it. This skill builds nothing itself.
Common setup (brand, conventions, env files, verification): see docs/skill-setup.md. Terms: docs/glossary.md.
1. How the organization is charged
The platform meters usage in credits, not seats. Everything below is managed in os.ibl.ai (Admin mode → settings → Billing) and readable from your app with the SDK / REST surface in §4.
| Concept | What it means for you | Where |
|---|---|---|
| Credits | A prepaid, rechargeable balance. Agent usage (LLM calls, RAG, voice, …) draws it down. When it is spent, agents pause — the balance is a hard ceiling you set. | Billing → Plan & Credits (Add Credits) |
| Plan | Free → Trial → Premium. Free/Trial show an Upgrade button (Stripe checkout); Premium shows its renewal date. |
Billing → Plan & Credits |
| Payment method | Stored in Stripe via Manage Billing (Stripe portal). Required before Add Credits and Auto Recharge work. | Billing → Plan & Credits |
| Auto Recharge | Opt-in. Threshold, recharge amount, and an optional spending limit (defaults when enabled empty: $5 threshold / $16 recharge; spending limit Unlimited unless set). |
Billing → Manage Usage |
| Your own LLM keys | Admins add provider keys (OpenAI, Anthropic, Google, Azure per-deployment, …) under Integrations → LLMs. Agents can then choose those models. Costs attributed to each provider/model appear in Analytics → Costs. | Integrations → LLMs; /iblai-vibe-agent-llm |
| Spend caps | Admin ceilings on LLM cost at three scopes — the whole org, one agent, one user on one agent — per day/week/month/year, enforced as Block Requests (HTTP 429, the chat is refused) or Alert Only; near-limit alerts at 80 % and 95 % by default. The tightest applicable cap governs. |
Billing → Spend Limits / Agent Limits; /iblai-vibe-billing, /iblai-vibe-agent-billing |
IBLAI_API_KEY as an LLM key |
Your Platform API Token is also a standard OpenAI-style key on https://asgi.data.<domain>/api/ai-mentor/orgs/<org>/v1 (Authorization: Bearer). Calls made with it are your org's usage. Server-side only. |
/iblai-vibe-ops-init, iblai-api-inference |
Rule of thumb for a new app: set an org-wide monthly spend cap in Alert Only mode on day one, then tighten to Block once you know the real number (the Spend Limits tab shows actual spend this month and all time before you set anything).
2. Charging your users — pick a rail
| A · Platform credits | B · App paywall (your Stripe) | C · Item monetization (Stripe Connect) | |
|---|---|---|---|
| What is sold | ibl.ai credits / plan tier to the org's own members | Entry to the whole app — one-time or subscription | Access to specific items: an agent, course, program, pathway, or custom item, with pricing tiers |
| Whose Stripe | ibl.ai's | Yours — linked from the app with Connect with Stripe, or a restricted key stored on the org as the stripe integration credential (never typed into a chat) |
Your Stripe Connect Express account, ibl.ai-managed |
| Commission | — | None | ibl.ai commission per sale |
| Webhooks | — | None (verified polling by the platform) | Webhook-reconciled subscriptions |
| Buyer sees | CreditBalance widget + Stripe pricing page |
Your /paywall page → Stripe's form in a modal → into the app |
PaywallModal per item, guest/public buy, PurchasesTab in Profile |
| Admin sees | Billing tab | /paywall/setup: free / one-time / monthly, then Connect with Stripe |
MonetizationTab in Account: paywall config, prices, subscribers, revenue |
| Needs an operator flag | show_paywall |
none | enable_monetization |
| Choose when | Your org resells ibl.ai usage to its own admins/trial users | "One app, one price, my customers" (the iblai/vibe-agent model) |
A marketplace of agents/courses with per-item prices, trials, subscriptions, and revenue reporting |
| Skill | /iblai-vibe-credit, /iblai-vibe-billing |
/iblai-vibe-monetization-app-paywall |
/iblai-vibe-monetization (family index) |
Decision in three questions:
- Are you charging for the app as a whole, or for things inside it? Whole app → B. Things inside → C.
- Do you want to keep 100 % on your own Stripe account, with no webhooks to host? → B.
- Do you need subscriptions per item, trials per item, guest checkout, or revenue/subscriber dashboards? → C.
A is not a way to charge your end users for your product; it is how an org
tops up its own credits.
3. What the platform must have before money flows
| Rail | Prerequisite | How to check |
|---|---|---|
| A | show_paywall on the org |
JSON.parse(localStorage.tenants).find(t => t.key === org).show_paywall |
| B | A Stripe source on the org — an account linked with Connect with Stripe (the admin does it at /paywall/setup), or a stripe integration credential holding a restricted key and its publishable key; a backend that serves …/providers/stripe/connect/ |
GET $CONNECT → source is connected or key with a non-empty publishable_key; 404 old backend ($CONNECT defined in /iblai-vibe-monetization-app-paywall Step 1) |
| C | enable_monetization on the org; Connect Express onboarding complete (is_ready_for_payments) |
/iblai-vibe-monetization-onboard |
Flags are set by an ibl.ai operator — there is no in-app toggle. If a flag is off, none of that rail's UI renders even when the code is correct.
4. Reading money from your app
SDK hooks (verified in @iblai/data-layer 1.13.x): useGetCreditTransactionsQuery,
useGetTenantSpendCapQuery, useGetAgentSpendCapQuery, useGetUserSpendCapQuery,
useGetSpendCapStatusQuery (safe to show end users: zone + percent, never dollars),
useDeleteTenantSpendCapMutation / …AgentSpendCap… / …UserSpendCap….
Components: CreditBalance, BillingTab (both @iblai/iblai-js/web-containers).
REST (server-side, Authorization: Api-Token $IBLAI_API_KEY):
| Need | Call | Reference |
|---|---|---|
| Org credit account | GET /dm/api/billing/account/?platform_key={org} |
iblai-api-billing |
| Transactions | GET /dm/api/billing/transactions/?platform_key={org} |
same |
| Org cap | PUT/GET/DELETE /dm/api/ai-mentor/orgs/{org}/spend-caps/tenant/ |
iblai-api-spend-caps |
| A user's cap status (safe to show end users) | GET /dm/api/ai-mentor/orgs/{org}/spend-caps/status/{user_id}/[?mentor=] |
same |
| Costs by provider / model / user | GET /dm/api/analytics/financial/?platform_key={org}&metric=total_costs&date_filter=30d |
iblai-api-analytics |
Details of every endpoint and error code for rails B and C:
references/rails.md.
Related skills
/iblai-vibe-credit— the navbar credit widget (rail A)/iblai-vibe-billing— org Billing page: plan, credits, spend limits, agent limits/iblai-vibe-agent-billing— one agent's cap and per-user caps/iblai-vibe-monetization-app-paywall— rail B end to end/iblai-vibe-monetization— rail C family index/iblai-vibe-admin— who may see billing (admins only)