Billing
Billing covers your plan and the nodes it includes, subscription, invoices, payment methods and usage, and what you may host and at what price. It also manages the products you hold and buy, the Jaah AI wallet (its balance, top-ups, auto-recharge and ledger) and the monthly budgets on projects and groups.
List budgets
Lists the organization's monthly budgets, projects first then groups, each with this month's Jaah AI spend (UTC), the whole percent spent and its state: `ok` below 80%, `warn` from 80%, `held` from 100%, when new tasks of the project, or launched by the group's members, wait. Requires the Org Owner or Org Admin role and Budgets on the plan (else 403).
Delete budget
Removes a project's or group's monthly budget, so it is unlimited again; removing none is a no-op. Returns 204 with no body. Requires the Org Owner or Org Admin role and Budgets on the plan (else 403).
Get budget
Returns one project's or group's monthly budget (`null` = unlimited) and what it spent this month. `scope` is `project` or `group`. Requires the Org Owner or Org Admin role and Budgets on the plan (else 403).
Set budget
Sets a project's or group's monthly budget in micro-dollars (`monthly_usd_micros`, above 0, at most $1,000,000) and returns it. A raise past this month's spend lets waiting tasks dispatch on the next pass. Requires the Org Owner or Org Admin role and Budgets on the plan (else 403).
Get billing
Returns the organization's billing state: whether billing is connected, its billing details, subscription, any checkout in progress, the next charge and open billing notices. When the payment provider is unreachable, `details` is empty and the next charge reports `available: false`. Requires the Org Owner or Org Admin role.
Cancel subscription
Schedules a downgrade to the Trial plan at the end of the current billing period, undoable until then; an unpaid plan ends at once and an unfinished first payment is abandoned. Returns the updated subscription state, or 409 when there is no plan. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
Abandon checkout
Abandons an unfinished first payment for a paid plan; the organization stays on the plan it has. Returns the updated subscription state, or 409 when no payment is in progress. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
Update billing details
Replaces the organization's billing name, email, address and tax ID, creating its billing customer record on first use. Returns the saved details. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
Switch billing interval
Switches the plan between monthly and yearly billing from the next renewal; nothing is charged now, and Undo subscription change cancels the switch until then. Returns the updated subscription state; a plan with no yearly price returns 422, and one already billed that way, set to end, on a price set for you, in a free trial or with a change already scheduled returns 409. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
Preview an interval switch
Quotes what switching between monthly and yearly billing costs: nothing now, and the new period's amount from the next renewal, with no line items. It stores no quote, so `preview_id` is null. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
List invoices
Lists up to 100 of the organization's invoices, newest first, with amounts, status (including refunds), credit notes and document links. Returns an empty list when billing is not connected. Requires the Org Owner or Org Admin role.
List invoice lines
Returns one of the organization's invoices line by line: each line's description, amount, quantity and service period, plus the subtotal and total. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
Pay invoice
Pays an open invoice now with the organization's default card. Returns the invoice status, plus a client secret when the bank asks for 3D Secure; another organization's invoice returns 404, an invoice that is not open returns 409, and a declined card returns 402. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
List billing notices
Lists the organization's open billing notices, such as a failed payment or an expiring card, newest first. Requires the Org Owner or Org Admin role.
List payment methods
Lists the organization's saved payment methods, the default first. Returns an empty list when billing is not connected. Requires the Org Owner or Org Admin role.
Delete payment method
Removes a saved payment method, first promoting another card to default when needed. With `dry_run=1`, reports whether the delete would be refused and which method would become the default, without changing anything; a refused delete returns 409. Requires the Org Owner or Org Admin role.
Set default payment method
Makes a saved payment method the default that pays invoices and lets a failed Jaah AI auto-recharge run again; an expired card returns 422. Returns all payment methods. Requires the Org Owner or Org Admin role.
List hostings
Returns the organization's hostings, newest first: what each one is, whether it is a dedicated host, a shared node or a trial, how it is billed, its monthly price, the date it is paid until, its status (pending payment, active, past due, stopped, cancelling or terminated), when a cancelled one ends, and the actions open to it. Requires the Org Owner or Org Admin role.
Create setup intent
Starts saving a new payment method and returns the client secret the browser payment form uses to collect the card, including any 3D Secure step. Rate limited per user and per organization. Requires the Org Owner or Org Admin role.
Sync billing
Refreshes the organization's payment methods, subscription and open invoices from the payment provider at once, and makes the newest usable card the default when none is set. Returns the payment methods. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
Undo subscription change
Cancels a scheduled downgrade, cancellation or billing interval switch, keeping the current plan. Returns the updated subscription state. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
List bundles
Lists the nodes your plan includes, one entry per node, each with its status: provisioning, failed, ready, removed, stopping, stopped, kept or terminated. A node your plan no longer includes shows when it stops and the monthly price to keep it. Open to any organization member.
Get Jaah AI wallet
Returns the organization's Jaah AI balance, the balance at which work pauses, the low-balance alert, mode, auto-recharge settings, prices, recent top-ups and recent ledger entries. Requires the Org Owner or Org Admin role.
Get Jaah AI ledger
Lists the organization's Jaah AI ledger between `from` and `to`, newest first, each day's usage folded into one row. Pages with `limit` and the `before` and `before_id` values of the previous page's last row. Requires the Org Owner or Org Admin role.
Set Jaah AI low-balance threshold
Sets the balance at which the organization gets a low-balance alert; a value below the pause point returns 422. Returns the wallet. Requires the Org Owner or Org Admin role.
Set Jaah AI mode
Switches the organization between running work on the Jaah AI account (`jaah`) and on its own agent accounts (`own`), and returns the wallet. Switching to `jaah` needs a plan that includes Jaah AI (else 403) and a balance above the pause point or a default card; any other refusal to switch returns 409. Requires the Org Owner or Org Admin role.
Refund a Jaah AI top-up
Refunds up to the unspent paid credit to the cards that paid it, returning the amount refunded, why any remainder was not, and the wallet. Returns 422 while auto-recharge is on or when the refund is refused, and 409 while another refund runs; a refused refund moves nothing. Requires the Org Owner or Org Admin role, and returns 429 past its rate limit: see Rate limits.
Get Jaah AI usage
Returns the organization's Jaah AI spend and usage between `from` and `to`, grouped by task, epic, project, user or model, with a total and a daily series cut in the `tz` time zone. At most 200 groups, biggest spend first; past that the last row, key `others`, sums the rest and `folded` counts them. Requires the Org Owner or Org Admin role.
Get organization plan
Returns the caller's organization plan, the plan catalogue with prices, and each plan limit with current usage. Open to any organization member; subscription details appear only for Org Owners, Org Admins and members allowed to view finance.
Get agents in use
Returns what the caller's organization's Agents limit counts now: the agents in use and the limit, the tasks holding them that the caller can see (a step of an epic names its epic), how many the caller cannot see, and the live console sessions. Open to any organization member; a staging organization counts over its parent too.
Choose plan
Selects the Trial plan and returns the organization plan; paid plans are bought with a subscription, so any other plan returns 422. Records only the first choice. Requires the Org Owner or Org Admin role.
Get trial agents
Returns the agents meter of the caller's organization on any plan: the most agents wanted at once in the last 7 days (counted afresh when the agents bought change or a trial starts), the agents running now, the agents bought on a per-agent plan or else the plan's Agents limit (`paid` says which), and the agent cap in force, with the trial's end during a free trial. An organization with no agents bought on a per-agent plan and an unlimited Agents limit gets trialing false and no figures. Open to any organization member; a staging organization reads its parent's.
List your products
Lists what your organization holds (`held`: every product not ended, with how it is paid, its status, its price and the actions you may take) and, for an Org Owner or Org Admin, the self-serve products you may buy (`buy`; empty for any other member).
Buy a product
Buys a self-serve product with your default card, or another of your cards named by `payment_method_id`: a one-off product is paid now, a monthly one pays its first month up front and then rides your add-ons bill; resend the same `request_id` after 3-D Secure to finish it. Returns the product held and the payment's status. Requires the Org Owner or Org Admin role; a plan is refused with 409, as it changes through the plan change.
Change the plan
Moves your organization to a plan, by its `plan_key`, with an agent count and a billing period. An upgrade or more agents is charged now and needs the `quote_id` of its quote, a cheaper plan, Free or another billing period waits for the end of the paid period, and in a free trial the change applies now with nothing charged; resend the same `request_id` after 3-D Secure to finish it. Requires the Org Owner or Org Admin role; returns 409 for a plan you cannot pick or one you already hold, and 429 past its rate limits: see Rate limits.
Quote a plan change
Returns what moving your organization to a plan, by its `plan_key`, with an agent count and a billing period costs: `change` names the kind of change (subscribe, upgrade, downgrade, agents, interval, end, keep or trial), `total` is due today, and `next_at` and `next_total` say when it applies and the charge then. Requires the Org Owner or Org Admin role; returns 409 for a plan you cannot pick and 429 past its rate limit: see Rate limits.
Quote a product
Returns what a selection of a self-serve product costs now: the interval it bills, the quantity, the unit price and the total charged today (a monthly product's first month). Requires the Org Owner or Org Admin role. A plan is refused with 409: it changes through the plan change.
Get a product's settings
Returns your organization's settings of one product and the schema they follow. Returns 404 for a product with no settings. Requires the Org Owner or Org Admin role.
Set a product's settings
Replaces your organization's settings of one product, checked against its schema; no product needs to be held. Requires the Org Owner or Org Admin role.
Remove a product
Removes a product you bought by card now: a monthly one's unused days are credited on your next bill (refunded to your card when nothing else is billed with it), a paid one-off keeps its payment, and an unpaid one's invoice is voided. Returns the product held. Requires the Org Owner or Org Admin role.
Cancel, keep or retry a product
Cancels a monthly product you bought at the end of its paid period (`cancel`), keeps one you cancelled (`undo`), or pays a failed payment again (`retry`). Returns the product held. Requires the Org Owner or Org Admin role.
List product kinds
Lists every kind of product Jaah sells, in order, with its label, the choices its products are sold along and the extra fields a buyer fills in. Any signed-in user may call it.
List public plans
Lists every plan you can sign up for, in catalogue order: its name, description, monthly price (`amount_cents` 0 is Free; per agent when `per_agent`, at least `min_agents`), yearly price, free trial, how long it lasts (`duration_days`, null is no end), bundled products, caps (null is unlimited) and included features; then what each hosted machine costs per month. Public: no account needed, any site may call it, and answers may be cached for 5 minutes.
Get hosting catalog
Returns what the organization may host and at what price: whether each way to host (a dedicated host, a shared node) is offered and, when not, why; the offered instance types, storage sizes and shared tiers with their monthly prices; the saved default card; and the recommended way to add a node. Requires the Org Owner or Org Admin role.
Delete hosting
Deletes a hosting now: its machine is removed and the unused days of a monthly hosting are credited on the next invoice. Returns the hosting. Requires the Org Owner or Org Admin role.
Cancel hosting
Cancels a monthly hosting at renewal: it keeps running until the end of the month already paid, nothing more is billed for it, and it then stops. Returns the hosting. Requires the Org Owner or Org Admin role.
Get hosting change options
Returns what an active monthly dedicated hosting may change to: every offered instance type (current, available, or needing a new machine and why) and every storage size (only larger ones can be picked), its current product, and how many sessions are running on it. Requires the Org Owner or Org Admin role.
Quote a hosting change
Quotes changing a dedicated hosting to another instance type and/or more storage: the new monthly price and the amount due now (negative is credited to the next bill) as Stripe computes it, held for 10 minutes, and whether the change needs a new machine. Requires the Org Owner or Org Admin role.
Cancel a hosting change
Cancels a quoted hosting change, or one whose payment is still waiting on the bank's confirmation: nothing changes. Requires the Org Owner or Org Admin role.
Confirm a hosting change
Pays a quoted hosting change: the old product ends and the new one starts now, and the machine changes once the payment succeeds (a change that needs a new machine requires `reprovision_confirmed`). When the bank asks to confirm, `payment` carries the client secret and you call again once confirmed. Requires the Org Owner or Org Admin role.
Resume hosting
Resumes a hosting: a cancelled one is kept, and one stopped by a cancellation or the end of a trial is charged a full month now (default card, or `payment_method_id`) and started; when the bank asks to confirm, `payment` carries the client secret and you call again once confirmed. A hosting stopped for non-payment resumes only by paying its open invoice (409). Requires the Org Owner or Org Admin role.
List a hosting's running sessions
Lists the sessions running now on a dedicated hosting's nodes, oldest first, with each one's node, task and start time. Requires the Org Owner or Org Admin role.
Undo hosting cancellation
Keeps a hosting that was cancelled at renewal, as long as its paid month has not ended. Returns the hosting. Requires the Org Owner or Org Admin role.