Plans
The Plans page is headed Plans, subtitled "Compare available plans and switch when your usage changes".
How plans work
Your organization is always on a plan. The default is Pay as you go: no monthly fee, no included tokens, and every request charged at standard list rates.
A paid plan defines some combination of:
- Monthly fee: a fixed recurring charge.
- Included usage: either a token allowance per model, or a dollar amount of usage, depending on the plan's quota model.
- Overage pricing: the rates that apply once the included allowance is used up.
- Rate limits: the request and token throughput that comes with the plan.
Audio usage is always pay as you go. Speech-to-text and text-to-speech hold no plan quota and no commitment allowance in either direction. They are never drawn from an included allowance and never consume one. Speech-to-text is metered per second of input audio, rounded up, with an optional per-model minimum billed duration. Text-to-speech is priced on the input text, per 1,000,000 characters, with a limit of 4096 characters per request. See Speech to Text and Text to Speech.
Billing period
Plan periods are anchored to the date your plan was assigned, not to the calendar month. A plan that started on the 15th runs from the 15th to the 15th. Anchors on the 29th–31st adjust automatically in shorter months.
This anchored period is what governs included-allowance renewal and overage. See Billing for how the period is displayed and for the UTC boundary rules.
The Renews date beside your current plan is the end of the billing period that is open right now — the same period your closing invoice is drafted over and the same one your spend cap is measured against. Every surface that names a period names that one.
Two consequences worth knowing:
- A period that opened part-way through a day starts at that instant, not at midnight. When a plan change, a billing-mode change or a commitment renewal splits a period, the successor begins the moment it was applied. The API reports that exact instant; the portal shows its date.
- Your included allowance and your consumption are always read off the same period. At a renewal boundary you will not see the new period's allowance beside the previous period's usage.
/api/v1/usage/current reports the open billing periodThe usage endpoint reports the billing period that is open now — the same one /api/v1/plan/current and the Billing page name, starting at the exact instant that period opened rather than at midnight or on the 1st. It used to report a fixed calendar month, which diverged for every organization not anchored on the 1st and could sum consumption across a period boundary. See Usage.
The plan you are on
The Current plan chip at the top of the page reports your organization's actual assignment, read from your own plan record rather than matched against the public catalog. That distinction matters when your plan was set up for you:
| Your situation | What the page shows |
|---|---|
| A public plan | The plan name and fee. Its row in the ladder carries the Current plan badge. |
| A private or negotiated plan | Your plan's real name and real monthly fee, with the note "Not in the comparison below". The ladder lists public plans only, so no row is badged. |
| Billed under a commitment | Your plan is named, with the note "Billed under your commitment" — usage for the period is drawn against the commitment contract, so the plan's monthly fee is not charged. |
| No plan at all | The default Pay as you go plan, whose row carries the Default badge. |
Both notes carry a hint explaining themselves and pointing at Billing, which is where a private plan's included usage and charges for the current period are reported.
Because the page knows your real fee, plan changes are classified against it: a plan cheaper than your private plan is offered as a downgrade rather than an upgrade, and the Cancel your plan block is offered to private-plan organizations too.
The ladder is built from the public catalog, so a plan set up for your organization is not in it and the page does not invent a row for it. What that plan grants you this period is on Billing.
Comparing plans
The catalog is a ladder: one row per plan, five fixed columns. Whatever the catalog holds, it is always five columns wide, so no plan is pushed off the side of the page and nothing scrolls sideways to be read.
A two-option toggle above the ladder switches the criteria set:
- Token-based plans: plans that sell you a token allowance.
- Consumption-based plans: plans that sell you a dollar amount of usage.
Both kinds coexist on the platform, and the toggle decides which set of rows you are looking at. The page opens on the tab matching your own plan's quota model. If a plan you expect to see is missing, check the other tab.
What each row shows
| Column | Contents |
|---|---|
| Plan | The name, a Current plan or Default badge where applicable, and a short tagline |
| Monthly fee | The fee, or Free |
| Included tokens / Included usage | On the Token-based tab, how many models the plan bundles tokens for and the first of them; on the Consumption-based tab, the dollar amount of usage included. A plan that bundles nothing says so in words: "No bundled tokens on this plan" |
| Overusage rates / Rates after budget | The cheapest published rate, as "from {price} / 1M in", and how many models are priced. "No per-model rates published" where none are |
| Actions | The call to action, Per-model detail, and Compare |
A figure is never printed without its unit: the rate column carries / 1M beside the price rather than relying on a column heading to supply it.
Per-model detail
Per-model detail expands the row into the full per-model breakdown: every model the plan includes tokens for, every model it prices, and, under "Not on this plan:", the models in the catalog that this plan does not cover at all. One row is open at a time.
A plan whose quota is a single pool shared by several models states that pool's allowance against each member model, under the Shared token pool grant label. The figure is the size of the one pool, not an allowance per model: three lines reading 100M mean 100M shared between the three, not 300M.
Comparing plans side by side
Compare on a row adds that plan to a comparison tray at the foot of the page. Pick a second and the tray opens by itself; up to three plans can be compared at once, and a full tray says "Remove one to swap in another" rather than silently ignoring a fourth pick. Remove takes a plan back out, and the tray can be hidden and reopened without losing the selection.
The tray compares the same criteria as the ladder, laid out as columns so you can read one plan against another. Switching the Token-based / Consumption-based toggle closes the tray, because the two tabs describe different criteria and a mixed comparison would be meaningless.
Changing your plan
Whichever action you are offered, the switch is never immediate: it happens when a human approves it, when the billing period turns, or when your card payment goes through. Only organization owners and admins are offered an action at all.
The call to action in each column reflects your situation. In priority order:
| State | What you see |
|---|---|
| Already on it | A Current plan pill |
| Enterprise tier | Contact sales |
| Managed organization | Managed by your account manager |
| Same price as yours | This plan costs the same as your current plan. Contact support to switch. |
| A paid upgrade you can pay for by card, and you are owner or admin | Upgrade |
| A downgrade or a cancellation, and you are owner or admin | Switch plan |
| Any other eligible change, and you are owner or admin | Request change |
| Eligible, but you are a member | Contact your organization owner to change plans. |
The label is not decoration: it tells you which of the three routes below your change takes, and the confirmation dialog behind it says the same thing in a sentence. Upgrade appears only where your platform takes card payment for plan upgrades and a card rail is configured on it; where either is missing, the same change is offered as Request change and is reviewed by a person instead.
A change is still blocked, whatever the label says, while another order is open, while your organization is on a commitment contract, or while the portal cannot read your plan-change status.
Confirming a change
The confirmation dialog states what will happen before you commit, and the two cases differ.
Downgrading: the change is scheduled straight away and takes effect at the end of the current billing period. Your current plan stays active until then, and you can withdraw the change up to that point. No human review is involved: a downgrade is approved automatically and simply waits for the period boundary.
Upgrading: what happens depends on whether the plan is paid and on whether your platform takes payment for plan changes up front:
- If it does, the dialog names the money: "You'll pay {amount} now. That opens a new billing period and covers its first month; after that the plan is {fee}/month. Your plan changes as soon as the payment goes through." The order goes to awaiting payment, and the banner on this page links you into checkout. Nobody is reviewing anything at that point — the change is waiting on you.
- If it does not, the portal sends a plan change request, the order is parked for review, and your current plan stays active until it is approved.
Both amounts in that sentence come from the same quote the money panel below is built from. If the quote could not be produced, the dialog drops the figures rather than guessing at them and says what happens without naming an amount.
It does not finish the one you are in. The payment covers the first month of the new period, and the date the dialog and checkout give you for your next charge is that new period's renewal date — not the end date of the period you are leaving.
What the change costs, before you confirm
Both confirmation dialogs — the plan switch and the cancellation — carry a money panel under that sentence, stating what the change does to your balance:
| Line | Meaning |
|---|---|
| Takes effect | When it is approved, or the date of your next period boundary for a scheduled change. |
| New plan price | The target plan's list monthly fee. |
| Charged when it takes effect / Charged today | What you are actually charged when the change is applied. |
| Credit for your current plan | The unused part of your current plan's fee, returned to your balance. |
| Due now / Back to your balance | The net of the two. |
| From {date} | The full monthly fee from your next renewal onwards. |
Two hints beside the panel explain why the charge is less than a full month, and why money comes back.
A mid-cycle upgrade is prorated on both sides. The unused part of the plan you are leaving comes back to you as credit, and the plan you are joining is charged only for the part of the cycle it actually covers — the same arithmetic read in both directions:
credit = old plan fee × the part of the cycle not yet used
charged = new plan fee × the part of the cycle not yet used
A change that takes effect exactly on a cycle boundary is charged the full monthly fee, because there is nothing to prorate. Where a fee was prorated, your billing document states the basis: the proration factor, the full monthly price and the cycle it was applied to, so that factor times that price reads back as the amount charged. See Billing.
They are worked out against where you are in your billing period at the moment the dialog opens. If the change is approved later, both amounts shrink slightly, in your favour. The figures that count are the ones on your billing documents.
If the platform cannot work out what a change costs, the dialog says so and Confirm still works — the request is reviewed before anything is charged, and you can withdraw it until then. The dialog never falls back to quoting the list price instead.
A downgrade or a cancellation shows the same panel with the boundary date, Charged today $0.00, and the real figure on the renewal line, so "nothing is charged now" is something you read rather than infer from silence.
Paying for an upgrade
Only a paid upgrade can be gated behind payment. Free plans, downgrades and cancellations never take money at request time and are never held up by it.
While an order is awaiting payment:
- The banner carries a link into checkout, so you can pay when you are ready. See Billing for how checkout works.
- Checkout shows a fixed amount, not a field you type into. The figure was worked out and frozen on the order when you asked for the change, so nothing on the payment page can charge you a different number: "You are paying {amount} now for the first month of a new billing period, which starts as soon as the payment goes through." Under it, "Your next {plan} charge is {full} on {date}."
- A deadline is shown where the platform publishes one: "Complete this payment by {deadline}. If it is not paid by then, the plan change is cancelled and nothing is charged."
- If the order carries no amount, the page refuses to take money rather than inventing a figure. It says so, states that nothing has been charged and that your plan change is still in place, and asks you to contact us to complete it. That is a fault on our side, not something you can fix by paying.
- Paying returns you to a confirmation that the change is on its way. It can take a moment to be applied, and nothing more is needed from you.
- Your organization's billing details must be complete before a card payment can be taken. If they are not, you are asked to fill them in as part of the payment rather than being sent away to another page.
- You can withdraw the order at any time. Withdrawing leaves you on your current plan and changes nothing about the current period.
- If you leave checkout without paying, the order is cancelled automatically at the deadline and your current plan is untouched. Nothing is charged. If the banner is gone, the order expired; request the change again.
Whether it is awaiting payment, awaiting review or scheduled, you can only have one plan change outstanding. Withdraw the open one before requesting a different plan.
When a change is blocked
A change the platform cannot apply ends as blocked. The banner carries the platform's own reason for refusing, word for word, so support and your account contact are looking at the same sentence you are.
Blocked is a final state: the order does not resume on its own. Once the reason is resolved, request the change again.
Cancelling your plan
A Cancel your plan block offers to "Move to pay-as-you-go at the end of your current billing period." Like a downgrade, a cancellation is approved automatically and scheduled for the period boundary rather than taking effect immediately, and it can be withdrawn until then.
Withdrawing a request
While a request or a scheduled change is outstanding, a banner carries a Withdraw button. Withdrawing cancels the pending change and leaves you on your current plan; nothing about the current period changes.
After the request is decided
When your open request is decided, a banner reports the outcome in place of the pending one:
| Outcome | What the banner says |
|---|---|
| Plan change applied | Your switch was approved on the stated date and is active now, with a link into Billing to see what you were charged. |
| Plan change declined | Names the plan and the date you asked, states that nothing was charged, and prints the reviewer's own reason verbatim under "Reason given:". A refused request is never silent. |
| Plan change withdrawn | The request you withdrew, with the plan and the date. Nothing was charged and your plan is unchanged. |
The outcome banner covers your most recent order only, and it steps aside while a newer request is open — an in-flight request is the news then. A change the platform could not apply has its own banner instead; see When a change is blocked.
A Recent plan changes card lists your last five orders: from → to, the date, the status — Awaiting review, Awaiting payment, Being applied, Scheduled, Applied, Declined, Withdrawn or Could not be applied — and the reviewer's reason on a refusal.
Applying a change touches two systems in step: the one that keeps your billing period and the one that holds your plan assignment. If the second half does not complete, the platform now detects the mismatch and finishes it by itself, usually within the hour, so your account cannot be left billed for one plan while entitled to another. Retries are keyed to your original request, so an interrupted change is never charged twice. If you are told a change could not be confirmed, give it a while and reload the page before requesting it again; contact support if the two still disagree.
Banners
| Banner | Meaning |
|---|---|
| Your plan is managed by the platform | Your plan is set by your account manager. No self-service action is available. |
| Scheduled plan change | An approved change is waiting for the end of the current billing period. |
| Plan change in progress | A change is being applied right now. |
| Pending plan change request | An upgrade request is awaiting review. Carries a Withdraw button. One request at a time. |
| Awaiting payment | Your upgrade needs paying before it can be applied. Links into checkout and carries a Withdraw button. See Paying for an upgrade. |
| Plan change blocked | The platform could not apply the change, and the banner states its reason verbatim. Terminal; request the change again once the reason is addressed. |
| Plan changes are paused | Your organization is on a commitment contract; plan moves go through your account contact. |
| Plan change applied | Your most recent request was approved and is active. Links into Billing. |
| Plan change declined | Your most recent request was refused, with the reviewer's reason quoted. Nothing was charged. |
| Plan change withdrawn | You withdrew your most recent request. Nothing was charged. |
If the platform cannot check your plan-change status, the page fails closed and shows a banner saying so rather than offering an action that might not work. Retry, or contact support if it persists.
Tracking what you have used
Plan consumption is reported on the Billing page, not here. Your accrued usage for the period, your included-allowance meters, the value of your usage at list price, and your spend limits all live there.
See Billing.
Whether you get those allowance meters depends on whether your plan grants quota, not on whether it charges a fee. A plan with a $0 monthly fee and a real token allowance — the shape used for pilots, trials and negotiated arrangements — gets the full surface: included tokens, what you have used against them, and the per-model overage, exactly as a paid plan does. The only difference is that no Plan fee line is drawn, because there is no fee to state. An account with no allowance at all to meter has none of those sections and sees accrued usage and usage value instead.
You also receive email alerts when an included allowance reaches 80% and 100%. Alerts are latched per model group rather than per individual model, so a group with several models raises one alert rather than one per model.
API Reference
Plan endpoints require JWT authentication.
Get your current plan
curl https://api.bulutistan.ai/api/v1/plan/current \
-H "Authorization: Bearer <your-jwt-token>"
Which one you get is decided by a field called billing_basis, not by the plan's quota mode.
billing_basisofbudgetreturns a deliberately minimal, percent-only payload: the quota mode, the plan, the period, a utilization fraction capped at 1.0, and a flag for whether there is any included usage. It carries no token counts and no dollar amounts at all. This is intentional: a budget plan's cost internals are not exposed here, and their absence is not a fault.- Every other basis returns the full payload: per-model groups and meters, the plan fee, uncommitted usage cost and estimated charges.
Write clients that branch on billing_basis rather than assuming a single shape.
The period block reports the billing period that is open now: start and end as UTC dates, and start_at / end_at as the exact half-open instants, so a period that began part-way through a day reports the time it actually began rather than midnight. It is the same period the closing invoice is drafted over, and the allowance and consumption figures beside it are both read off it. A tenant with no open period at all falls back to the plan anniversary.
If your organization is on pay as you go there is no plan to report, and the response reflects that rather than describing an allowance.
Where the full payload reports an estimated charge, treat it as an estimate: its uncommitted-usage component is carried at list value rather than at your resolved price, so an organization with negotiated rates will see a figure that reads slightly high. For the amount that actually applies, use the Billing page.
List available plans
curl https://api.bulutistan.ai/api/v1/plans \
-H "Authorization: Bearer <your-jwt-token>"
Returns the active public plans together with their included-allowance and overage-pricing summaries, plus the flags the portal uses to decide which call to action to render.
Each included-allowance and overage row names the model it applies to and, where the platform can tell, carries serviceable: true when your organization can call that model right now, false when it cannot. The key is absent when serviceability cannot be determined — read absence as unknown, never as false. A row is never dropped for being unserviceable: what a plan includes does not change because a model is temporarily unavailable.
A quota granted as a pool shared by several models emits one row per model you are allowed to see, all carrying the same group_id and a shared_model_count. The allowance on those rows is the size of the one pool, so collapse rows sharing a group_id into a single line rather than adding them up. A group that grants nothing is omitted entirely, and the plan reads as metered with no bundle — which is what it is.
Quote a plan change
Returns what a change would cost before you order it. It writes nothing and reserves nothing.
curl "https://api.bulutistan.ai/api/v1/plan/change-quote?plan_id=<target-plan-id>&change_type=upgrade" \
-H "Authorization: Bearer <your-jwt-token>"
change_type is one of upgrade, downgrade or cancel.
The response names both plans, the open period and how much of it has elapsed, then the two money legs: charge_now (the amount, the full monthly fee, the proration factor and whether it was prorated at all), credit_now, the net, and at_renewal. Every amount is a decimal string — parse it as a decimal, not a float, or you will lose cents.
estimate is always true, and it is not decoration: both legs are computed against the instant you asked, and both move as the period elapses. A downgrade or a cancellation answers effective_immediately: false with effective_at at the period boundary, zeroes on both immediate legs, and the real figure on at_renewal.
Request a plan change
Owner or admin only. Managed organizations receive 403.
curl -X POST https://api.bulutistan.ai/api/v1/plan/orders \
-H "Authorization: Bearer <your-jwt-token>" \
-H "Content-Type: application/json" \
-d '{ "plan_id": "<target-plan-id>", "change_type": "upgrade" }'
change_type is one of upgrade, downgrade or cancel, and defaults to upgrade. It is validated against the direction of the fee change, so declaring an upgrade to a cheaper plan is rejected with 422. For cancel, omit plan_id; the service resolves the default plan itself and rejects any other target. Unknown fields in the body are rejected.
A successful call answers 201. An upgrade is parked as requested for review, or as pending_payment where the platform takes payment for paid upgrades up front. A downgrade or cancel is auto-approved and moves to scheduled, taking effect at the end of the open billing period; it stays withdrawable until then.
Order statuses
requested · pending_payment · approving · scheduled · active · cancelled · rejected · blocked
pending_payment— the order is waiting for you to pay for it. It can be withdrawn, and it is cancelled automatically if the payment is never completed.blocked— terminal. The order carries ablock_reasonexplaining why the change could not be applied.
An order that has not reached a final state counts as open, and only one order may be open at a time. pending_payment is one of them, so a parked, unpaid order blocks any other plan change until it is paid, withdrawn or expired.
Withdraw a request
curl -X POST https://api.bulutistan.ai/api/v1/plan/orders/<order-id>/withdraw \
-H "Authorization: Bearer <your-jwt-token>"
List your plan change requests
curl https://api.bulutistan.ai/api/v1/plan/orders \
-H "Authorization: Bearer <your-jwt-token>"
Returns your organization's plan change orders with their status and decision dates.