billing - floo

Prepaid balance, spend caps, usage, funding, and auto top-up for the CLI’s current org.

balance

Read committed prepaid balance, pending funding, current spend headroom, and recorded billing recovery.

floo billing balance
floo billing balance --json

funding_eligible reports whether the organization can add prepaid funds. Pending funding becomes available after payment settlement. activation is dormant, scheduled, or active; it describes prepaid billing activation. Settled funds alone do not establish spend authority. authority reports the current headroom, limiting condition, and observation time. A hard-limit block requires a limit change; adding funds does not raise the limit. Metering delays can cause charges to appear later; they do not alone stop a funded account. enforcement records whether workload stops or recovery have caught up with the latest billing decision. Cleared billing restrictions do not establish that an app is healthy. Check the app’s status separately. When the API does not return authority or enforcement, the CLI reports that information as unavailable.

JSON output

{
  "success": true,
  "data": {
    "billing_mode": "prepaid",
    "funding_eligible": true,
    "activation": "active",
    "usage_started_at": "2026-09-26T12:00:00Z",
    "pending_nanodollars": "10000000000",
    "balance_nanodollars": "25000000000",
    "recorded_at": "2026-09-26T12:00:00Z",
    "authority": {
      "state": "available",
      "binding_authority": "funds",
      "balance_sequence": 3,
      "funds_remaining_nanodollars": "25000000000",
      "period_usage_nanodollars": "0",
      "hard_limit_nanodollars": "50000000000",
      "remaining_nanodollars": "25000000000",
      "observed_at": "2026-09-26T12:01:00Z"
    },
    "enforcement": {
      "desired_blocked": false,
      "generation": 2,
      "applied_generation": 1
    }
  }
}

Money fields are exact decimal integer strings: 1,000,000,000 nanodollars equals $1. A negative balance remains negative. recorded_at identifies the latest committed balance observation and can be null before one exists. In this example, spending has headroom, but the latest cleared billing decision has not been recorded as applied. Check app status separately. When funding_eligible is true, use floo billing upgrade to add funds. The same command opens the billing page to inspect the organization’s billing state. Use floo billing spend-cap get to inspect your usage limit. A paid checkout return alone does not confirm that funds are available.

notifications

Read retained billing emails and their submission outcomes.

floo billing notifications
floo billing notifications --limit 20 --json

Each record contains the frozen subject and plain-text body, billing state, first and last submission attempts, provider_accepted, and closed_reason. Provider acceptance does not confirm inbox delivery. A closed reason of acceptance_unresolved means the submission outcome is unknown. The command reads one page: 20 records by default, up to 100 with --limit. When next_before_id is non-null, pass it as --before-id to read older records. An empty records array means no emails were recorded for that page; a failed read reports an error. Email history describes earlier observations. Use floo billing balance for current spending authority and check your apps for their current status.

spend-cap get

Current spend cap and spend this period.

floo billing spend-cap get

  Spend cap: $50.00/month
  Current spend: $12.34

When the cap is exceeded, the command adds a warning naming what the org’s protection mode blocks: nothing (alerts_only), new deploys (freeze_new_spend), or deploys plus running services, which scale to zero (hard_stop).

JSON output

{
  "success": true,
  "data": {
    "spend_cap_cents": 5000,
    "current_period_spend_cents": 1234,
    "spend_cap_exceeded": false,
    "spend_cap_policy": "freeze_new_spend",
    "deploys_blocked": false
  }
}

Values are in cents. spend_cap_cents is null when no cap is set. Use floo billing usage for the plan, the plan maximum, and the per-app breakdown.

spend-cap set

Set the monthly spend cap in dollars. Pay as you go requires a positive amount and uses hard_stop; 0 is rejected with PREPAID_HARD_LIMIT_REQUIRED. For subscription billing, 0 removes the cap.

floo billing spend-cap set 50

Arguments

Argument	Description
`AMOUNT`	Monthly spend cap in dollars, from $0 to $1,000,000. Use `0` to remove the cap on subscription billing only.

Examples

# Set a $50/month cap
floo billing spend-cap set 50

# Subscription billing only: remove spend cap
floo billing spend-cap set 0

# Agent workflow: set cap and confirm
floo billing spend-cap set 100 --json 2>/dev/null | jq -r '.data.spend_cap'

JSON output

{
  "success": true,
  "data": {
    "spend_cap": 5000,
    "policy": "freeze_new_spend"
  }
}

spend_cap is in cents and is null after an accepted subscription set 0. Prepaid responses use policy: "hard_stop"; prepaid accounts cannot disable protection or choose a weaker policy. The JSON example above is a subscription response. policy is the budget-protection mode floo applies when spend reaches the cap: alerts_only, freeze_new_spend, hard_stop, or off when no cap is set. The CLI has no flag for the mode: setting a cap keeps the org’s current mode, or applies freeze_new_spend when protection was off. Change the mode in the dashboard. See Billing and spend caps for what each mode does.

