ax credit | AX Documentation

Inspect org prepaid credit balance and usage spend for one billing cycle, and buy more prepaid credit. Amounts are USD-denominated prepaid credits reported in micros (1 credit dollar = 1_000_000 micros).

Command	Use
`credit balance`	Org prepaid balance for one cycle (admin only).
`credit spend`	Usage spend for one cycle (members are self-scoped).
`credit reload`	Buy prepaid credit via Stripe Checkout (admin only).

Requires credentials from ax auth login (or AX_API_KEY) and an active org (ax org switch). Every subcommand accepts --org <org-id> to target another org without changing the saved active org.

Authorization

Who	`credit balance`	`credit spend`	`credit reload`
Org admin	Full org balance for the selected cycle.	Org spend; may group/filter by user or experiment.	May buy credit for the org.
Org member	Denied (permission error).	Personal spend only. The platform always scopes results to you.	Denied (permission error), matching the Billing UI.

Member-restricted spend flags error with permission denied:

--group-by user — members cannot group by user (use experiment, or omit).
--user <id-or-email> for another person — members may only omit --user or pass their own id/email; any other identity is denied without revealing whether that user exists.

Billing period

credit balance and credit spend select one org UTC calendar billing cycle with --period:

Value	Meaning
`current`	Default. Cycle containing now; if none is open, the newest cycle.
`previous`	Cycle immediately before the current selection.
`YYYY-MM`	Cycle whose period start falls in that UTC calendar month (strict two-digit month).

Invalid period tokens fail with a bad-request error. A period with no matching cycle fails as not found.

Money and JSON

Exact balances and spend stay decimal integer micros as JSON strings (never JSON numbers), so large values stay exact for scripts.
Human (non---json) output formats micros as currency (for example $1.50).
Do not treat totals as a separate “available to spend” wallet beyond what the response fields mean: balance is ledger remaining as of a point in time; spend is usage cost attributed in the cycle window.

`credit balance`

Show org prepaid credit balance for one billing cycle. Org admin only.

ax credit balance [--json] [--period <current|previous|YYYY-MM>] [--org <ORG_ID>]

Flag	What it does
`--json`	Emit JSON instead of a label block.
`--period <…>`	Billing cycle selector (default `current`).
`--org <org-id>`	Use this org without changing the active CLI org.

Output

Field	Meaning
Period / `period_start`, `period_end`	Selected cycle window.
Billing cycle / `billing_cycle_id`	Cycle id.
As of / `as_of`	Instant the balance is computed for: now while the cycle is still open; cycle end for a closed cycle.
Currency / `currency`	Currency code (USD).
Total / free / plan paid / paid balance	Remaining prepaid credit by bucket at `as_of` (micros in JSON).
Cycle funded / `cycle_funded_micros`	Funding attached to this cycle for the full cycle (not truncated to `as_of`).

Example:

ax credit balance
ax credit balance --period previous --json
ax credit balance --period 2026-06 --org 01KSDQ...

`credit spend`

Show usage spend for one billing cycle. Admins see org-wide totals (optionally grouped or filtered). Members always receive only their own spend.

ax credit spend [--json] [--period <current|previous|YYYY-MM>] \
  [--group-by experiment|user] [--experiment <ID|NAME>] [--user <ID|EMAIL>] \
  [--include-byok] [--org <ORG_ID>]

Flag	What it does
`--json`	Emit JSON instead of human text / table.
`--period <…>`	Billing cycle selector (default `current`).
`--group-by experiment\|user`	Break spend into series by experiment or user. User grouping is admin only.
`--experiment <id\|name>`	Limit to one experiment (id or exact display name).
`--user <id\|email>`	Limit to one user (Clerk user id or email). Admin only for another identity; members may only pass themselves or omit.
`--include-byok`	Include separate BYOK attribution totals (never mixed into managed spend).
`--org <org-id>`	Use this org without changing the active CLI org.

