# /iblai-vibe-pricing

> Mirrored from [`iblai/vibe`](https://github.com/iblai/vibe) · [`skills/billing/iblai-vibe-pricing/SKILL.md`](https://github.com/iblai/vibe/blob/main/skills/billing/iblai-vibe-pricing/SKILL.md). This page is generated — edit it in the repository, not here.

> **First time here?** If `iblai.env` has no `ARCHITECTURE=`, run `/iblai-vibe-start` first (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:

1. **How does ibl.ai charge *me* (the organization)?**
2. **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](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/skill-setup.md).
> Terms: [docs/glossary.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/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`](https://github.com/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:

1. **Are you charging for the app as a whole, or for things inside it?** Whole app → **B**. Things inside → **C**.
2. **Do you want to keep 100 % on your own Stripe account, with no webhooks to host?** → **B**.
3. **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](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/skills/billing/iblai-api-billing/SKILL.md) |
| 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](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/skills/billing/iblai-api-spend-caps/SKILL.md) |
| 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](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/skills/analytics/iblai-api-analytics/SKILL.md) |

Details of every endpoint and error code for rails B and C:
[`references/rails.md`](https://github.com/iblai/vibe/blob/main/skills/billing/iblai-vibe-pricing/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)