> ## Documentation Index > Fetch the complete documentation index at: https://docs.itoflow.ai/llms.txt > Use this file to discover all available pages before exploring further. # Billing and credits > Choose a plan and the model your agents use, see what each run cost in credits, set a spending cap, and manage invoices and your subscription. Itoflow never switches your model silently. > [!TIP] > > **The easiest way: ask your AI assistant.** With [Itoflow MCP](https://docs.itoflow.ai/mcp/install.md) connected to Claude or Codex, paste: > > ```text theme={null} > Use Itoflow to show my usage this billing period, my remaining credits, and > which models my plan includes. > ``` > > > [card] [Open in Claude](https://claude.ai/new?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20show%20my%20usage%20this%20billing%20period%2C%20my%20remaining%20credits%2C%20and%20which%20models%20my%20plan%20includes.) > > > > Start this in Claude with the Itoflow plugin. > > > [card] [Open in ChatGPT](https://chatgpt.com/?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20show%20my%20usage%20this%20billing%20period%2C%20my%20remaining%20credits%2C%20and%20which%20models%20my%20plan%20includes.) > > > > Start this in ChatGPT with the Itoflow plugin. > > Using another client? Copy the prompt with the button on the code block. > > No tokens or code needed. You can also do this in the [Itoflow app](https://app.itoflow.ai/account/billing). The rest of this page covers the HTTP API. Itoflow charges for AI usage in **credits**. Each plan includes a monthly amount of usage; paid plans can also allow pay-as-you-go overage up to a spending cap you set. Invoices and balances are in **money**. Keep the two apart: credits are not cents. ```mermaid theme={null} flowchart LR Usage[Agent runs] --> Credits[Credits used] Plan[Plan] --> Credits Credits --> Cap[Overage up to your spending cap] Cap --> Billing[Invoices and balance] ``` ## Plans There are three plan families: Free, Pro and Max. Pro and Max include monthly AI usage worth more than their fee, and the same advanced models. Free includes a small allowance on the basic model. Prices and allowances are on the [pricing page](https://itoflow.ai/pricing) and in `GET /pricing/catalog`; read them from there rather than hard-coding them. **How usage is counted.** Each model call in an agent run costs what the model provider charges, times a usage multiplier. For example, at a multiplier of 1.25, a provider charge of 1 US dollar uses 1.25 dollars of your included usage. Both the agent and its independent review count. Included usage resets each month and doesn't roll over. Pay-as-you-go overage, when enabled, isn't subsidized the way included usage is. News searches and matching news to companies or monitor mandates do not spend your AI credits. Requests use the existing rate limits, and judging has time limits. Agent runs that read or summarize news still spend credits. **Bonus credits** are one-off grants. They last across months until used, revoked or expired. Each month uses included credits first, then bonus credits. Bonus credits don't give access to paid models. ## Models and plans Chats, monitors and strategies each save their own model choice. Pro and Max unlock advanced models while their subscription is active or in a trial and the current billing period is valid. Trials use the plan's existing usage allowance and budget checks. A fusion mode chooses the main agent and its independent Guardian together: | Key | Main agent | Guardian | Plans | | - | - | - | - | | `fusion_deep` | Sol | Opus | Pro and Max | | `fusion_quick` | Terra | Sonnet | Pro and Max | | `fusion_light` | Luna | Haiku | All plans | You can also choose a single model. Its Guardian uses that same model: | Key | Model | Plans | | - | - | - | | `luna` | GPT-6 Luna | All plans | | `sol61` | GPT-6.1 Sol | Pro and Max | | `terra61` | GPT-6.1 Terra | Pro and Max | | `sol` | GPT-6 Sol | Pro and Max | | `astra` | GPT-6 Astra | Pro and Max | | `sonnet55` | Claude Sonnet 5.5 | Pro and Max | | `opus55` | Claude Opus 5.5 | Pro and Max | Haiku reviews fusion runs; you cannot choose it as a single main agent. Read `GET /pricing/model-access` for the current choices. Its `models` entries add `short_name` and `main_agent`; only entries with `main_agent: true` can run on their own. Its `modes` entries name both model keys and give their combined `requires_paid` and `enabled` values. The returned `default_mode` is your plan's default for new resources. The older `default_model` field keeps its single-model meaning. Pass a returned choice key, never a provider's model version. ```mermaid theme={null} flowchart LR Choice[Saved choice] --> Snapshot[Run settings] Snapshot --> Main[Main agent] Snapshot --> Guardian[Guardian review] Main --> Rates[Model rates] Guardian --> Rates ``` * **Default.** Without a choice, a new chat, monitor or strategy uses your plan's default mode. Existing ones keep their saved choice. * **Pinned settings.** Both agents keep the models and reasoning settings admitted when the run starts, including retries and recovery. Changing a saved choice affects the next run. * **Provider and cost.** Fusion reviews send review context to Anthropic, including on Free. Each agent bills at its own model's rates, including context-length tiers. Prompt-cache writes use their cache lifetime. * **No silent switching.** If your paid plan ends, saved paid choices stay selected, but new runs stop with “Choose the Free model or upgrade” until you change the choice or upgrade. * A payment method, a balance, or bonus credits don't give access to paid choices. A [connected ChatGPT subscription](https://docs.itoflow.ai/features/chat.md#connect-your-own-chatgpt-subscription) unlocks single OpenAI models for Chat and monitors. Fusion modes always use your plan's access and Itoflow keys for both agents; they never use that connection. Strategies use plan access. If Itoflow can't read your plan, it returns `503` rather than assume you're on Free. ## Read usage and billing | Endpoint | Returns | | - | - | | `GET /pricing/catalog` | Plans, prices, included usage and models. No token needed. | | `GET /pricing/config` | Public billing settings. No token needed. | | `GET /pricing/model-access` | Models your account can use | | `GET /account/billing-costs` | This period's usage, limits and spending cap | | `GET /pricing/billing-summary` | Balance, unpaid invoices, subscription and amount owed | | `GET /pricing/invoices` | Invoices | | `GET /pricing/customer-balance` | Account balance and currency | | `GET /pricing/credit-tiers` | Credit tiers | | `POST /pricing/get-plans` | Plans and the overage rate | | `POST /pricing/get-subscription` | Your subscription | `get-subscription` creates a Free subscription if you don't have one yet, so it isn't a pure read. Call these endpoints from your server. Browsers block calls from other websites, even to the public catalog. ### Usage this period `GET /account/billing-costs` returns `period_start`, `period_end`, `total_credits_used`, `invocation_count` and token counts. Depending on your plan, it also returns: | Field | Meaning | | - | - | | `credits_included`, `bonus_credits`, `effective_credits_included` | Credits available this period | | `credits_remaining`, `overage_credits`, `percentage_used` | Where you are now | | `current_tier` | `free`, `included` or `overage` | | `is_within_limit`, `block_reason` | Whether new runs can start, and if not, why | `block_reason` is one of `free_tier_exhausted`, `spending_cap_reached`, `subscription_inactive` or `not_configured`. ### Money fields In the billing summary: | Field | Meaning | | - | - | | `balance`, `balanceCurrency` | Balance in cents and its currency. A negative balance is credit in your favor. | | `unpaidInvoices` | Count, total due and invoice details | | `subscription` | Status, period end, whether it cancels at period end, plan and credits; may be `null` | | `upcomingInvoice` | Next invoice amount and period; may be `null` | | `totalOwed` | Amount owed, in cents | | `hasPaymentIssue` | Whether a payment needs attention | Fields ending in `_cents`, invoice amounts and the cent fields above are whole cents. Some dates are Unix timestamps and others ISO strings; check each field's schema. ## Change your plan 1. Read `GET /pricing/catalog`. Each entry has a `price_id`, a plan `key` (`free`, `pro` or `max`) and an `offer_key` such as `pro100` or `pro300`. Pick by `price_id`: one `key` can have several offers. 2. `POST /pricing/preview-upgrade` with the `planId` shows what the change will cost. Show it to the account owner. 3. `POST /pricing/update-subscription` with the `planId` and the `catalogRevision` you showed. If the terms changed in between, step 3 returns `409 PLAN_TERMS_CHANGED`. Read the catalog again and confirm the new terms. A successful response means the change was accepted; follow the payment status to see that it was paid. Paid upgrades keep the current renewal date. The preview and payment invoice cover the remaining-period price difference. Your purchased plan and included usage change only after payment succeeds. A nonempty `subscription.pending_update` means the requested upgrade still awaits payment; it does not grant its allowance. ```mermaid theme={null} flowchart LR Request[Request upgrade] --> Pending[One pending invoice, purchased plan stays active] Pending --> Paid[Payment succeeds] Paid --> Active[New plan and allowance apply] Pending --> Expired[Payment expires, purchased plan stays active] ``` Repeat the same target to resume the existing pending invoice. Choosing another plan while it is pending returns `409 SUBSCRIPTION_PAYMENT_PENDING`. An earlier unpaid plan-change invoice returns `409 SUBSCRIPTION_PAYMENT_REQUIRED`; resolve that invoice before changing plans. A simultaneous request returns `409 SUBSCRIPTION_UPDATE_IN_PROGRESS`; refresh before retrying. `409 SUBSCRIPTION_UPDATE_UNSUPPORTED` means the subscription cannot use this payment-gated flow, for example when it collects invoices manually. For saved Link, confirm through `POST /pricing/confirm-payment`. If it returns `requires_action` with no redirect URL, call Stripe.js `handleNextAction({clientSecret})` with the owned invoice's confirmation secret. Follow an explicit redirect URL when one is present and return to `/account/billing`. `processing` remains pending. After `succeeded`, refresh `POST /pricing/get-subscription` and check the paid invoice and effective plan before announcing that the upgrade is active. Billing shows the pending upgrade and a **Complete payment** action after reload. If your subscription uses a price no longer in the catalog, you keep its terms. Read them from your subscription and billing summary. Payment methods, the billing portal (`POST /pricing/billing-portal`) and payment confirmation have their own endpoints; see the reference. ## Spending cap and refunds `POST /pricing/spending-cap` with `spending_cap_cents` sets a monthly overage cap in cents. `0` or `null` turns overage off. A positive cap needs a paid plan; on Free it returns `PAID_PLAN_REQUIRED`. `POST /pricing/refund-balance` asks for a refund of your credit balance. It can return `NO_CREDIT_BALANCE`, `NO_REFUNDABLE_PAYMENT` or `REFUND_IN_PROGRESS`. ## ChatGPT subscription usage With a [connected ChatGPT subscription](https://docs.itoflow.ai/features/chat.md#connect-your-own-chatgpt-subscription), OpenAI model calls that your subscription pays for use no Itoflow credits. Other calls in the same run still do, and your spending cap still applies. When the subscription can't be used, for example because it needs reconnecting or has hit its own limit, calls run on Itoflow credits at normal rates. A run on a paid model that only your subscription gave you stops instead of being charged. An independent review that the subscription refuses part-way finishes on credits, so the work is still checked. Itoflow records who paid for each call when it happens. Reconnecting or disconnecting later doesn't change past records. To see what you were charged, check your usage, not the connection status or what the model says about itself. If a charge looks wrong, email [support@itoflow.ai](mailto:support@itoflow.ai) with the chat or task it belongs to. To see your usage, invoices and plan in the app, open [Billing](https://app.itoflow.ai/account/billing). See the [billing](https://docs.itoflow.ai/api-reference/coverage.md#billing) and [account](https://docs.itoflow.ai/api-reference/coverage.md#account) endpoint references for every field. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.