auto-top-up get

Read whether auto top-up is on, its threshold and amount, and why it is off. Only org admins can run this command.

floo billing auto-top-up get
floo billing auto-top-up get --json

JSON output

{
  "success": true,
  "data": {
    "enabled": true,
    "off_reason": null,
    "threshold_cents": 500,
    "amount_cents": 2500
  }
}

off_reason is null, customer (an admin turned it off), charge_failed (the card was declined), or needs_purchase (no credit purchase has authorized top-ups). amount_cents is the org’s last credit purchase amount, or null. The $5 threshold and purchase-based amount are not configurable. See Auto top-up for when the card is charged.

auto-top-up on

Turn auto top-up on and print the resulting state. Only org admins can run this command.

floo billing auto-top-up on

Before a credit purchase has authorized top-ups, the command fails with AUTO_TOP_UP_NEEDS_PURCHASE. Add credits once with floo billing upgrade.

auto-top-up off

Turn auto top-up off and print the resulting state. Only org admins can run this command.

floo billing auto-top-up off

Org admins can also turn auto top-up off or on on the dashboard Billing page. Saved-card charges for unpaid usage continue at month-end or when unpaid usage reaches $25.

upgrade

Opens the dashboard billing page for the CLI’s current org to pick a plan, add prepaid funds, or check recovery. An org without a plan lands on the plan picker.

floo billing upgrade

Plans and what they include are on getfloo.com/pricing.

JSON output

With --json, the CLI prints the URL instead of opening a browser:

{
  "success": true,
  "data": {
    "url": "https://app.getfloo.com/billing?org_id=..."
  }
}

Subscription plan changes take effect at a billing-period boundary. Prepaid organizations cannot start self-serve subscription checkout; contact support to change billing models.

usage

Plan, included credits, spend for the period, spend cap with a progress bar, per-app totals, and recorded cost lines.

floo billing usage

  Plan: paygo
  floo credits included: 0.00/month
  Compute used: $12.34 (Current month)
  Spend cap: $50.00/month
  Usage: 25% of cap
  ████████░░░░░░░░░░░░░░░░░░░░░░  25%

Flags

Flag	Description	Default
`--period PERIOD` / `-p PERIOD`	Compute-cost window: `current_month`, `last_month`, or `last_7d`	`current_month`

Warm instance cost

Web and API services scale to zero when min_instances is omitted on every plan and in every environment, including production. A warm instance bills continuously, even while idle. Rates are on getfloo.com/pricing; Scaling and availability has the verification commands. Set min_instances = 1 or higher in floo.app.toml to keep instances warm.

JSON output

{
  "success": true,
  "data": {
    "plan": "paygo",
    "spend_cap_cents": 5000,
    "max_spend_cap_cents": null,
    "period_spend_cents": 1234,
    "spend_cap_exceeded": false,
    "spend_cap_policy": "hard_stop",
    "deploys_blocked": false,
    "period": "current_month",
    "total_cost_usd": 12.34,
    "included_cost_usd": 0.0,
    "apps": [],
    "lines": []
  }
}

cost-breakdown

Inspect one app’s service and managed-resource costs:

floo billing cost-breakdown --app my-app
floo billing cost-breakdown --app my-app --period last_month --json

--period accepts current_billing_period, current_month (default), last_month, or last_7d. --app is inferred from local config when omitted.

Errors

Code	Meaning
`NOT_AUTHENTICATED`	Run `floo auth login` first
`INVALID_AMOUNT`	Spend cap must be between $0 and $1,000,000
`AUTO_TOP_UP_NEEDS_PURCHASE`	No credit purchase has authorized top-ups. Add credits once with `floo billing upgrade`
`PREPAID_HARD_LIMIT_REQUIRED`	Pay as you go requires a positive hard limit and the `hard_stop` policy
`SPEND_AUTHORITY_EXHAUSTED`	Inspect `floo billing balance` for the limiting condition; add credits or raise the hard limit as required
`SPEND_CAP_EXCEEDS_PLAN_LIMIT`	The cap is above your plan’s maximum. Upgrade to raise it

​balance

​JSON output

​notifications

​spend-cap get

​JSON output

​spend-cap set

​Arguments

​Examples

​JSON output

​auto-top-up get

​JSON output

​auto-top-up on

​auto-top-up off

​upgrade

​JSON output

​usage

​Flags

​Warm instance cost

​JSON output

​cost-breakdown

​Errors

balance

JSON output

notifications

spend-cap get

JSON output

spend-cap set

Arguments

Examples

JSON output

auto-top-up get

JSON output

auto-top-up on

auto-top-up off

upgrade

JSON output

usage

Flags

Warm instance cost

JSON output

cost-breakdown

Errors