Managed spend vs BYOK

Managed spend is 514-managed usage cost for the cycle (same idea as the platform Usage view): priced managed model usage plus infrastructure run charges in the cycle window. It is not mixed with BYOK.
BYOK attribution (--include-byok) is a separate total for bring-your-own-key usage cost. It is reported alongside managed spend and is never added into managed spend fields.
Without --include-byok, BYOK totals are omitted from human output and are zero in JSON.

Output

Field	Meaning
Period / billing cycle / currency	Selected cycle metadata.
`group_by`, `experiment_id`, `user_id`	Echo of effective grouping/filters (empty when unused).
Managed spend / `total_managed_spend_micros`	Sum of managed spend for the result set.
BYOK attribution / `total_byok_attribution_micros`	Sum of BYOK attribution when requested.
`series`	Optional breakdown rows (`key`, `label`, managed micros, optional BYOK micros). Grouped output prints a table in human mode.

Examples:

# Member or admin: your personal spend for the current cycle
ax credit spend

# Admin: org spend by experiment, including BYOK attribution
ax credit spend --group-by experiment --include-byok --json

# Admin: one teammate in a prior cycle
ax credit spend --user dana@acme.com --period previous

# Filter to one experiment by name
ax credit spend --experiment "gateway-smoke" --group-by experiment

`credit reload`

Buy prepaid credit for the org. Org admin only.

The CLI asks the platform to mint a hosted Stripe Checkout session (mode: payment) — the same session the web Buy credits flow creates — then prints the Checkout URL and opens it in your default browser. Payment always completes in the browser on Stripe; the terminal never handles card details, and credit is posted by the existing Stripe webhook once the session is paid.

ax credit reload --amount <USD> [--no-open] [--json] [--org <ORG_ID>]

Flag	What it does
`--amount <USD>`	Required. Credit amount in USD with at most two decimal places (`50`, `49.99`).
`--no-open`	Print the Checkout URL without launching a browser. Implied when stdout is not a TTY.
`--json`	Emit a machine-readable session handoff instead of human text.
`--org <org-id>`	Use this org without changing the active CLI org.

The amount must be between $5 and $5,000 — the same bounds as the web custom-amount purchase. Malformed amounts (negatives, more than two decimals, exponents, thousands separators) are rejected during argument parsing and exit with the usage code 2.

Agent and CI runs

When stdout is not a terminal, --no-open is implied: the command prints the Checkout URL (or JSON) and exits without trying to launch a browser. An agent should hand that URL to a human to complete payment.

Output

Human:

Open Stripe Checkout to buy $50.00 in credits:
https://checkout.stripe.com/c/pay/cs_…

--json:

{
  "url": "https://checkout.stripe.com/c/pay/cs_…",
  "session_id": "cs_…",
  "org_id": "org_…",
  "amount": "50.00",
  "amount_micros": "50000000",
  "currency": "usd"
}

amount is a canonical two-decimal dollar string and amount_micros is exact integer micros — money is never a JSON number on this surface, matching credit balance and credit spend.

Errors

Case	Exit	What you see
Not logged in / no active org	1	The usual CLI auth error plus `ax auth login`.
Not an org admin	1	`permission denied: …` (same rule as the Billing UI).
Missing or malformed `--amount`	2	clap usage error naming `--amount`.
Amount outside the purchase range	1	`bad request: amount must be from $5 to $5000 …`.
Stripe session could not be created	1	The safe upstream reason; never secrets.

Examples:

# Buy $50 of credit and open Checkout in the browser
ax credit reload --amount 50

# Print the URL only (agents, CI, remote shells)
ax credit reload --amount 49.99 --no-open

# Machine-readable handoff for another org
ax credit reload --amount 250 --json --org 01KSDQ...

Out of scope for this command: auto-reload setup, plan upgrades, and the Stripe Customer Portal all stay in the billing UI.

Search documentation